@agent-native/core 0.101.12 → 0.101.14

package/src/templates/chat/.agents/skills/delegate-to-agent/SKILL.md

@@ -0,0 +1,263 @@
+---
+name: delegate-to-agent
+description: >-
+  How to delegate all AI work to the agent chat. Use when delegating AI work
+  from UI or scripts to the agent, when a user asks for agent behavior or
+  LLM-powered features, when tempted to add inline LLM calls, or when sending
+  messages to the agent from application code.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Delegate All AI to the Agent
+
+## Rule
+
+The UI never calls an LLM directly. Product workflows are delegated to the
+agent through the chat bridge so users can see, steer, and audit the work.
+Server-side one-shot model calls are an explicit escape hatch for narrow text
+transforms only; use `completeText()` from `@agent-native/core/server` when the
+work intentionally does not need tools, chat history, or run state.
+
+## Why
+
+The agent is the single AI interface. It has context about the full project, can read/write any file, and can run scripts. Inline LLM calls bypass this — they create a shadow AI that doesn't know what the agent knows and can't coordinate with it.
+
+## How
+
+**From the UI (client):**
+
+```ts
+import { sendToAgentChat } from "@agent-native/core/client";
+
+sendToAgentChat({
+  message: "Generate a summary of this document",
+  context: documentContent, // optional hidden context (not shown in chat UI)
+  submit: true, // auto-submit to the agent
+});
+```
+
+**From the UI, in the background:**
+
+```ts
+import { sendToAgentChat } from "@agent-native/core/client";
+
+sendToAgentChat({
+  message: "Analyze this import and create any missing records",
+  context: `Import batch id: ${batchId}`,
+  submit: true,
+  newTab: true,
+  background: true,
+  openSidebar: false,
+});
+```
+
+This is still a full agent run: tools, actions, thread state, and run tracking
+all remain active. It simply does not focus or open the sidebar.
+
+**From scripts (Node):**
+
+```ts
+import { agentChat } from "@agent-native/core";
+
+agentChat.submit("Process the uploaded images and create thumbnails");
+```
+
+**For narrow server-side text transforms:**
+
+```ts
+import { completeText } from "@agent-native/core/server";
+
+const result = await completeText({
+  systemPrompt: "Return exactly one sentiment label.",
+  input: messageBody,
+  maxOutputTokens: 12,
+  temperature: 0,
+});
+```
+
+Wrap user-facing uses in actions so the UI and agent share the same operation.
+Do not call provider SDKs directly.
+
+**From the UI, detecting when agent is done:**
+
+```ts
+import { useAgentChatGenerating } from "@agent-native/core/client";
+
+function MyComponent() {
+  const isGenerating = useAgentChatGenerating();
+  // Show loading state while agent is working
+}
+```
+
+## `submit` vs Prefill
+
+The `submit` option controls whether the message is sent automatically or placed in the chat input for user review:
+
+| `submit` value | Behavior                                | Use when                                                                            |
+| -------------- | --------------------------------------- | ----------------------------------------------------------------------------------- |
+| `true`         | Auto-submits to the agent immediately   | Routine operations the user has already approved                                    |
+| `false`        | Prefills the chat input for user review | High-stakes operations (deleting data, modifying code, API calls with side effects) |
+| omitted        | Uses the project's default setting      | General-purpose delegation                                                          |
+
+```ts
+// Auto-submit: routine operation
+sendToAgentChat({ message: "Update the project summary", submit: true });
+
+// Prefill: let user review before sending
+sendToAgentChat({
+  message: "Delete all projects older than 30 days",
+  submit: false,
+});
+```
+
+## Capture user input first when generating from a prompt
+
+Buttons that produce new content ("New Design", "Create Dashboard", "Make Deck", "Generate Form") need the user's prompt as input. **Never hardcode a generic message** — the result will be a generic generation the user didn't actually ask for.
+
+**Bad** — auto-submits a placeholder message; the user never said what they wanted:
+
+```tsx
+<Button
+  onClick={() =>
+    sendToAgentChat({ message: "make a design", submit: true })
+  }
+>
+  New Design
+</Button>
+```
+
+**Good** — Popover anchored to the button captures the prompt, then submits it:
+
+```tsx
+<Popover open={open} onOpenChange={setOpen}>
+  <PopoverTrigger asChild>
+    <Button>New Design</Button>
+  </PopoverTrigger>
+  <PopoverContent className="w-96">
+    <Textarea
+      autoFocus
+      value={prompt}
+      onChange={(e) => setPrompt(e.target.value)}
+      placeholder="What do you want to design?"
+    />
+    <Button
+      onClick={() => {
+        sendToAgentChat({ message: prompt, submit: true });
+        setOpen(false);
+        setPrompt("");
+      }}
+    >
+      Create
+    </Button>
+  </PopoverContent>
+</Popover>
+```
+
+**Always ask for input first when** the output depends on a prompt the user must provide — "design what?", "deck about what?", "dashboard for which metric?", "form for which use case?".
+
+**Auto-submit without input is fine when intent is unambiguous:**
+
+- "Try to fix" on a tool error — submits the error details with a clear fix instruction
+- "Retry the last operation" after a transient failure
+- Single-purpose buttons where there is nothing meaningful for the user to add
+
+If you find yourself writing `submit: true` with a hardcoded creative verb (`"design a..."`, `"write a..."`, `"build a..."`), stop and add a Popover.
+
+## Delegating to a Sub-Agent (Agent Teams)
+
+`sendToAgentChat()` delegates from app code _to_ the agent. The other axis of
+delegation is the agent handing work _to a sub-agent_ through the Agent Teams
+run-manager. The main chat stays the orchestrator: it spawns sub-agents, then
+reads and integrates their results.
+
+### When to spawn a sub-agent vs do it yourself
+
+- **Do it yourself** when the work is small, on the critical path, or tightly
+  coupled to what you're already doing. Sub-agent overhead and coordination risk
+  outweigh the benefit.
+- **Spawn a sub-agent** for a self-contained unit of work that can run
+  independently — a disjoint investigation, an isolated implementation slice, a
+  long-running search — especially when it frees the main thread to keep
+  orchestrating.
+
+### Briefing contract
+
+Every sub-agent brief must specify four things, or the sub-agent will guess:
+
+- **Objective** — the one concrete outcome it owns, in a sentence.
+- **Context** — the facts it needs (paths, prior findings, constraints) so it
+  doesn't re-derive them.
+- **Output** — the exact shape you want back (a summary, a file edited, a list
+  of paths, a yes/no with rationale).
+- **Boundaries** — what it must NOT touch (files, branches, side effects) and
+  when to stop and report rather than push forward.
+
+### Fan-out discipline
+
+- **Default to a single sub-agent.** Most delegation is one focused task.
+- **Spawn multiple only for genuinely independent units** that don't share state
+  or files. Never parallelize coupled work — if B needs A's output, run them in
+  sequence.
+- **Cap parallel fan-out at ~3.** More sub-agents means more synthesis cost and
+  more chance of conflicting edits to the same area.
+
+### Synthesis discipline
+
+- **Read every result** before concluding — don't act on the first one back.
+- **Reconcile conflicts** between sub-agent findings explicitly; decide which is
+  right rather than averaging or ignoring.
+- **Integrate into one answer.** The main thread produces the single coherent
+  result; it never just forwards raw sub-agent transcripts to the user.
+
+Background sub-agents must use the core run-manager / Agent Teams infrastructure
+rather than ad-hoc LLM calls.
+
+## Don't
+
+- Don't `import Anthropic from "@anthropic-ai/sdk"` in client or server code
+- Don't `import OpenAI from "openai"` in client or server code
+- Don't make direct API calls to any LLM provider
+- Don't use AI SDK functions like `generateText()`, `streamText()`, etc.
+- Don't build "AI features" that bypass the agent chat
+- Don't auto-submit a hardcoded prompt for generative actions — capture user input first (see above)
+- Don't use `completeText()` for workflows that need tools, database writes,
+  auditability, user steering, or multi-step reasoning. Use the agent chat
+  instead, optionally with `background: true`.
+
+## Exception
+
+Scripts may call external APIs (image generation, search, etc.) — but the AI
+reasoning and orchestration still goes through the agent. A script is a tool
+the agent uses, not a replacement for the agent.
+
+`completeText()` is allowed for small server-side transforms such as
+classification, extraction, rewriting a short string, or normalizing messy
+provider text. It deliberately runs with `tools: []` and does not create chat
+thread state.
+
+## When to Use A2A Instead
+
+`sendToAgentChat()` delegates work to the **local** agent — the one running alongside your app. When the work should go to a **different** agent entirely (e.g., asking an analytics agent for data, or a calendar agent for availability), use the A2A (agent-to-agent) protocol instead.
+
+```ts
+import { callAgent } from "@agent-native/core/a2a";
+
+// Call a different agent — not the local agent chat
+const stats = await callAgent(
+  "https://analytics.example.com",
+  "What were last week's signups?",
+  { apiKey: process.env.ANALYTICS_A2A_KEY },
+);
+```
+
+See the **a2a-protocol** skill for the full pattern.
+
+## Related Skills
+
+- **a2a-protocol** — When the work goes to a different agent, not the local one
+- **actions** — The agent invokes actions via `pnpm action <name>` to perform complex operations
+- **self-modifying-code** — The agent operates through the chat bridge to make code changes
+- **storing-data** — The agent writes results to the database after processing requests
+- **real-time-sync** — The UI updates automatically when the agent writes data

