@agent-native/core 0.127.1 → 0.128.0

package/corpus/core/src/templates/chat/.agents/skills/feature-flags/SKILL.md

@@ -1,169 +0,0 @@
----
-name: feature-flags
-description: >-
-  Declare, evaluate, manage, and remove framework feature flags. Use when
-  shipping a capability gradually, targeting users or organizations, or
-  replacing a compile-time rollout switch with a production-safe runtime flag.
-scope: dev
-metadata:
-  internal: true
----
-
-# Feature Flags
-
-A feature flag is a boolean declared in app code, evaluated locally by Core,
-and managed from the Analytics fleet control plane. Code owns whether a flag
-exists. Runtime settings own only its rollout state.
-
-Flags let an app deploy dormant code and turn it on in the real environment
-without another deployment. They are not experiments: do not add variants,
-hypotheses, conversion metrics, exposure tracking, or lifecycle states.
-
-## When to use one
-
-Use a flag for a reversible rollout of a user-facing capability whose dormant
-code is safe to deploy. Flags are useful for production dogfooding, exact-user
-or organization pilots, and deterministic percentage rollouts.
-
-Do not use a flag for authentication, authorization, secrets, audit enablement,
-SSR cache behavior, or another security boundary. Client hiding is presentation
-only; every guarded server action must evaluate the same registered flag.
-
-## Agent workflow
-
-### 1. Declare
-
-Keep definitions in a shared TypeScript module so server and client code use the
-same stable key. Flags are boolean and default-off.
-
-```ts
-import { defineFeatureFlag } from "@agent-native/core/feature-flags/registry";
-
-export const FULL_APP_BUILDING = defineFeatureFlag({
-  key: "full-app-building",
-  displayName: "Full app building",
-  description: "Create and edit Fusion-backed applications.",
-});
-```
-
-Keys are immutable, never reused, and contain only letters, numbers, dots,
-underscores, or hyphens. Prefer a concise app-owned name. Do not create flag
-definitions or rollout rows from Analytics.
-
-### 2. Register
-
-Register app definitions from a Nitro plugin before actions are discovered.
-Do not add app-specific flags to a Core registry.
-
-```ts
-import { createFeatureFlagsPlugin } from "@agent-native/core/server";
-
-import { FULL_APP_BUILDING } from "../../shared/feature-flags.js";
-
-export default createFeatureFlagsPlugin({ flags: [FULL_APP_BUILDING] });
-```
-
-### 3. Guard server and client
-
-The server action is the enforcement boundary:
-
-```ts
-import { isFeatureFlagEnabled } from "@agent-native/core/feature-flags";
-
-run: async (args, ctx) => {
-  if (!(await isFeatureFlagEnabled(FULL_APP_BUILDING, ctx))) {
-    throw new Error("Full app building is not enabled for this account.");
-  }
-  // guarded operation
-}
-```
-
-Use the client hook only to hide or reveal hydrated UI:
-
-```tsx
-import { useFeatureFlag } from "@agent-native/core/client/feature-flags";
-
-const enabled = useFeatureFlag(FULL_APP_BUILDING.key);
-return enabled ? <FullAppOption /> : null;
-```
-
-The client hook intentionally returns false while loading or for an unknown
-flag. Never replace that fail-closed behavior with app-local bucketing or a
-compile-time fallback. Never evaluate personalized flags in the public SSR
-shell; it is shared and cached for every visitor.
-
-### 4. Verify and roll out
-
-1. Verify the off path before changing rollout state.
-2. Confirm the registered flag appears in **Analytics → Feature flags** for the
-   app and is Off by default.
-3. Use **Enable for me** for initial production dogfood.
-4. Expand to exact emails, organization IDs, or a percentage only from
-   Analytics.
-5. Confirm the client presentation and authoritative server action agree.
-
-## Management contract
-
-Core mounts three actions in registered apps:
-
-| Action | Purpose |
-| --- | --- |
-| `get-feature-flags` | Return the current caller's evaluated boolean values. |
-| `list-feature-flags` | Return definitions and rollout metadata to an authorized operator. |
-| `set-feature-flag` | Atomically turn a flag off, enable it for the operator, or replace targeting rules. |
-
-Analytics calls the app-local operator actions through narrowly scoped A2A
-delegation. Tokens require an exact audience, organization, scope, operator
-role, and audit correlation id. Management is permission-checked and audited
-by the target app. Never manage flags through generic settings routes, raw SQL,
-or per-app toggle UIs.
-
-## Rollout semantics
-
-The operator modes are **Off**, **Targeted**, and **Everyone**. Core stores them
-as `off`, `rules`, and `on`.
-
-Targeted rules combine exact normalized emails, exact organization IDs, and a
-percentage with OR semantics. Exact matches are checked first. Percentage
-buckets use Core's stable hash of the flag key and authenticated user identity;
-anonymous callers fail closed. Raising a percentage preserves the users already
-included at a lower percentage. Do not implement bucketing in app code.
-
-Unknown definitions, missing state, malformed state, storage errors, and
-evaluation errors all return the code default (`false` in v1). Explicit Off
-wins over every target; Everyone enables every authenticated caller.
-
-## Remove a flag
-
-After a rollout is permanent:
-
-1. Replace guarded branches with the chosen behavior.
-2. Delete the server and client gates.
-3. Delete the definition and registration entry.
-4. Verify the flag disappears from the Analytics fleet.
-5. Remove stale tests and rollout instructions.
-
-A permanent flag is just an if statement with a pension plan.
-
-## Verification checklist
-
-- Unknown and unregistered keys evaluate false.
-- UI hiding and server enforcement use the same registered key.
-- Exact-user, organization, deterministic percentage, Everyone, and Off paths
-  have focused tests.
-- Increasing a percentage is monotonic; anonymous percentage evaluation is off.
-- Unauthorized callers cannot list targeting details or mutate flags.
-- Mutations are atomic, read back stored state, emit refresh, and appear in the
-  audit log with the flag key.
-- Analytics represents ready, no-definition, unsupported, forbidden, legacy,
-  and unreachable directory apps honestly.
-- Future agents can find this skill from root `AGENTS.md`, and
-  `pnpm guard:workspace-skills` passes after syncing generated copies.
-
-## Related skills
-
-- **adding-a-feature** — preserve UI/action/instruction/application-state parity
-- **actions** — define and call guarded app operations
-- **audit-log** — inspect automatic action mutation history
-- **reliable-mutations** — make rollout changes atomic and provable
-- **security** — keep security controls out of feature flags

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

