@agent-native/core 0.85.7 → 0.86.1

package/docs/content/template-plan.mdx

@@ -6,11 +6,11 @@ description: "Agent-Native Plans turns your coding agent's plan into a structure
 # Visual Plans
 
 > **Most people install Plan as a skill, not a scaffolded app.** One CLI command
-> adds the `/visual-plan` and `/visual-recap` skills plus the hosted Plan
-> connector to your coding agent — see [Plan plugin & marketplace](/docs/plan-plugin)
-> for the plugin and marketplace routes. Forking the Plan template (covered under
-> [For developers](#for-developers)) is the secondary path, for self-hosting or
-> building on Plan itself.
+> adds the `/visual-plan`, `/visual-recap`, and `/visualize-repo` skills plus
+> the hosted Plan connector to your coding agent — see
+> [Plan plugin & marketplace](/docs/plan-plugin) for the plugin and marketplace
+> routes. Forking the Plan template (covered under [For developers](#for-developers))
+> is the secondary path, for self-hosting or building on Plan itself.
 
 Agent-Native Plans is visual plan mode for coding agents. It turns an ordinary
 Codex, Claude Code, Markdown, or pasted implementation plan into a structured
@@ -115,7 +115,8 @@ hit an OAuth wall:
 npx @agent-native/core@latest skills add visual-plan
 ```
 
-The command installs both commands: `/visual-plan` and `/visual-recap`.
+The command installs three commands: `/visual-plan`, `/visual-recap`, and
+`/visualize-repo`.
 
 If you are using a chat-based host that accepts MCP connector URLs directly
 (rather than a CLI-configured client), connect the hosted Plans connector at
@@ -358,6 +359,35 @@ and commenting, and returns the hosted URL. Local-files mode does not
 automatically make your coding agent's LLM local; choose a local or approved
 model if that privacy boundary matters too.
 
+## Repo visual docs {#visualize-repo}
+
+Use `/visualize-repo` when you want a durable visual documentation layer for a
+codebase instead of a one-off plan or recap. It creates or opens a local Plan
+MDX workspace, updates `agent-native.json` with an `apps.visualize-repo`
+local-files section, and serves the docs through the same localhost bridge:
+
+```bash
+npx @agent-native/core@latest visualize-repo --open
+```
+
+If no `agent-native.json` exists, the command bootstraps one and recommends a
+small starter set from the repo structure, such as `actions/`,
+`app/components/`, `app/pages/`, `server/db/schema.ts`, `src/`, `packages/`,
+`templates/`, `docs/`, or `content/`. You can target specific source anchors:
+
+```bash
+npx @agent-native/core@latest visualize-repo \
+  --target actions/webhooks.ts \
+  --target server/db/schema.ts \
+  --target app/components/PromptComposer.tsx
+```
+
+The starter folder lives at `.agent-native/visual-docs/repo-overview` by
+default. Comments stay local in `comments.json`, so reviewers can mark sections
+for a coding agent and the agent can update both code and MDX in the same
+change. Run `visualize-repo check` for local lint, and `visualize-repo verify`
+when you want the Plan renderer schema to validate the MDX.
+
 ## Desktop local file sync {#desktop-local-sync}
 
 Agent Native Desktop also gives hosted Plans a native local-folder bridge. This
@@ -409,6 +439,7 @@ touch local files.
 - "Run `/visual-recap` on this PR so I can review the shape of the change first."
 - "Use `/visual-recap` on the diff between `main` and this branch."
 - "Use `/visual-recap` in local-files mode so no recap content is written to the Plan DB."
+- "Run `/visualize-repo` and start with our public API actions and schema."
 
 ## Recovering from auth errors {#auth-errors}
 

package/docs/content/tracking.mdx

@@ -235,7 +235,7 @@ Privacy defaults are intentionally conservative but still useful for playback:
 - URLs are scrubbed with the same `scrubUrl()` helper used by browser analytics.
 - Replay capture is web-only and opt-in; it does not record native desktop screens.
 
-While recording, session replay also captures browser console output (`log`, `info`, `warn`, `error`, `debug`, plus window `error` / `unhandledrejection`) and network request metadata (`fetch` and XHR) as tagged rrweb custom events, so agents and the replay viewer can debug user-reported issues. Capture is on by default when replay is enabled; tune or disable it with the `sessionReplay.console` and `sessionReplay.network` options, each accepting a boolean or an options object (`{ maxEvents?: number }`). Request/response bodies and headers are never captured, URLs are scrubbed, messages are truncated, the recorder's own ingest/tracking traffic is excluded, and per-session budgets (1000 console / 2000 network events) add a truncation notice when exceeded.
+While recording, session replay also captures browser console output (`log`, `info`, `warn`, `error`, `debug`, plus window `error` / `unhandledrejection`) and network request metadata (`fetch` and XHR) as tagged rrweb custom events, so agents and the replay viewer can debug user-reported issues. Capture is on by default when replay is enabled; tune or disable it with the `sessionReplay.console` and `sessionReplay.network` options, each accepting a boolean or an options object (`{ maxEvents?: number }`, with `network` additionally accepting `captureErrorBodies` and `maxErrorBodyLength`). Request bodies and headers are never captured; response bodies are captured only as a bounded, redacted snippet for 5xx (server error) responses (`captureErrorBodies`, default true, capped at `maxErrorBodyLength` chars, default 2048) — non-5xx and network-failure responses never carry a body. URLs are scrubbed, messages are truncated, the recorder's own ingest/tracking traffic is excluded, and per-session budgets (1000 console / 2000 network events) add a truncation notice when exceeded.
 
 The Analytics template stores replay metadata in SQL (`session_recordings`) and stores chunks through private blob refs (`session_replay_chunks`). Browsers and agents never receive provider URLs. Playback goes through scoped server routes and the default agent tools return summaries or bounded replay events, not raw chunk table access.
 

package/docs/content/workspace-connections.mdx

@@ -264,7 +264,7 @@ The initial provider ids are:
 | `google_drive` | search, import, docs           | brain, content, slides         |
 | `hubspot`      | search, import, crm            | analytics, brain, mail         |
 | `granola`      | search, import, meetings, docs | brain, calendar, dispatch      |
-| `clips`        | search, import, meetings       | brain, clips, videos           |
+| `clips`        | search, import, meetings       | brain, clips                   |
 | `generic`      | search, import, docs           | custom webhooks and file drops |
 
 Credential keys are names only, such as `SLACK_BOT_TOKEN` or `GITHUB_TOKEN`. Provider metadata must never include actual credential values.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.85.7",
+  "version": "0.86.1",
   "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": {
@@ -63,6 +63,7 @@
     },
     "./agent-web": "./dist/agent-web/index.js",
     "./db": "./dist/db/index.js",
+    "./db-admin": "./dist/db-admin/index.js",
     "./db/schema": "./dist/db/schema.js",
     "./db/drizzle-config": "./dist/db/drizzle-config.js",
     "./client": "./dist/client/index.js",
@@ -204,8 +205,8 @@
     "@radix-ui/react-popover": "^1.1.15",
     "@radix-ui/react-select": "^2.2.6",
     "@radix-ui/react-tooltip": "^1.2.8",
-    "@react-router/dev": "^8.0.1",
-    "@react-router/fs-routes": "^8.0.1",
+    "@react-router/dev": "^8.1.0",
+    "@react-router/fs-routes": "^8.1.0",
     "@resvg/resvg-js": "^2.6.2",
     "@rrweb/record": "2.0.1",
     "@sentry/browser": "10.60.0",
@@ -280,8 +281,8 @@
     "@assistant-ui/tap": "^0.5.14",
     "@excalidraw/excalidraw": "0.18.1",
     "@excalidraw/mermaid-to-excalidraw": "2.2.2",
-    "@react-router/dev": "^8.0.1",
-    "@react-router/fs-routes": "^8.0.1",
+    "@react-router/dev": "^8.1.0",
+    "@react-router/fs-routes": "^8.1.0",
     "@supabase/supabase-js": "^2.49.0",
     "@tabler/icons-react": "^3.40.0",
     "@tailwindcss/typography": "^0.5.20",
@@ -309,7 +310,7 @@
     "playwright": "^1.61.1",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
-    "react-router": "^8.0.1",
+    "react-router": "^8.1.0",
     "tailwindcss": "^4.2.4",
     "typescript": "^6.0.3",
     "vite": "8.1.0",

package/src/templates/default/.agents/skills/real-time-collab/SKILL.md

@@ -249,34 +249,97 @@ type PatchDeckOp =
 Concurrent edits to different slides both succeed at the action level; there
 is no whole-deck LWW. Forms use the same shape with field-level ops.
 
-## Collaborative Undo Scoping (Y.UndoManager)
+## Agent Presence & Lingering Edit Highlights
+
+The agent is a *visible* collaborator, not a silent content-swapper. Core
+handles most of this automatically:
+
+- **Auto-presence on agent writes** — any `applyText` / `searchAndReplace` /
+  `applyJson` / `applyPatchOps` call with `requestSource: "agent"` publishes
+  an agent awareness entry plus a `recentEdits` attribution describing what
+  changed. Actions that route writes through the collab layer get full
+  presence UX with zero extra wiring.
+- **Linger** — `agentLeaveDocument` (and the auto-presence path) keeps the
+  agent's awareness entry alive for ~6s (`AGENT_PRESENCE_LINGER_MS`) after the
+  last edit so viewers see who just changed what. Pass `{ lingerMs: 0 }` to
+  clear immediately. On serverless the linger degrades to the 30s awareness
+  expiry.
+- **`agentTouchDocument(docId, { edit, metadata })`** — refcount-neutral
+  presence + attribution for actions that write SQL directly (no collab doc).
+  `edit.descriptor` is one of `{kind:"text",quote}`, `{kind:"selector",selector}`,
+  `{kind:"paths",paths}`, `{kind:"doc"}`.
+- **Durable across instances** — awareness is mirrored to the additive
+  `_collab_awareness` table, so presence written by an action in one
+  serverless invocation is visible to clients polling any other instance.
+
+Client rendering:
+
+```tsx
+import {
+  usePresence, useRecentEdits, RecentEditHighlights,
+  PresenceBar, LiveCursorOverlay, RemoteSelectionRings,
+} from "@agent-native/core/client";
+
+const { others, setPresence } = usePresence(awareness, ydoc?.clientID);
+const recentEdits = useRecentEdits(others); // non-expired, ~6s TTL
+
+<RecentEditHighlights
+  edits={recentEdits}
+  containerRef={containerRef}
+  resolveRect={(edit) => /* map descriptor → DOMRect, or null */ null}
+/>
+```
+
+Humans get the same treatment: call `publishRecentEdit(awareness, { descriptor })`
+from local mutation paths so peers see lingering highlights for human edits
+too. `CollabUser.avatarUrl` puts faces on avatars, cursors, and edit tags.
+
+## Per-User Undo (never revert someone else's work)
 
-Scope undo/redo to the local user's own edits so peer and agent changes are
-never accidentally reversed:
+Undo must only reverse the local user's edits — and must never restore a
+whole-document snapshot (that clobbers concurrent edits by peers/the agent).
+Core ships two primitives:
+
+**Yjs surfaces — `useCollabUndo`** (wraps `Y.UndoManager` lifecycle):
 
 ```ts
-import * as Y from "yjs";
+import { useCollabUndo } from "@agent-native/core/client";
+
+const { undo, redo, canUndo, canRedo, transactLocal, localOrigin } =
+  useCollabUndo({
+    ydoc,
+    scope: (doc) => doc.getText("content"),
+    captureTimeout: 500,
+    enableKeyboardShortcuts: true, // Mod+Z / Shift+Mod+Z / Mod+Y
+  });
 
-const LOCAL_EDIT_ORIGIN = "local";
+// Tag every local mutation so it is captured:
+transactLocal(() => { /* mutate shared types */ });
+```
 
-const undoManager = new Y.UndoManager(ydoc.getText("content"), {
-  trackedOrigins: new Set([LOCAL_EDIT_ORIGIN]),
-  captureTimeout: 800, // coalesces rapid slider drags into one undo step
-});
+Remote (`"remote"`) and agent (`"agent"`/`"server"`) origins are never
+captured. The manager is recreated/destroyed automatically when `ydoc`
+changes. (TipTap's Collaboration extension already provides this behavior
+for its own editor content.)
 
-// Mark local edits with the tracked origin
-ydoc.transact(() => {
-  // apply local change
-}, LOCAL_EDIT_ORIGIN);
+**Op-based surfaces (slides/forms) — `useLocalOpUndo`**: record inverse
+granular ops for each local mutation; undo replays the inverse ops through
+your normal granular mutation path:
 
-undoManager.undo(); // only reverses LOCAL_EDIT_ORIGIN transactions
-undoManager.redo();
+```ts
+const { push, undo, redo, canUndo, canRedo } = useLocalOpUndo({
+  apply: (ops) => applyGranularOps(ops), // your patch path
+});
+
+push({
+  undo: [{ type: "patch", slideId, fields: prevFields }],
+  redo: [{ type: "patch", slideId, fields: nextFields }],
+  coalesceKey: `${slideId}:content`, // merge rapid bursts into one step
+});
 ```
 
-Rules:
-- Pass a `Set` to `trackedOrigins` — not an array.
-- Remote (`"remote"`) and agent (`"agent"`) origins are never captured.
-- Recreate and destroy the manager when the active document changes.
+Entries whose target no longer exists should fail soft (skip), never reset
+the whole history — external/agent edits must not wipe the user's undo stack.
 
 ## Common Pitfalls
 

package/src/templates/default/.agents/skills/real-time-sync/SKILL.md

@@ -58,6 +58,21 @@ The agent modifies data in SQL, but the UI runs in the browser. SSE bridges same
 
 - Don't create manual polling loops — `useDbSync()` handles SSE plus fallback polling
 - Don't create your own fetch-based polling alongside `useDbSync` — use the `onEvent` callback for custom handling
+- Don't open your own `EventSource` to `/_agent-native/events`. A tab must hold exactly ONE SSE connection no matter how many features listen — extra streams eat the browser's per-origin connection budget and can starve ordinary data fetches (worst on HTTP/1.1 dev servers). Subscribe to the shared transport instead:
+
+  ```ts
+  import { subscribeSyncEvents } from "@agent-native/core/client";
+
+  const unsubscribe = subscribeSyncEvents({
+    onEvents: (events) => {
+      // filter by event.source and handle push-style updates
+    },
+    // Optional: relax your own fallback cadence while push is healthy.
+    onSseStateChange: (connected) => {},
+  });
+  ```
+
+  `useDbSync` and every `subscribeSyncEvents` subscriber share one `EventSource` and one fallback poll loop per tab — this is how collaborative documents receive doc updates and cursor/awareness events.
 
 ## Which sources to depend on
 

package/src/templates/default/.agents/skills/storing-data/SKILL.md

@@ -25,6 +25,14 @@ Agent-native apps use Drizzle ORM over the configured SQL backend. Local develop
 
 For app code, use Drizzle's schema/query DSL by default. Raw SQL is an escape hatch for additive migrations, health checks, or one-off maintenance, not the normal way to build features.
 
+### Naming migrations
+
+When you add an entry to a `runMigrations([...])` list (`@agent-native/core/db`), always give it a unique `name:` slug (e.g. `name: "analytics-alert-rules-table"`) alongside its `version`. Never renumber or reuse version numbers on existing entries.
+
+Why: version numbers alone are not a safe identity. Two branches that each independently extend the same migration list can ship different DDL under the same version numbers — whichever branch deploys first "claims" those version numbers in the bookkeeping table, and the other branch's DDL is silently treated as already applied even though it never ran. This exact collision took down analytics: parallel branches both extended their migration list through v75-v83 with different DDL, so `analytics_alert_rules`, `analytics_alert_incidents`, and `session_recordings.network_error_count` never made it to production despite the bookkeeping table showing every version as applied. A `name:` slug is tracked independently of version numbers, so it applies exactly once per database regardless of what any other branch already recorded.
+
+Existing unnamed migrations don't need to be renamed retroactively (the two gating strategies coexist), but any new entry should always carry a name.
+
 ### Core SQL Stores (auto-created, available in all templates)
 
 | Store               | Purpose                                              | Access                                     |

package/src/templates/default/app/root.tsx

@@ -1,6 +1,7 @@
 import { useDbSync } from "@agent-native/core/client";
 import {
   AppProviders,
+  ErrorReportActions,
   appPath,
   getLocaleInitScript,
   getThemeInitScript,
@@ -66,6 +67,9 @@ const ERROR_COPY = {
       "This page doesn't exist. It may have been moved or deleted.",
     statusTitle: (status: number) => `${status} Error`,
     goHome: "Go home",
+    sendFeedback: "Send feedback",
+    feedbackPlaceholder: "Describe what happened before this error appeared.",
+    openGitHubIssue: "Open GitHub issue",
   },
   "zh-CN": {
     genericTitle: "出了点问题",
@@ -74,6 +78,9 @@ const ERROR_COPY = {
     notFoundDetails: "此页面不存在。它可能已被移动或删除。",
     statusTitle: (status: number) => `${status} 错误`,
     goHome: "返回首页",
+    sendFeedback: "发送反馈",
+    feedbackPlaceholder: "描述此错误出现前发生了什么。",
+    openGitHubIssue: "打开 GitHub issue",
   },
   "zh-TW": {
     genericTitle: "發生錯誤",
@@ -82,6 +89,9 @@ const ERROR_COPY = {
     notFoundDetails: "此頁面不存在，可能已被移動或刪除。",
     statusTitle: (status: number) => `${status} 錯誤`,
     goHome: "返回首頁",
+    sendFeedback: "傳送意見回饋",
+    feedbackPlaceholder: "描述此錯誤出現前發生了什麼。",
+    openGitHubIssue: "開啟 GitHub issue",
   },
   "es-ES": {
     genericTitle: "Algo salió mal",
@@ -91,6 +101,10 @@ const ERROR_COPY = {
       "Esta página no existe. Puede que se haya movido o eliminado.",
     statusTitle: (status: number) => `Error ${status}`,
     goHome: "Ir al inicio",
+    sendFeedback: "Enviar comentarios",
+    feedbackPlaceholder:
+      "Describe qué pasó antes de que apareciera este error.",
+    openGitHubIssue: "Abrir issue en GitHub",
   },
   "fr-FR": {
     genericTitle: "Une erreur est survenue",
@@ -100,6 +114,9 @@ const ERROR_COPY = {
       "Cette page n'existe pas. Elle a peut-être été déplacée ou supprimée.",
     statusTitle: (status: number) => `Erreur ${status}`,
     goHome: "Retour à l'accueil",
+    sendFeedback: "Envoyer un retour",
+    feedbackPlaceholder: "Décrivez ce qui s'est passé avant cette erreur.",
+    openGitHubIssue: "Ouvrir une issue GitHub",
   },
   "de-DE": {
     genericTitle: "Etwas ist schiefgelaufen",
@@ -109,6 +126,9 @@ const ERROR_COPY = {
       "Diese Seite existiert nicht. Sie wurde möglicherweise verschoben oder gelöscht.",
     statusTitle: (status: number) => `${status} Fehler`,
     goHome: "Zur Startseite",
+    sendFeedback: "Feedback senden",
+    feedbackPlaceholder: "Beschreiben Sie, was vor diesem Fehler passiert ist.",
+    openGitHubIssue: "GitHub-Issue öffnen",
   },
   "ja-JP": {
     genericTitle: "問題が発生しました",
@@ -118,6 +138,9 @@ const ERROR_COPY = {
       "このページは存在しません。移動または削除された可能性があります。",
     statusTitle: (status: number) => `${status} エラー`,
     goHome: "ホームへ",
+    sendFeedback: "フィードバックを送信",
+    feedbackPlaceholder: "このエラーの直前に起きたことを説明してください。",
+    openGitHubIssue: "GitHub issue を開く",
   },
   "ko-KR": {
     genericTitle: "문제가 발생했습니다",
@@ -127,6 +150,10 @@ const ERROR_COPY = {
       "이 페이지는 존재하지 않습니다. 이동되었거나 삭제되었을 수 있습니다.",
     statusTitle: (status: number) => `${status} 오류`,
     goHome: "홈으로 이동",
+    sendFeedback: "피드백 보내기",
+    feedbackPlaceholder:
+      "이 오류가 나타나기 전에 무슨 일이 있었는지 적어 주세요.",
+    openGitHubIssue: "GitHub issue 열기",
   },
   "pt-BR": {
     genericTitle: "Algo deu errado",
@@ -136,6 +163,9 @@ const ERROR_COPY = {
       "Esta página não existe. Ela pode ter sido movida ou excluída.",
     statusTitle: (status: number) => `Erro ${status}`,
     goHome: "Ir para o início",
+    sendFeedback: "Enviar feedback",
+    feedbackPlaceholder: "Descreva o que aconteceu antes deste erro aparecer.",
+    openGitHubIssue: "Abrir issue no GitHub",
   },
   "hi-IN": {
     genericTitle: "कुछ गलत हुआ",
@@ -144,6 +174,9 @@ const ERROR_COPY = {
     notFoundDetails: "यह पेज मौजूद नहीं है। इसे स्थानांतरित या हटाया गया हो सकता है।",
     statusTitle: (status: number) => `${status} त्रुटि`,
     goHome: "होम जाएं",
+    sendFeedback: "फ़ीडबैक भेजें",
+    feedbackPlaceholder: "इस त्रुटि से पहले क्या हुआ, उसका वर्णन करें।",
+    openGitHubIssue: "GitHub issue खोलें",
   },
   "ar-SA": {
     genericTitle: "حدث خطأ",
@@ -152,6 +185,9 @@ const ERROR_COPY = {
     notFoundDetails: "هذه الصفحة غير موجودة. ربما تم نقلها أو حذفها.",
     statusTitle: (status: number) => `خطأ ${status}`,
     goHome: "الذهاب إلى الرئيسية",
+    sendFeedback: "إرسال الملاحظات",
+    feedbackPlaceholder: "صف ما حدث قبل ظهور هذا الخطأ.",
+    openGitHubIssue: "فتح مشكلة في GitHub",
   },
 };
 
@@ -285,6 +321,17 @@ export function ErrorBoundary() {
         >
           {copy.goHome}
         </Link>
+        <ErrorReportActions
+          appName="Agent Native"
+          title={title}
+          details={details}
+          status={status}
+          issueTitle={`Error screen: ${title}`}
+          feedbackLabel={copy.sendFeedback}
+          feedbackPlaceholder={copy.feedbackPlaceholder}
+          githubLabel={copy.openGitHubIssue}
+          className="mt-4"
+        />
         {stack && (
           <pre className="mt-6 w-full text-left text-xs overflow-auto p-4 bg-muted rounded">
             <code>{stack}</code>

package/src/templates/default/package.json

@@ -23,8 +23,8 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@react-router/dev": "^8.0.1",
-    "@react-router/fs-routes": "^8.0.1",
+    "@react-router/dev": "^8.1.0",
+    "@react-router/fs-routes": "^8.1.0",
     "@tailwindcss/typography": "^0.5.20",
     "@tailwindcss/vite": "^4.1.18",
     "@tanstack/react-query": "^5.99.2",
@@ -38,7 +38,7 @@
     "oxfmt": "catalog:",
     "react": "catalog:",
     "react-dom": "catalog:",
-    "react-router": "^8.0.1",
+    "react-router": "^8.1.0",
     "sonner": "^2.0.7",
     "tailwind-merge": "^3.5.0",
     "tailwindcss": "^4.1.18",

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

@@ -36,8 +36,16 @@ method gives the UI, docs, and future agents one stable contract.
    | Agent chat context | Agent chat client helpers from `@agent-native/core/client` |
    | Ask the user a multiple-choice question from app code | `askUserQuestion` from `@agent-native/core/client` (renders inline in the agent panel; answer goes to the agent — do not build a custom modal) |
    | Live sync | `useDbSync`, `useChangeVersion`, `useChangeVersions` |
+   | Listen to the shared SSE/poll change stream | `subscribeSyncEvents` from `@agent-native/core/client` — never open a second `EventSource` to `/_agent-native/events` |
    | Extension iframe calls | `appAction`, `appFetch`, `extensionFetch` from the extension runtime |
 
+   Action fetch behavior: every `useActionQuery` / `useActionMutation` /
+   `callAction` request is bounded by a 60s timeout, and timeouts surface as
+   errors instead of retrying silently. `useActionQuery` cancels superseded
+   requests automatically via React Query's abort signal. For imperative
+   calls, `callAction(name, params, { method, signal, timeoutMs })` accepts an
+   `AbortSignal` and a `timeoutMs` override for legitimately long operations.
+
 2. If no client API exists, add the narrowest helper at the boundary.
 
    - Put shared framework helpers in `packages/core/src/client/*`.

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

@@ -232,3 +232,25 @@ This layer is optional and **no-op by default**:
 - Even with the api package installed, it ships a default no-op tracer. Spans become real only once the **host registers a `TracerProvider`** (via `@opentelemetry/sdk-node` or similar). The framework deliberately does not depend on the heavy SDK/exporter packages and never registers a provider itself — instrumentation is opt-in by the embedding app.
 
 The loop emits `agent.run` (with `agent.run_id`, `agent.thread_id`, `agent.user_id`, `agent.model`), `tool.call` (`tool.name` + status), and `llm.call` spans, each finished with OK/ERROR status. This is purely additive to the in-house `agent_trace_spans` / `agent_trace_summaries` tables. Source: `packages/core/src/observability/tracing.ts` + `traces.ts`. See the Observability doc for the full table.
+
+## Tracking Bridge
+
+Instrumented agent loops also emit one server-side tracking event per completed
+LLM generation:
+
+- Event name: `$ai_generation`
+- Provider path: `track()` from `@agent-native/core/tracking`, so configured
+  PostHog, Agent Native Analytics, Mixpanel, Amplitude, and webhook providers
+  receive it through the same best-effort fan-out as other tracking events.
+- PostHog shape: uses AI Observability properties such as `$ai_trace_id`,
+  `$ai_session_id`, `$ai_model`, `$ai_provider`, `$ai_input_tokens`,
+  `$ai_output_tokens`, `$ai_latency`, `$ai_total_cost_usd`, and `$ai_is_error`.
+- Agent Native Analytics shape: the same event lands in `analytics_events` with
+  mirrored query-friendly properties such as `run_id`, `thread_id`,
+  `cost_cents_x100`, `duration_ms`, `tool_calls`, `successful_tools`,
+  `failed_tools`, and `status`.
+
+Do not build a separate LLM-observability ingestion API unless there is a clear
+reason the tracking provider registry cannot express the use case. Keep prompt,
+tool input, and model output content out of tracking by default; use the existing
+observability config flags for local trace content capture.

package/src/templates/workspace-core/.agents/skills/real-time-collab/SKILL.md

@@ -249,34 +249,97 @@ type PatchDeckOp =
 Concurrent edits to different slides both succeed at the action level; there
 is no whole-deck LWW. Forms use the same shape with field-level ops.
 
-## Collaborative Undo Scoping (Y.UndoManager)
+## Agent Presence & Lingering Edit Highlights
+
+The agent is a *visible* collaborator, not a silent content-swapper. Core
+handles most of this automatically:
+
+- **Auto-presence on agent writes** — any `applyText` / `searchAndReplace` /
+  `applyJson` / `applyPatchOps` call with `requestSource: "agent"` publishes
+  an agent awareness entry plus a `recentEdits` attribution describing what
+  changed. Actions that route writes through the collab layer get full
+  presence UX with zero extra wiring.
+- **Linger** — `agentLeaveDocument` (and the auto-presence path) keeps the
+  agent's awareness entry alive for ~6s (`AGENT_PRESENCE_LINGER_MS`) after the
+  last edit so viewers see who just changed what. Pass `{ lingerMs: 0 }` to
+  clear immediately. On serverless the linger degrades to the 30s awareness
+  expiry.
+- **`agentTouchDocument(docId, { edit, metadata })`** — refcount-neutral
+  presence + attribution for actions that write SQL directly (no collab doc).
+  `edit.descriptor` is one of `{kind:"text",quote}`, `{kind:"selector",selector}`,
+  `{kind:"paths",paths}`, `{kind:"doc"}`.
+- **Durable across instances** — awareness is mirrored to the additive
+  `_collab_awareness` table, so presence written by an action in one
+  serverless invocation is visible to clients polling any other instance.
+
+Client rendering:
+
+```tsx
+import {
+  usePresence, useRecentEdits, RecentEditHighlights,
+  PresenceBar, LiveCursorOverlay, RemoteSelectionRings,
+} from "@agent-native/core/client";
+
+const { others, setPresence } = usePresence(awareness, ydoc?.clientID);
+const recentEdits = useRecentEdits(others); // non-expired, ~6s TTL
+
+<RecentEditHighlights
+  edits={recentEdits}
+  containerRef={containerRef}
+  resolveRect={(edit) => /* map descriptor → DOMRect, or null */ null}
+/>
+```
+
+Humans get the same treatment: call `publishRecentEdit(awareness, { descriptor })`
+from local mutation paths so peers see lingering highlights for human edits
+too. `CollabUser.avatarUrl` puts faces on avatars, cursors, and edit tags.
+
+## Per-User Undo (never revert someone else's work)
 
-Scope undo/redo to the local user's own edits so peer and agent changes are
-never accidentally reversed:
+Undo must only reverse the local user's edits — and must never restore a
+whole-document snapshot (that clobbers concurrent edits by peers/the agent).
+Core ships two primitives:
+
+**Yjs surfaces — `useCollabUndo`** (wraps `Y.UndoManager` lifecycle):
 
 ```ts
-import * as Y from "yjs";
+import { useCollabUndo } from "@agent-native/core/client";
+
+const { undo, redo, canUndo, canRedo, transactLocal, localOrigin } =
+  useCollabUndo({
+    ydoc,
+    scope: (doc) => doc.getText("content"),
+    captureTimeout: 500,
+    enableKeyboardShortcuts: true, // Mod+Z / Shift+Mod+Z / Mod+Y
+  });
 
-const LOCAL_EDIT_ORIGIN = "local";
+// Tag every local mutation so it is captured:
+transactLocal(() => { /* mutate shared types */ });
+```
 
-const undoManager = new Y.UndoManager(ydoc.getText("content"), {
-  trackedOrigins: new Set([LOCAL_EDIT_ORIGIN]),
-  captureTimeout: 800, // coalesces rapid slider drags into one undo step
-});
+Remote (`"remote"`) and agent (`"agent"`/`"server"`) origins are never
+captured. The manager is recreated/destroyed automatically when `ydoc`
+changes. (TipTap's Collaboration extension already provides this behavior
+for its own editor content.)
 
-// Mark local edits with the tracked origin
-ydoc.transact(() => {
-  // apply local change
-}, LOCAL_EDIT_ORIGIN);
+**Op-based surfaces (slides/forms) — `useLocalOpUndo`**: record inverse
+granular ops for each local mutation; undo replays the inverse ops through
+your normal granular mutation path:
 
-undoManager.undo(); // only reverses LOCAL_EDIT_ORIGIN transactions
-undoManager.redo();
+```ts
+const { push, undo, redo, canUndo, canRedo } = useLocalOpUndo({
+  apply: (ops) => applyGranularOps(ops), // your patch path
+});
+
+push({
+  undo: [{ type: "patch", slideId, fields: prevFields }],
+  redo: [{ type: "patch", slideId, fields: nextFields }],
+  coalesceKey: `${slideId}:content`, // merge rapid bursts into one step
+});
 ```
 
-Rules:
-- Pass a `Set` to `trackedOrigins` — not an array.
-- Remote (`"remote"`) and agent (`"agent"`) origins are never captured.
-- Recreate and destroy the manager when the active document changes.
+Entries whose target no longer exists should fail soft (skip), never reset
+the whole history — external/agent edits must not wipe the user's undo stack.
 
 ## Common Pitfalls
 

package/src/templates/workspace-core/.agents/skills/real-time-sync/SKILL.md

@@ -58,6 +58,21 @@ The agent modifies data in SQL, but the UI runs in the browser. SSE bridges same
 
 - Don't create manual polling loops — `useDbSync()` handles SSE plus fallback polling
 - Don't create your own fetch-based polling alongside `useDbSync` — use the `onEvent` callback for custom handling
+- Don't open your own `EventSource` to `/_agent-native/events`. A tab must hold exactly ONE SSE connection no matter how many features listen — extra streams eat the browser's per-origin connection budget and can starve ordinary data fetches (worst on HTTP/1.1 dev servers). Subscribe to the shared transport instead:
+
+  ```ts
+  import { subscribeSyncEvents } from "@agent-native/core/client";
+
+  const unsubscribe = subscribeSyncEvents({
+    onEvents: (events) => {
+      // filter by event.source and handle push-style updates
+    },
+    // Optional: relax your own fallback cadence while push is healthy.
+    onSseStateChange: (connected) => {},
+  });
+  ```
+
+  `useDbSync` and every `subscribeSyncEvents` subscriber share one `EventSource` and one fallback poll loop per tab — this is how collaborative documents receive doc updates and cursor/awareness events.
 
 ## Which sources to depend on