package/src/templates/chat/.agents/skills/frontend-design/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: frontend-design
+description: >-
+  Create distinctive, production-grade frontend interfaces with high design
+  quality. Use when building web components, pages, artifacts, posters, or
+  applications (websites, landing pages, dashboards, React components,
+  HTML/CSS layouts, or when styling/beautifying any web UI). Generates
+  creative, polished UI that avoids generic AI aesthetics.
+scope: dev
+license: Complete terms in LICENSE.txt
+source: https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md
+metadata:
+  internal: true
+---
+
+# Frontend Design
+
+This skill guides creation of distinctive, production-grade frontend interfaces. Implement real working code with strong product judgment, excellent accessibility, and a clear visual point of view.
+
+The user may ask for a component, page, full app, dashboard, marketing surface, or restyle. Before coding, understand the audience and pick a direction that fits the product instead of defaulting to generic SaaS polish.
+
+## Design Thinking
+
+Before coding, decide:
+
+- **Purpose**: What workflow does this surface make easier? What is the primary action?
+- **Audience**: Who will use it repeatedly, and what should feel fast, calm, playful, premium, editorial, technical, or utilitarian?
+- **Tone**: Choose a concrete aesthetic direction: refined minimal, dense operations console, editorial, playful, industrial, warm handmade, high-contrast data tool, etc.
+- **Information hierarchy**: What must be visible in the first five seconds, and what should be progressively disclosed?
+- **Differentiation**: What makes this feel designed for this exact domain?
+
+Then implement working code that is cohesive, accessible, responsive, and polished in small details: typography, spacing, copy, motion, empty states, loading states, focus states, and error states.
+
+## Minimalism And Progressive Disclosure
+
+Default to Apple/Linear-level restraint: make the primary workflow obvious, then remove everything that does not help that workflow right now. A polished UI often has fewer visible controls, fewer borders, fewer labels, and fewer explanatory surfaces than the first reasonable implementation.
+
+- **Start by subtracting**: Before adding a visible control, banner, toolbar row, card, or explanatory block, ask what can be removed, merged, renamed, or moved into an existing affordance.
+- **One primary action**: Each surface should have one dominant next action. Secondary actions belong in menus, popovers, command palettes, disclosure rows, or contextual hover/focus states unless they are used constantly.
+- **Progressively disclose rare work**: Advanced options, diagnostics, metadata, settings, import/export, destructive actions, and inspection tools should stay tucked away until requested. Prefer small icon triggers with tooltips, popovers, drawers, or detail panels over permanent chrome.
+- **Keep chrome quiet**: Avoid new always-visible bars, badges, callouts, helper text, and counters unless they prevent mistakes or are central to repeated use. Status can often be a dot, ring, muted count, or tooltip.
+- **Favor content over containers**: Do not wrap every section in a card. Use whitespace, alignment, typography, dividers, and full-width bands before adding boxes.
+- **Design for repeated use**: Production app UI should feel calm after the hundredth use. If a control shouts, animates, explains itself, or occupies a full row for an occasional action, hide or compress it.
+- **Make absence intentional**: Empty states should be sparse and action-oriented. Do not fill blank space with marketing copy, decorative art, or lists of features just because the screen feels empty.
+- **Use familiar primitives**: Icon buttons need clear tooltips. Menus, popovers, tabs, switches, and segmented controls should carry complexity instead of exposing every option at once.
+
+## Aesthetic Guidelines
+
+- **Typography**: Use the product's existing type system first. For net-new public pages, choose characterful but readable type and keep sizing appropriate to the surface.
+- **Color and theme**: Use semantic tokens and CSS variables. Avoid one-note palettes and default purple/blue gradients unless the brand demands them.
+- **Motion**: Prefer purposeful transitions and small state changes. Use CSS transitions/keyframes unless the app already uses a motion library. Never `transition-all` — list the properties that actually change (e.g. `transition-[opacity,transform]`). Use the shared easing tokens defined in `packages/core/src/styles/agent-native.css` instead of hand-typing curves: `var(--ease-drawer)` (260ms, drawers/app chrome), `var(--ease-collapse)` (200ms, expand/collapse), `var(--ease-out-strong)` (snappy entrances) — in Tailwind, `ease-[var(--ease-collapse)]`. Enter/exit with ease-out, never `ease-in`. Overlays that zoom in must set the Radix origin var (e.g. `origin-[--radix-popover-content-transform-origin]`). Animate `transform`/`opacity`, not width/height/padding/box-shadow. Gate looping or large-movement animations with `motion-reduce:`. Command palettes and keyboard-triggered actions get no animation.
+- **Composition**: Match the workflow. Operational apps should be dense and scannable; marketing or portfolio pages can be more immersive.
+- **Visual assets**: Websites, games, and object-focused pages need real or generated media when images help users understand the subject.
+- **Responsive fit**: Text must not overflow buttons, cards, tabs, sidebars, or fixed-format tools. Use stable dimensions for boards, grids, toolbars, and counters.
+
+**Beat convergence, not just defaults.** You sample toward the "on-distribution" center, so naming what to avoid is not enough: every "don't" needs a "do", or you converge on the next safe option (ban Inter and you reach for Roboto; ban purple gradients and you reach for Space Grotesk + a teal accent on every screen). Commit to one named direction, pair any reference with the reason it fits ("Linear: the quiet confidence of its spacing" — a bare "Linear" collapses back to the average), and match implementation effort to the vision: maximalist wants elaborate motion and effects, minimal wants restraint and precise spacing. When building on an existing app, inspect its tokens/type/components first and treat any drift back to a default as a missing token to pin, not something to re-prompt.
+
+## Agent-Native UI Rules
+
+- Agent-native apps use React, Vite, Tailwind CSS, shadcn/ui, and `@tabler/icons-react`.
+- **Use shadcn/ui primitives for standard UI**: `DropdownMenu`, `Popover`, `Dialog`, `AlertDialog`, `Sheet`, `Tabs`, `Tooltip`, `Select`, `Command`, `Sidebar`, `Table`, `Card`, `Badge`, `Skeleton`, and related primitives.
+- **When touching shadcn/ui components, also read `shadcn-ui` if it exists.** That skill covers `components.json`, CLI docs, component composition, theming, and registry workflows.
+- Check `app/components/ui/` before importing a shadcn component. If a primitive is missing, add it from the app root with `pnpm dlx shadcn@latest add <component>`, then review the generated file.
+- Do not build custom dropdowns, menus, popovers, modals, or confirmations with manual absolute positioning and click-outside effects.
+- Never use browser dialogs (`window.alert`, `window.confirm`, `window.prompt`). Use `AlertDialog`, `Dialog`, or app-specific confirmation UI.
+- Use Tabler icons for all first-party UI icons. Do not add Lucide, Heroicons, inline SVG icon sets, or emoji icons.
+- Use `useActionQuery` and `useActionMutation` from `@agent-native/core/client` for action-backed UI. Standard CRUD should go through actions, not custom `/api/` routes.
+- Keep UI optimistic where possible: update cache and navigation immediately, then reconcile or roll back on mutation result.
+- Custom styles belong in Tailwind classes, component CSS, or the existing global CSS theme file; avoid inline styles.
+
+## shadcn/ui Design Rules
+
+- Use built-in component variants first (`variant`, `size`) before overriding classes.
+- Use semantic tokens (`bg-background`, `text-muted-foreground`, `border-border`, `bg-primary`) instead of raw Tailwind colors for app chrome and reusable components.
+- Use `gap-*` in flex/grid layouts instead of `space-x-*` or `space-y-*`.
+- Use `size-*` when width and height are equal, and `truncate` instead of spelling out overflow/ellipsis/nowrap.
+- Use `cn()` from the local utils alias for conditional classes.
+- Dialog, Sheet, Drawer, and AlertDialog content must have an accessible title. Use `sr-only` only when the visible design already communicates the title.
+- Put menu/list items inside their group primitives: `SelectGroup`, `DropdownMenuGroup`, `CommandGroup`, and equivalents.
+- Use full `Card` composition when the content has a title, description, content, or actions. Do not dump complex cards into a single `CardContent`.
+- Use `ToggleGroup` for small option sets, `Switch` for binary settings, `Checkbox` for multi-select, `RadioGroup` for one-of-many, and `Slider`/inputs for numeric values.
+- For forms, prefer the app's existing shadcn form pattern. If newer `Field`, `FieldGroup`, or `InputGroup` primitives are installed or appropriate to add, use them instead of raw layout divs.
+- Loading states use `Skeleton`, `Progress`, `Spinner`, or the app's existing loading primitives. Empty states should have one clear next action.
+
+## Anti-Patterns
+
+Avoid:
+
+- Generic AI aesthetics: purple gradients, glassy cards everywhere, vague sparkle language, decorative blobs, and context-free hero sections.
+- Custom reimplementations of shadcn primitives.
+- Raw color overrides on shared components when semantic tokens or variants would work.
+- New always-visible controls for rare actions. Prefer menus, popovers, sheets, tabs, collapsibles, or advanced sections.
+- Full-width banners, persistent helper rows, decorative cards, or explanatory chrome for status that could be a compact affordance.
+- Treating progressive disclosure as optional. If a control is not part of the main daily workflow, hide it until context, hover, focus, or explicit user intent makes it relevant.
+- UI cards nested inside other cards.
+- Text or icons that resize or shift fixed-format UI on hover/loading.
+
+## Verification
+
+For substantial frontend work:
+
+1. Run the relevant formatter/checks.
+2. Start the dev server when the app needs one.
+3. Verify with browser screenshots at desktop and mobile widths.
+4. Check interactive states: hover, focus, loading, empty, error, and destructive confirmations.
+
+## Related Skills
+
+- **shadcn-ui** — shadcn CLI, component docs, composition rules, theming, and registries
+- **self-modifying-code** — The agent can edit source code to apply design changes
+- **storing-data** — All data lives in SQL; use actions for data access
+- **actions** — `useActionQuery`/`useActionMutation` hooks for frontend data fetching

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

