@agent-native/core 0.14.8 → 0.15.1

package/dist/templates/workspace-core/.agents/skills/portability/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: portability
+description: >-
+  How to keep template code database-agnostic and hosting-agnostic. Use when
+  defining schemas, writing raw SQL, creating server routes, or anything that
+  could leak a SQLite-only, Postgres-only, or Node-only assumption.
+---
+
+# Portability
+
+## Rule
+
+**Never write code that only works on one database or one hosting platform.** Templates must run on any SQL database (SQLite, Postgres, D1, Turso, Supabase, Neon) and any Nitro deploy target (Node, Cloudflare, Netlify, Vercel, Deno, Lambda, Bun) without code changes.
+
+## Database Agnostic
+
+Use the dialect-agnostic schema helpers from `@agent-native/core/db/schema`:
+
+```ts
+import {
+  table,
+  text,
+  integer,
+  real,
+  now,
+  sql,
+} from "@agent-native/core/db/schema";
+
+export const meals = table("meals", {
+  id: text("id").primaryKey(),
+  name: text("name").notNull(),
+  calories: integer("calories").notNull(),
+  weight: real("weight"),
+  archived: integer("archived", { mode: "boolean" }).notNull().default(false),
+  createdAt: text("created_at").notNull().default(now()),
+});
+```
+
+| Helper    | Purpose                                                                                   |
+| --------- | ----------------------------------------------------------------------------------------- |
+| `table`   | Delegates to `pgTable` or `sqliteTable` based on dialect                                  |
+| `text`    | Works in both dialects, supports `{ enum: [...] }`                                        |
+| `integer` | `{ mode: "boolean" }` maps to Postgres `boolean` automatically                            |
+| `real`    | `real` on SQLite, `double precision` on Postgres                                          |
+| `now`     | Dialect-agnostic current timestamp — use with `.default(now())` on text timestamp columns |
+| `sql`     | Re-exported from `drizzle-orm` for raw SQL expressions                                    |
+
+**Never import from `drizzle-orm/sqlite-core` or `drizzle-orm/pg-core` directly in template code.** Always use `@agent-native/core/db/schema` instead.
+
+### Raw SQL helpers
+
+- `getDbExec()` — auto-converts `?` params to `$1` for Postgres
+- `isPostgres()` — runtime dialect check
+- `intType()` — returns correct integer type for the dialect
+
+### Never
+
+Never write SQLite-only syntax: `INSERT OR REPLACE`, `AUTOINCREMENT`, `datetime('now')`. When writing docs, say "SQL database" — not "SQLite".
+
+## Hosting Agnostic
+
+The server runs on **Nitro** with **H3** as the HTTP framework. Templates must be deployable to any Nitro-supported target.
+
+### Never use Express
+
+All server code uses H3/Nitro: `defineEventHandler`, `readBody`, `getMethod`, `setResponseHeader`, etc. Express is not a dependency. If you see Express types or patterns anywhere, replace them with H3 equivalents.
+
+### No platform-specific config in templates
+
+Files like `netlify.toml`, `wrangler.toml`, `vercel.json`, and `netlify/functions/` do not belong in template source. Platform configuration lives in CI/hosting dashboards or in deployment-specific repos.
+
+### No Node APIs in server routes/plugins
+
+Never use `fs`, `child_process`, or `path` in server routes and plugins. Use Nitro abstractions. (Actions in `actions/` run in Node.js and can use Node APIs freely.)
+
+### No persistent-process assumptions
+
+Never assume a persistent server process. Use the SQL database for all state.
+
+## Related Skills
+
+- `storing-data` — Schema patterns and the core SQL stores
+- `server-plugins` — Framework routes and H3 handler patterns
+- `security` — SQL injection prevention via parameterized queries

package/dist/templates/workspace-core/.agents/skills/qa/SKILL.md