@@ -1,174 +0,0 @@
----
-name: frontend-design
-description: >-
-  Sets the visual direction for a new or redesigned surface, with production
-  quality that avoids generic AI aesthetics. Use when building a new page,
-  app, or marketing surface, defining visual identity, or doing a design pass
-  ("make this look good"). Do not load it for routine UI edits: adding a field
-  to an existing form, fixing spacing, wiring a button, or changing copy.
-scope: dev
-license: Complete terms in LICENSE.txt
-source: https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md
-local-changes: >-
-  Description narrowed and Verification rescoped deliberately; an upstream sync
-  must not restore the broad auto-load triggers or screenshot-everything step.
-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.
-
-### Progressive Disclosure Is A Design Requirement
-
-Treat an all-at-once interface as a defect to fix during design, not as a
-styling preference. Before coding, inventory every piece of content and action
-on the surface, then assign each one to the smallest useful visibility level:
-
-1. **Immediate** — the page title, current state, one primary action, and the
-   compact context needed to choose what to do next.
-2. **Expanded** — the details needed for the selected item or active workflow.
-3. **On demand** — advanced settings, diagnostics, credentials, metadata,
-   destructive actions, documentation, and rarely used tools.
-
-Use single-select accordions or simple disclosure rows for sibling panels when
-the user is choosing one item at a time. Inside an expanded panel, keep another
-layer for independent concerns instead of dumping every form, explanation, and
-secondary action into the first reveal. Prefer one flat panel with alignment,
-dividers, and whitespace over nested cards; provider or product icons should
-not receive decorative borders or containers unless the container communicates
-state or interaction. A collapsed row should still show the item name, status,
-and a concise summary so the user can scan the whole surface without opening
-everything.
-
-Before shipping, ask: “What can disappear until the user asks for it?” Then
-verify collapsed, expanded, loading, empty, error, and narrow-width states.
-If the first viewport contains multiple forms, repeated explanatory copy,
-documentation links, and controls for unrelated tasks, the surface has not
-passed this requirement yet.
-
-- **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 and Vite. The default adapter uses Tailwind CSS,
-  shadcn/ui, and `@tabler/icons-react`, but an app may register a different
-  company design system in `app/design-system.ts`.
-- **Use the app's design-system seam for standard UI.** Inspect
-  `app/design-system.ts`, `ToolkitProvider`, and the local UI adapter directory
-  before choosing a primitive. Use shadcn primitives when they are the active
-  adapter; use the registered company components when they are not.
-- **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.
-- Pages, routes, and domain components must import controls through the app's
-  local adapter path, usually `@/components/ui/*`. Never import
-  `@agent-native/toolkit/ui/*` directly in app product code.
-- Toolkit/Core feature presentation flows through the semantic components from
-  `@agent-native/toolkit/design-system`. Their props express intent, emphasis,
-  size, controlled values, and behavior; they do not require Tailwind, CVA, or
-  `className`.
-- For deeper feature customization, consume the feature-level headless
-  controller through its product render slot. The same controller must power
-  the default and custom views. Eject the smallest supported unit only after
-  tokens, semantic components, controllers, and slots are insufficient.
-- 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
-
-Match verification effort to the size of the change. For one component, one
-form, one page, or a restyle, run the app's existing checks — formatter,
-`pnpm typecheck`, existing tests — and stop there.
-
-Escalate to browser verification only when the user asks for it, or when the
-change is a multi-step user-visible flow that cannot be confirmed any other
-way. Never author a new Playwright/Puppeteer script, add a browser-automation
-dependency, or stand up an e2e harness to check work the user did not ask you
-to test that way; use an available browser tool, or say what you could not
-verify.
-
-For substantial frontend work:
-
-1. Run the relevant formatter/checks.
-2. Start the dev server when the app needs one.
-3. Verify with the available browser tooling at desktop and mobile widths.
-4. Check interactive states: hover, focus, loading, empty, error, and destructive confirmations.
-5. When registering or changing a company adapter, run
-   `@agent-native/toolkit/conformance`, including mixed-overlay focus,
-   `portalContainer`, and z-index stacking checks.
-
-## Related Skills
-
-- **shadcn-ui** — shadcn CLI, component docs, composition rules, theming, and registries
-- **customizing-agent-native** — Design-system registration, feature controllers, product slots, conformance, and ejection
-- **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/corpus/core/src/templates/chat/.agents/skills/real-time-sync/SKILL.md

@@ -1,232 +0,0 @@
----
-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/hooks";
-   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/hooks";
-   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/hooks";
-
-  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. Hidden tabs keep that shared transport alive by default: SSE stays connected and active fallback polling relaxes to a 10-second floor (idle polling remains once per minute). Pass `pauseWhenHidden: true` only for a consumer that explicitly must stop all hidden-tab sync.
-
-## 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/hooks";
-
-// `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