@@ -0,0 +1,232 @@
+---
+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.
+scope: dev
+metadata:
+  internal: true
+---
+
+# 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 sync events and updates per-source change counters:
+
+   ```ts
+   import { useDbSync } from "@agent-native/core/client";
+   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 request storms in production. A successful mutating action refreshes active `useActionQuery` observers under the `["action"]` prefix. Browser actions carry a tab id so their originating tab ignores the sync echo while other tabs refresh. Legacy apps can opt into broader compatibility with `actionInvalidatePredicate`, but first-party apps should use action-backed or source-versioned query keys. Idle fallback polling runs once per minute; active agent work temporarily uses the faster cadence.
+
+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.
+
+4. **Fallback** polling calls `/_agent-native/poll?since=N`. It runs every 2 seconds until SSE is connected, then relaxes to 15 seconds (`SSE_FALLBACK_INTERVAL_MS`). If SSE is disabled or unavailable (e.g., edge/serverless deployments), polling continues at the 2 s cadence. Polling is the universal serverless fallback: new framework writes are read from the durable `sync_events` log, while the older DB timestamp scan remains as a slower safety net for direct SQL writes and older processes.
+
+5. 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
+- 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
+
+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            | Use targeted source keys, settle bursty list counters, and avoid broad action invalidation.                   |
+
+## 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 Live Sync
+
+Actions work with the same sync system. When a mutating 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. Client components should call actions through those hooks, not with raw action-route fetches.
+
+For custom apps, the best out-of-the-box path is:
+
+1. Put read actions in `actions/` with `defineAction({ http: { method: "GET" } })`.
+2. Put write actions in `actions/` with the default POST/PUT/DELETE behavior.
+3. Call reads from React with `useActionQuery` and writes with `useActionMutation`.
+
+This avoids duplicate `/api/*` JSON CRUD routes and makes agent-created records show up automatically. Raw `useQuery` can still work, but it should include `useChangeVersions(["action", "<domain-source>"])` in the query key for targeted refreshes.
+
+### Auto-emit on mutating actions
+
+The framework emits a change 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,
+  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.
+
+## Keeping Stateful Components In Sync
+
+The `useChangeVersion` / `useActionQuery` pattern above keeps the **query layer** fresh. But components that copy a server value into local React state still go stale on agent edits — refetching the query updates the prop, yet the local copy never re-adopts it. This is a recurring bug.
+
+**Never do this** for a value the agent can mutate:
+
+```ts
+// BUG: `title` is captured once and never re-reads the prop.
+const [title, setTitle] = useState(props.title);
+```
+
+When the agent renames the record, the query refetches, `props.title` updates, but the input still shows the stale value until the component remounts.
+
+**Derived-state surfaces (form fields, inline editors, popovers): use `useReconciledState`.** It re-adopts the authoritative external value when it changes, except while the user is actively editing that field — so agent mutations show up live without clobbering in-progress typing:
+
+```ts
+import { useReconciledState } from "@agent-native/core/client";
+
+// `active` = true while the user is editing this field (focused / dirty).
+const [title, setTitle] = useReconciledState(props.title, { active: isEditing });
+```
+
+**Collaborative rich-text editors are different** — they don't copy a value into `useState`. They reconcile authoritative SQL content into a shared Y.Doc under an `updatedAt` gate with lead-client election. See `real-time-collab` → "Agent edits as a real-time peer editor". Don't reach for `useReconciledState` for a Yjs-backed editor.
+
+| Surface | Keep it fresh with |
+| ------- | ------------------ |
+| React Query reads | `useChangeVersion` / `useActionQuery` (above) |
+| Local edit state copied from a server value (inputs, popovers, inline editors) | `useReconciledState(externalValue, { active })` |
+| Collaborative rich-text editor (Yjs) | `updatedAt`-gated reconcile + `isReconcileLeadClient` — see `real-time-collab` |
+
+## Granular server-side merge for non-body fields
+
+For structured documents (slide decks, form builders, design files) where the
+Yjs body collab would cause LWW conflicts at the container level, pair the
+change-sync `updatedAt` bump with a **granular server-side merge action** that
+accepts targeted per-item operations (add/patch/delete/reorder). Concurrent
+edits to different items both survive at the action level; the `collab` source
+version bump then propagates the merged state to all open clients. See
+`real-time-collab` for the pattern and examples.
+
+## Related Skills
+
+- **storing-data** — Application-state and settings are data stores that sync through change events
+- **context-awareness** — Navigation state writes use jitter prevention to avoid overwriting active edits
+- **actions** — Mutating actions trigger change events
+- **client-methods** — Route details belong in helpers/hooks, not components
+- **self-modifying-code** — Agent code edits trigger change events; rapid edits can cause event storms
+- **real-time-collab** — Collaborative editors reconcile agent edits into a shared Y.Doc, driven by the same change-sync `updatedAt` bump; also the granular server-side merge pattern for structured data