@@ -0,0 +1,313 @@
+---
+name: qa
+description: >-
+  Autonomous QA testing across template apps using Playwright. Use when testing
+  apps end-to-end, finding and fixing bugs, or running a QA sweep. Invoke as
+  /qa with optional --apps and --focus args.
+user-invocable: true
+---
+
+# QA Testing
+
+Autonomous QA testing that spins up template apps, tests them with Playwright in parallel, fixes issues, retests, and reports findings. Only alerts the user when blocked.
+
+## Usage
+
+```
+/qa                                            # test mail, calendar, content, forms
+/qa --apps mail,forms                          # test specific apps
+/qa --focus "test form submission and compose"  # prioritize specific flows
+```
+
+**Args:**
+
+- `--apps` — comma-separated app names (default: `mail,calendar,content,forms`)
+- `--focus` — natural language guidance for what to prioritize
+
+## Orchestrator Steps
+
+You (the agent running this skill) are the orchestrator. Follow these steps in order.
+
+### Step 1: Parse Args
+
+Parse the user's invocation to determine:
+
+- **apps**: which apps to test (default: mail, calendar, content, forms)
+- **focus**: optional test priority guidance
+
+### Step 2: Check Credential Readiness
+
+For each app, check if required credentials exist:
+
+| App      | Check                                          | Can test without? |
+|----------|-------------------------------------------------|-------------------|
+| forms    | No credentials needed                          | Yes               |
+| content  | No credentials needed (Notion is opt-in)       | Yes               |
+| calendar | `templates/calendar/.env` has GOOGLE_CLIENT_ID | Partially — local events work, Google sync won't |
+| mail     | `templates/mail/.env` has GOOGLE_CLIENT_ID     | Partially — UI renders, Gmail features won't |
+
+Read each app's `.env` file (if it exists) to check. If credentials are missing:
+
+- Still test the app — many features work without external APIs
+- Include in the tester's instructions: "No Google credentials found. Test local features. Flag any feature that crashes without credentials as 'needs credentials' rather than a bug."
+- Only alert the user (via SendMessage to team lead or AskUserQuestion) if the app **cannot start at all**
+
+### Step 3: Start Dev Servers
+
+Start each app's dev server on a dedicated port using `run_in_background`:
+
+| App      | Port | Command |
+|----------|------|---------|
+| mail     | 9201 | `cd templates/mail && PORT=9201 pnpm dev` |
+| calendar | 9202 | `cd templates/calendar && PORT=9202 pnpm dev` |
+| content  | 9203 | `cd templates/content && PORT=9203 pnpm dev` |
+| forms    | 9204 | `cd templates/forms && PORT=9204 pnpm dev` |
+
+Start all servers in parallel (multiple Bash calls with `run_in_background: true`).
+
+Then verify each server is ready by polling with curl:
+
+```bash
+for i in {1..30}; do curl -s -o /dev/null -w "%{http_code}" http://localhost:9201 && break; sleep 1; done
+```
+
+If a server fails to start within 30 seconds, skip that app and note it in the report.
+
+### Step 4: Generate Test Plans
+
+For each app, read these files to understand what to test:
+
+1. `templates/<app>/app/routes/` or `templates/<app>/app/routes.ts` — discover all pages
+2. `templates/<app>/CLAUDE.md` — features, API routes, data model
+3. `templates/<app>/server/routes/api/` — API endpoints
+
+Combine with any `--focus` guidance to produce a test plan. The test plan is a numbered list of user-facing flows to verify. Example:
+
+```
+1. Home page loads without errors
+2. Create a new item via the UI
+3. Edit an existing item
+4. Delete an item
+5. Check all navigation links work
+6. Verify no console errors on any page
+7. Verify no failed network requests
+```
+
+### Step 5: Create Team and Spawn Testers
+
+Create a team and spawn one tester agent per app, all in parallel:
+
+```
+TeamCreate: name="qa", description="QA testing sweep"
+```
+
+Create one task per app:
+
+```
+TaskCreate: subject="QA test <app> on port <port>", description="<test plan>"
+```
+
+Then spawn tester agents in parallel using the Agent tool. Each agent gets:
+
+- `name`: `qa-<app>` (e.g., `qa-mail`)
+- `team_name`: `qa`
+- `mode`: `auto`
+- The full tester prompt (see Tester Agent Prompt below)
+
+### Step 6: Monitor and Alert
+
+After spawning testers, wait for their idle notifications and task updates.
+
+- When a tester completes its task, note its findings
+- When a tester reports being blocked (missing credentials, app won't start, needs user input), relay that to the user via AskUserQuestion
+- When all testers are done, proceed to Step 7
+
+### Step 7: Compile Report and Shutdown
+
+Gather all tester reports from their task updates. Print a compiled summary:
+
+```markdown
+# QA Summary — <date>
+
+## Apps Tested: N
+## Total Issues Found: N
+## Fixed: N
+## Needs Review: N
+
+### Mail App
+[tester report]
+
+### Forms App
+[tester report]
+
+...
+```
+
+Then shut down all teammates:
+
+```
+SendMessage to each tester: { type: "shutdown_request" }
+```
+
+---
+
+## Tester Agent Prompt
+
+Use this as the prompt when spawning each tester agent via the Agent tool. Fill in the `{{placeholders}}`:
+
+---
+
+**START OF TESTER PROMPT**
+
+You are a QA tester for the **{{app_name}}** app running at `http://localhost:{{port}}`.
+
+## Your Mission
+
+Test the app thoroughly using Playwright MCP tools. Find bugs, fix them, retest. Report your findings.
+
+## Team Context
+
+You are on team "qa". Your name is "qa-{{app_name}}".
+
+- Use TaskUpdate to mark your task as `in_progress` when you start
+- Use TaskUpdate to mark your task as `completed` when done, with your report in the description
+- If you are blocked and need user input, send a message to the team lead explaining what you need
+
+## Credential Status
+
+{{credential_status}}
+
+## Test Plan
+
+{{test_plan}}
+
+## How to Test
+
+Use these Playwright MCP tools:
+
+1. **Navigate**: `browser_navigate` to `http://localhost:{{port}}<path>`
+2. **See the page**: `browser_snapshot` — returns an accessibility tree showing all visible elements with `ref` attributes
+3. **Click**: `browser_click` with `ref` from the snapshot
+4. **Type**: `browser_type` with `ref` and `text`
+5. **Fill forms**: `browser_fill_form` with `ref` and `values`
+6. **Check console**: `browser_console_messages` — look for errors
+7. **Check network**: `browser_network_requests` — look for failed requests (4xx, 5xx)
+8. **Wait**: `browser_wait_for` when you need to wait for content to appear
+9. **Screenshot**: `browser_take_screenshot` when you want to capture the visual state
+
+### Testing Loop
+
+For each test in your plan:
+
+1. Navigate to the relevant page
+2. Take a snapshot to see what's on screen
+3. Check console messages for errors
+4. Check network requests for failures
+5. Interact with the page — click buttons, fill forms, navigate flows
+6. If something is broken:
+   a. Document: what page, what's wrong
+   b. Read the relevant source files to understand the issue
+   c. Fix the code
+   d. Wait 2-3 seconds for Vite HMR to hot-reload
+   e. Retest by taking a new snapshot
+   f. If still broken after 3 attempts, mark as "needs human review" and move on
+7. Move to the next test
+
+After completing all tests, do **one more pass** on any pages where you found issues to verify fixes didn't break other things.
+
+**Maximum 2 full passes.** Don't loop forever.
+
+### Start by navigating to the home page
+
+Always start by navigating to `http://localhost:{{port}}/` and taking a snapshot to verify the app is running.
+
+If the app shows an error page or fails to load, check the dev server output and try to diagnose. If it's a missing dependency or config issue, report it and stop — don't spend time debugging infrastructure.
+
+## Isolation Rules
+
+**CRITICAL:** You may ONLY modify files within `templates/{{app_name}}/`. If a bug requires changes to `packages/core/` or any other template, report it as a finding but do NOT fix it.
+
+After modifying any source file, run:
+```bash
+npx prettier --write <file>
+```
+
+## What Counts as a Bug
+
+- Page crashes or shows error overlay
+- Console errors (not warnings — errors only)
+- Network requests returning 4xx or 5xx
+- Buttons/links that don't work
+- Forms that don't submit
+- Data that doesn't save or display
+- Layout severely broken (overlapping text, invisible elements)
+- Features described in CLAUDE.md that don't work
+
+What is NOT a bug:
+- Minor styling preferences
+- Missing features that aren't described in CLAUDE.md
+- Warnings in console
+- Slow loading (unless > 10 seconds)
+
+## Report Format
+
+When you're done, update your task (via TaskUpdate) with status `completed` and set the description to your report:
+
+```markdown
+## QA Report: {{app_name}}
+
+### Summary: N found, N fixed, N needs review
+
+#### Fixed
+1. **Short description** — What file you changed and why
+
+#### Needs Review
+1. **Short description** — Why you couldn't fix it
+
+#### Skipped (needs credentials)
+1. **Feature name** — What credential is needed
+
+#### Pages Tested
+- /path (page name) — status (OK, N issues fixed, N needs review)
+```
+
+**END OF TESTER PROMPT**
+
+---
+
+## Troubleshooting
+
+### Port already in use
+
+Kill the process on the port before starting:
+
+```bash
+lsof -ti :9201 | xargs kill -9 2>/dev/null; true
+```
+
+### Dev server won't start
+
+Common causes:
+
+- Missing `node_modules` — run `pnpm install` from root first
+- Missing `.env` file — some apps need one even if empty. Check `.env.example`
+- Port conflict — kill stale processes (see above)
+- Build error in core — run `pnpm --filter @agent-native/core build` first
+
+### Playwright MCP not responding
+
+The Playwright MCP server must be configured in Claude Code's MCP settings. If browser tools aren't available, the tester agent should report "Playwright MCP tools not available" and stop.
+
+### HMR not picking up changes
+
+After editing a file, wait 2-3 seconds. If the page doesn't update, try a hard refresh by navigating away and back. Vite HMR sometimes misses changes in server-side files — restart the dev server if needed.
+
+### App shows "credentials not configured" when they are
+
+This is a known issue. The tester should:
+
+1. Check the `.env` file exists and has the right variable names
+2. Check if the app reads from `.env` or `data/.env`
+3. Check the server plugin that loads credentials
+4. Try to fix the credential detection logic
+5. If unfixable, report as "needs review" with details about what the app expects vs. what's configured

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

@@ -0,0 +1,112 @@
+---
+name: real-time-collab
+description: >-
+  Multi-user collaborative editing with Yjs CRDT and live cursors. Use when
+  adding real-time collaborative editing to a template, debugging sync issues,
+  or understanding how the agent and humans edit documents simultaneously.
+---
+
+# Real-Time Collaboration
+
+## Rule
+
+Collaborative editing uses Yjs CRDT via TipTap. The agent and human users are equal participants — both edit the same Y.Doc and changes merge cleanly without conflicts.
+
+## How It Works
+
+- **`Y.Doc`** stores the document as a `Y.XmlFragment` (ProseMirror node tree)
+- **TipTap's Collaboration extension** binds the editor to the Y.XmlFragment via `ySyncPlugin`
+- **CollaborationCaret extension** renders remote users' cursors with names and colors
+- **Polling** (every 2s) syncs Y.Doc updates and awareness state between clients and server
+- **SQL `_collab_docs` table** persists Yjs state as base64-encoded binary (works across SQLite/Postgres)
+
+## Agent + Human Editing
+
+1. **Human edits** → TipTap → ySyncPlugin → Y.XmlFragment → `POST /_agent-native/collab/:docId/update`
+2. **Agent edits** → `edit-document` action → server search-replace → Y.XmlFragment mutation → poll update → all clients
+
+Both produce minimal Yjs operations that merge cleanly. Agent edits appear without destroying cursor position, selection, or undo history.
+
+The `edit-document` action uses surgical search-and-replace on Y.XmlText nodes — more efficient than regenerating the entire document.
+
+## Enabling Collaboration
+
+### 1. Install packages
+
+```bash
+pnpm add @tiptap/extension-collaboration @tiptap/extension-collaboration-caret @tiptap/y-tiptap
+```
+
+### 2. Add collab server plugin
+
+```ts
+// server/plugins/collab.ts
+import { createCollabPlugin } from "@agent-native/core/collab";
+
+export default createCollabPlugin({
+  table: "documents",
+  contentColumn: "content",
+  idColumn: "id",
+});
+```
+
+### 3. Use the client hook
+
+```ts
+import { useCollaborativeDoc } from "@agent-native/core/client";
+
+const { ydoc, provider } = useCollaborativeDoc(documentId);
+```
+
+### 4. Add TipTap extensions
+
+```ts
+import { Collaboration } from "@tiptap/extension-collaboration";
+import { CollaborationCaret } from "@tiptap/extension-collaboration-caret";
+
+const editor = useEditor({
+  extensions: [
+    Collaboration.configure({ document: ydoc }),
+    CollaborationCaret.configure({
+      provider,
+      user: { name: session.email, color: "#6366f1" },
+    }),
+  ],
+});
+```
+
+### 5. Add to vite.config.ts optimizeDeps
+
+```ts
+optimizeDeps: {
+  include: [
+    "@tiptap/extension-collaboration",
+    "@tiptap/extension-collaboration-caret",
+    "@tiptap/y-tiptap",
+  ],
+}
+```
+
+## Collab Routes (auto-mounted)
+
+| Route | Purpose |
+| ----- | ------- |
+| `GET /_agent-native/collab/:docId/state` | Fetch full Y.Doc state |
+| `POST /_agent-native/collab/:docId/update` | Apply client Yjs update |
+| `POST /_agent-native/collab/:docId/text` | Apply full text (diff-based) |
+| `POST /_agent-native/collab/:docId/search-replace` | Surgical find/replace in Y.XmlFragment |
+| `POST /_agent-native/collab/:docId/awareness` | Sync cursor/presence state |
+| `GET /_agent-native/collab/:docId/users` | List active users |
+
+## Common Pitfalls
+
+- **Don't pass `content` as a TipTap prop** when Collaboration is enabled — Yjs owns the content. Set initial content via the Y.Doc instead.
+- **Don't use `editor.setContent()`** for agent edits — it bypasses Yjs and causes conflicts. Use the `search-replace` route or `edit-document` action.
+- **Add packages to `optimizeDeps`** — Vite won't pre-bundle Yjs packages correctly otherwise, causing runtime errors in dev.
+- **One `Y.Doc` per document** — Don't create multiple Y.Doc instances for the same document ID. Use the `useCollaborativeDoc` hook which caches by ID.
+
+## Related Skills
+
+- `real-time-sync` — Polling infrastructure that delivers Y.Doc updates
+- `storing-data` — The `_collab_docs` table where Yjs state is persisted
+- `self-modifying-code` — Agent edits to collaborative documents go through `edit-document`, not raw SQL

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

@@ -0,0 +1,165 @@
+---
+name: real-time-sync
+description: >-
+  How to keep the UI in sync with agent changes via SSE plus polling fallback.
+  Use when wiring query invalidation for new data models, debugging UI not
+  updating, or understanding jitter prevention.
+---
+
+# Real-Time Sync
+
+## Rule
+
+The UI stays in sync with agent/script changes through `useDbSync()`. In-process writes stream over `/_agent-native/events` first; `/_agent-native/poll` remains the cross-process/serverless fallback. When the agent writes to the database, the UI detects the change and updates automatically — no manual refresh needed.
+
+## Why
+
+The agent modifies data in SQL, but the UI runs in the browser. SSE bridges same-process writes immediately; polling bridges anything SSE cannot see, such as another serverless invocation, cron job, or external script. Every visible write increments a version counter, `useDbSync()` receives the change, and React Query invalidates the relevant caches. This is what makes database writes feel real-time without relying on aggressive polling.
+
+## How It Works
+
+1. **Server** increments a version counter on every database write. In-process events stream through the authenticated `/_agent-native/events` endpoint.
+
+2. **Client** listens for SSE/poll events and updates per-source change counters:
+
+   ```ts
+   import { useDbSync } from "@agent-native/core";
+   useDbSync({ queryClient });
+   ```
+
+   For each non-own event, `useDbSync` bumps a per-source counter (e.g. `dashboards`, `analyses`, `settings`, `action`) and invalidates a small fixed list of framework-internal prefixes (`["action"]`, `["app-state"]`, `["__set_url__"]`, etc.). It does **not** blanket-invalidate templates' own data queries — that caused a request storm in production.
+
+3. **Templates fold per-source counters into their query keys.** This is the pattern that makes "agent writes show up without a manual refresh" reliable:
+
+   ```ts
+   import { useChangeVersion } from "@agent-native/core/client";
+   import { useQuery } from "@tanstack/react-query";
+
+   const v = useChangeVersion("dashboards");
+   const dashboard = useQuery({
+     queryKey: ["dashboard", id, v],
+     queryFn: () => fetchDashboard(id),
+     placeholderData: (prev) => prev, // no flicker on refetch
+   });
+   ```
+
+   When the agent writes (`update-dashboard` action → server emits `source: "dashboards"`), the counter advances, the queryKey changes, and React Query refetches that one query. The old data stays on screen during the refetch thanks to `placeholderData`.
+
+   For list/sidebar queries, use the same pattern — pass the counter into the queryKey of every list query you want to keep fresh.
+
+3. **Fallback** polling calls `/_agent-native/poll?since=N`. It runs every 2 seconds until SSE is connected, then relaxes to 15 seconds. If SSE is disabled or unavailable, polling continues at the normal cadence.
+
+4. When the agent writes to the database, the version increments, SSE/polling detects it, and React Query refetches the affected queries.
+
+## Don't
+
+- 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
+
+## Which sources to depend on
+
+Common sources you'll fold into query keys:
+
+| Source            | Bumped by                                                                   |
+| ----------------- | --------------------------------------------------------------------------- |
+| `action`          | The agent runner after every successful mutating action tool call           |
+| `app-state`       | Writes to `application_state` (navigation, selections, ephemeral UI state)  |
+| `settings`        | Writes to the `settings` table                                              |
+| `dashboards`      | Dashboard CRUD via `upsertDashboard` / `archiveDashboard` etc.              |
+| `analyses`        | Analysis CRUD                                                               |
+| `extensions`      | Extension CRUD                                                              |
+| `collab`          | Yjs collaborative-doc updates                                               |
+| `screen-refresh`  | Explicit `refresh-screen` agent tool call                                   |
+
+If a query reads data the agent can mutate via more than one path, depend on multiple sources with `useChangeVersions`:
+
+```ts
+const v = useChangeVersions(["dashboards", "action"]);
+useQuery({ queryKey: ["dashboard", id, v], ... });
+```
+
+`useChangeVersions` returns a single integer that advances whenever any of the listed sources advance.
+
+## Tuning refetch behavior
+
+To prevent cache thrashing during rapid agent writes, set `staleTime` on your queries:
+
+```ts
+useQuery({
+  queryKey: ["items"],
+  queryFn: fetchItems,
+  staleTime: 2000, // don't refetch within 2 seconds
+});
+```
+
+## Troubleshooting
+
+| Symptom                            | Check                                                                                                          |
+| ---------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| UI not updating after agent writes | Is `useDbSync` called with the correct `queryClient`? Does the affected query have an active observer?         |
+| Poll endpoint not responding       | Is `/_agent-native/poll` accessible? Is the server running?                                                    |
+| SSE not connecting                 | Is `/_agent-native/events` accessible and authenticated? Polling should still keep the UI fresh as fallback.   |
+| High CPU / event storms            | The agent is writing rapidly. Add `staleTime` to queries to debounce refetches.                                |
+
+## Jitter Prevention
+
+When the agent writes to application-state via script helpers (`writeAppState`, `deleteAppState`), the write is automatically tagged with `requestSource: "agent"`. This prevents the UI from overwriting active user edits when it receives the change event.
+
+### How it works
+
+1. **Agent writes** are tagged: the script helpers in `@agent-native/core/application-state` pass `{ requestSource: "agent" }` to the store.
+2. **UI writes** are tagged: templates send a per-tab ID via the `X-Request-Source` header on PUT/DELETE requests to application-state endpoints.
+3. **Sync filters**: `useDbSync()` accepts an `ignoreSource` option. The UI passes its own tab ID so it ignores events from its own writes — but still picks up events from agents, other tabs, and scripts.
+
+### Template setup
+
+```ts
+// app/lib/tab-id.ts
+export const TAB_ID = `tab-${Math.random().toString(36).slice(2, 8)}`;
+
+// app/root.tsx
+import { TAB_ID } from "@/lib/tab-id";
+
+useDbSync({
+  queryClient,
+  ignoreSource: TAB_ID,
+});
+```
+
+The `use-navigation-state.ts` hook sends the same `TAB_ID` in the `X-Request-Source` header when writing navigation state, so the tab that wrote the state does not refetch it.
+
+### Why this matters
+
+Without jitter prevention, a cycle occurs: the UI writes state, sync detects the change, the UI refetches and re-renders, potentially overwriting what the user is actively editing. With `ignoreSource`, the UI only reacts to changes from other sources (agent scripts, other browser tabs, other users).
+
+## Action Routes and Polling
+
+Action routes (`/_agent-native/actions/:name`) work with the same sync system. When a POST/PUT/DELETE action writes to the database, the version counter increments and `useDbSync` picks up the change. Frontend mutations via `useActionMutation` automatically invalidate `["action"]` query keys on success, triggering refetches of `useActionQuery` hooks.
+
+### Auto-emit on mutating actions
+
+The framework emits a poll event with `source: "action"` whenever any non-read-only action runs to completion — whether called via HTTP (`/_agent-native/actions/:name`) or as an agent tool call. Read-only actions (`http: { method: "GET" }` or explicit `readOnly: true`) are skipped.
+
+This means UIs don't need the agent to remember to call `refresh-screen` after every mutation. A listener like this (used in the `macros` template) will refresh after any mutating agent call:
+
+```ts
+useDbSync({
+  queryClient,
+  queryKeys: [],
+  ignoreSource: TAB_ID,
+  onEvent: (data) => {
+    if (data.requestSource === TAB_ID) return;
+    // Invalidate all useActionQuery caches so list-*, get-*, etc. refetch
+    queryClient.invalidateQueries({ queryKey: ["action"] });
+  },
+});
+```
+
+`refresh-screen` remains available for unusual cases — e.g. the agent mutated data via a path the framework can't see (external system the app mirrors), or the agent wants to pass a `scope` hint for narrower invalidation.
+
+## Related Skills
+
+- **storing-data** — Application-state and settings are the data stores that sync via polling
+- **context-awareness** — Navigation state writes use jitter prevention to avoid overwriting active edits
+- **actions** — Action routes auto-expose actions as HTTP endpoints; database writes trigger poll events
+- **self-modifying-code** — Agent code edits trigger poll events; rapid edits can cause event storms