@agent-native/core 0.14.8 → 0.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.14.8",
+  "version": "0.15.0",
   "type": "module",
   "description": "Framework for agent-native application development — where AI agents and UI share state via files",
   "license": "MIT",
@@ -48,6 +48,7 @@
     "./extensions/url-safety": "./dist/extensions/url-safety.js",
     "./tools/url-safety": "./dist/extensions/url-safety.js",
     "./file-upload": "./dist/file-upload/index.js",
+    "./file-upload/actions/upload-image": "./dist/file-upload/actions/upload-image.js",
     "./resources": "./dist/resources/index.js",
     "./resources/store": "./dist/resources/store.js",
     "./resources/metadata": "./dist/resources/metadata.js",
@@ -92,6 +93,15 @@
     "tsconfig.base.json",
     "src/templates"
   ],
+  "scripts": {
+    "build": "tsc && node scripts/finalize-build.mjs",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest --run src",
+    "prepack": "cp ../../README.md ./README.md",
+    "prepublishOnly": "npm run build",
+    "release": "npm version patch && npm publish --access public"
+  },
   "dependencies": {
     "@amplitude/analytics-browser": "^2.41.1",
     "@anthropic-ai/sdk": "^0.90.0",
@@ -263,7 +273,7 @@
     "@react-router/fs-routes": "^7.13.1",
     "@supabase/supabase-js": "^2.49.0",
     "@tabler/icons-react": "^3.40.0",
-    "@tailwindcss/vite": "^4.2.4",
+    "@tailwindcss/vite": "catalog:",
     "@tanstack/react-query": "^5.99.2",
     "@types/better-sqlite3": "^7.6.13",
     "@types/diff-match-patch": "^1.0.36",
@@ -283,17 +293,10 @@
     "node-pty": "^1.1.0",
     "react": "^19.2.5",
     "react-router": "^7.13.1",
-    "tailwindcss": "^4.2.4",
+    "tailwindcss": "catalog:",
     "typescript": "^6.0.3",
-    "vite": "8.0.3",
+    "vite": "catalog:",
     "vitest": "^4.1.5",
     "ws": "^8.18.0"
-  },
-  "scripts": {
-    "build": "tsc && node scripts/finalize-build.mjs",
-    "dev": "tsc --watch",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest --run src",
-    "release": "npm version patch && npm publish --access public"
   }
-}
+}

package/src/templates/default/.agents/skills/adding-a-feature/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: adding-a-feature
+description: >-
+  The four-area checklist every new feature in this app must complete. Use
+  when adding any feature, integration, or capability to keep the agent and
+  UI in parity.
+---
+
+# Adding a Feature — The Four-Area Checklist
+
+## Rule
+
+Every new feature MUST update all four areas. Skipping any one breaks the agent-native contract — the agent and UI must always be equal partners.
+
+## Why
+
+Agent-native apps are defined by parity: everything the UI can do, the agent can do, and vice versa. A feature that only has UI is invisible to the agent. A feature that only has actions is invisible to the user. A feature without app-state sync means the agent is blind to what the user is doing. And **a feature without auto-refresh wiring means the agent's writes are silently invisible until the user manually reloads** — that breaks the framework's #1 promise.
+
+## The Checklist
+
+### 1. UI Component
+
+Build the user-facing interface — a page, component, dialog, or route. Use `useActionQuery` and `useActionMutation` from `@agent-native/core/client` for data fetching and mutations. You rarely need custom `/api/` routes.
+
+**Auto-refresh on agent writes is non-negotiable** — when the agent mutates the data this UI shows, the UI must reflect the change without a manual refresh. Two paths, pick the right one:
+
+- **`useActionQuery` (preferred)** — automatically covered. The framework's `useDbSync` invalidates `["action"]` on every change event, so every `useActionQuery` hook refetches when the agent runs an action. No extra wiring required.
+
+- **Raw `useQuery` with a custom key** — needs explicit wiring. Fold `useChangeVersions([<source>, "action"])` from `@agent-native/core/client` into the `queryKey` and set `placeholderData: (prev) => prev`. The `"action"` source is the reliable signal — the agent runner emits it after every successful tool call. The resource-specific source (e.g. `"settings"`, `"app-state"`) is bonus. Without this wiring, agent writes will be invisible until manual refresh.
+
+  ```tsx
+  import { useChangeVersions } from "@agent-native/core/client";
+  import { useQuery } from "@tanstack/react-query";
+
+  function useItem(id: string) {
+    const v = useChangeVersions(["items", "action"]);
+    return useQuery({
+      queryKey: ["item", id, v],
+      queryFn: () => fetchItem(id),
+      placeholderData: (prev) => prev, // no flicker on refetch
+    });
+  }
+  ```
+
+  See the `real-time-sync` skill for the full pattern and source catalog.
+
+### 2. Action
+
+Create an action in `actions/` using `defineAction`. This serves double duty: the agent calls it as a tool, and the framework auto-exposes it as an HTTP endpoint at `/_agent-native/actions/:name` for the UI to call. Set `http: { method: "GET" }` for read actions, leave default for writes, or set `http: false` for agent-only actions like `navigate` and `view-screen`.
+
+### 3. Skills / Instructions
+
+Update `AGENTS.md` (the per-app guide) and/or create a skill in `.agents/skills/` if the feature introduces patterns the agent needs to know. At minimum, add the new actions to the action table in the template's `AGENTS.md`.
+
+### 4. Application State Sync
+
+Expose navigation and selection state so the agent knows what the user is looking at. Write to the `navigation` app-state key on route changes. Update the `view-screen` action to fetch relevant data for the new feature. Add a `navigate` command if the agent needs to open the new view.
+
+## Anti-Patterns
+
+- **UI without actions** — The user can create things but the agent cannot. Breaks parity.
+- **Actions without UI** — The agent can do something the user cannot. Less common but still breaks parity.
+- **Mutations without auto-refresh wiring** — The agent says "done!" but the screen doesn't change until the user hits reload. This is the most common silent regression. If you used `useActionQuery` you're covered; if you used raw `useQuery`, fold `useChangeVersions` into the key. Always test by asking the agent to mutate the data and watching the UI without refreshing.
+
+## Verification
+
+For every new feature, manually verify:
+
+1. Can the user perform the operation from the UI?
+2. Can the agent perform the operation via an action (`pnpm action <name>`)?
+3. When the agent runs the action, **does the UI update within a second or two without a manual refresh**? If not, your query is missing `useActionQuery` or `useChangeVersions` wiring — go back to step 1.
+4. Does `view-screen` return the new feature's state when the user is on that page?

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

@@ -12,58 +12,81 @@ source: https://github.com/anthropics/skills/blob/main/skills/frontend-design/SK
 
 # Frontend Design
 
-This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.
+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 provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints.
+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, understand the context and commit to a BOLD aesthetic direction:
-- **Purpose**: What problem does this interface solve? Who uses it?
-- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
-- **Constraints**: Technical requirements (framework, performance, accessibility).
-- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember?
+Before coding, decide:
 
-**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work — the key is intentionality, not intensity.
+- **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 (HTML/CSS/JS, React, Vue, etc.) that is:
-- Production-grade and functional
-- Visually striking and memorable
-- Cohesive with a clear aesthetic point-of-view
-- Meticulously refined in every detail
+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.
 
-## Frontend Aesthetics Guidelines
+## Aesthetic Guidelines
 
-Focus on:
-- **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font.
-- **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
-- **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (`animation-delay`) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
-- **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
-- **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays.
+- **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.
+- **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.
 
-## Anti-Patterns to Avoid
+## Agent-Native UI Rules
 
-NEVER use generic AI-generated aesthetics like:
-- Overused font families (Inter, Roboto, Arial, system fonts)
-- Clichéd color schemes (particularly purple gradients on white backgrounds)
-- Predictable layouts and component patterns
-- Cookie-cutter design that lacks context-specific character
+- 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.
 
-Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.
+## shadcn/ui Design Rules
 
-## Implementation Notes
+- 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.
 
-**Match implementation complexity to the aesthetic vision.** Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.
+## Anti-Patterns
 
-In the agent-native framework context:
-- Agent-native apps use React 18, Vite, TailwindCSS, and shadcn/ui
-- Custom styles go in component CSS or Tailwind classes — never inline styles
-- For complex visual effects, use a `<style>` tag in the component or a dedicated CSS file
-- Fonts can be loaded from Google Fonts via `@import` in a CSS file or `<link>` in `index.html`
-- Animation libraries: prefer CSS transitions and keyframes; use Framer Motion for complex sequences
-- All new UI components should be placed in `app/components/`
+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.
+- 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** — Design configuration can be stored in the settings table for agent-editable theming
+- **storing-data** — All data lives in SQL; use actions for data access
+- **actions** — `useActionQuery`/`useActionMutation` hooks for frontend data fetching

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

@@ -20,35 +20,47 @@ The agent modifies data in SQL, but the UI runs in the browser. Polling bridges
 
 1. **Server** increments a version counter on every database write. The `/_agent-native/poll` endpoint returns the current version and any events since the last poll.
 
-2. **Client** polls for changes and invalidates React Query caches:
+2. **Client** polls for changes and updates per-source counters:
 
    ```ts
    import { useDbSync } from "@agent-native/core";
-   useDbSync({ queryClient, queryKeys: ["items", "settings"] });
+   useDbSync({ queryClient });
    ```
 
-3. When the agent writes to the database, the version increments, polling detects it, and React Query refetches the affected queries.
+3. **Templates fold a per-source counter into the relevant query key.** When the source advances, only the dependent query refetches:
+
+   ```ts
+   import { useChangeVersion } from "@agent-native/core/client";
+
+   const v = useChangeVersion("items"); // or "settings", "dashboards", "action", etc.
+   const { data } = useQuery({
+     queryKey: ["items", v],
+     queryFn: fetchItems,
+     placeholderData: (prev) => prev,
+   });
+   ```
+
+4. When the agent writes to the database, the server emits a `recordChange({ source, ... })` event. `useDbSync` bumps the matching counter; any query with that counter in its key refetches; everything else stays untouched.
 
 ## Don't
 
 - Don't create manual polling loops — `useDbSync()` handles it (polls every 2 seconds by default)
 - Don't create your own fetch-based polling alongside `useDbSync` — use the `onEvent` callback for custom handling
 
-## Query Key Mapping
+## Tuning refetch behavior
 
-By default, `useDbSync` invalidates all listed query keys on every change. For apps with multiple data models, this causes unnecessary refetches. Use event-based filtering via the `onEvent` callback:
+`useDbSync` invalidates every active query on any non-own change event. The `onEvent` callback still fires with each change event, so templates can layer surgical extras on top — for example, invalidating an inactive query that wouldn't otherwise refetch:
 
 ```ts
 useDbSync({
   queryClient,
-  queryKeys: [], // don't auto-invalidate everything
   onEvent: (data) => {
     if (data.source === "settings") {
-      queryClient.invalidateQueries({ queryKey: ["settings"] });
-    } else if (data.source === "app-state") {
-      queryClient.invalidateQueries({ queryKey: ["navigate-command"] });
-    } else {
-      queryClient.invalidateQueries({ queryKey: ["items"] });
+      // Force a refetch even when not actively observed
+      queryClient.invalidateQueries({
+        queryKey: ["settings"],
+        refetchType: "all",
+      });
     }
   },
 });
@@ -66,11 +78,11 @@ useQuery({
 
 ## Troubleshooting
 
-| Symptom                            | Check                                                                                                          |
-| ---------------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| UI not updating after agent writes | Is `useDbSync` called with the correct `queryClient`? Are the `queryKeys` matching your `useQuery` keys?       |
-| Poll endpoint not responding       | Is `/_agent-native/poll` accessible? Is the server running?                                                    |
-| High CPU / event storms            | The agent is writing rapidly. Add `staleTime` to queries and use event-based filtering.                        |
+| 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?                                              |
+| High CPU / event storms            | The agent is writing rapidly. Add `staleTime` to queries to debounce refetches.                          |
 
 ## Jitter Prevention
 
@@ -93,7 +105,6 @@ import { TAB_ID } from "@/lib/tab-id";
 
 useDbSync({
   queryClient,
-  queryKeys: ["app-state", "settings"],
   ignoreSource: TAB_ID,
 });
 ```

package/src/templates/default/.agents/skills/shadcn-ui/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: shadcn-ui
+description: >-
+  Use when adding, updating, debugging, styling, or composing shadcn/ui
+  components, forms, dialogs, menus, charts, sidebars, themes, registries, or
+  any project with a components.json file.
+source: https://ui.shadcn.com/docs/skills
+---
+
+# shadcn/ui
+
+This skill keeps shadcn/ui work project-aware. Components are source files in the app, so always inspect the local project before adding, importing, or rewriting them.
+
+## First Steps
+
+1. Work from the app root that owns `components.json`.
+2. Run `pnpm dlx shadcn@latest info --json` when you need current project context: framework, Tailwind version, aliases, icon library, installed components, and resolved paths.
+3. Use the actual aliases from `components.json` or `shadcn info`; do not assume `@/components/ui` if the project says otherwise.
+4. Check `app/components/ui/` or the resolved `ui` path before importing a component.
+5. For unfamiliar components, run `pnpm dlx shadcn@latest docs <component>` and read the returned docs or examples before coding.
+
+## Adding Or Updating Components
+
+- Add missing primitives with `pnpm dlx shadcn@latest add <component>` from the app root.
+- Before overwriting an existing component, use `pnpm dlx shadcn@latest add <component> --dry-run` and `--diff` to inspect the change.
+- After adding registry code, read the generated files. Fix import aliases, icon imports, missing subcomponents, and composition issues before using the component.
+- Do not fetch raw component files manually from GitHub when the shadcn CLI can resolve the registry item.
+- If a user asks to add a third-party block but does not name a registry, ask which registry to use instead of guessing.
+
+## Component Composition
+
+- Use existing primitives before custom markup: `Alert` for callouts, `Badge` for small status labels, `Separator` for dividers, `Skeleton` for placeholders, `Table` for tabular data, and `Card` for framed content.
+- Use full card anatomy when appropriate: `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, and `CardFooter`.
+- Dialog, Sheet, Drawer, and AlertDialog content must include an accessible title. Use visually hidden titles only when the visible UI already communicates the title.
+- Put items inside their group components: `SelectItem` in `SelectGroup`, `DropdownMenuItem` in `DropdownMenuGroup`, `CommandItem` in `CommandGroup`, and equivalent menu groups.
+- `TabsTrigger` belongs inside `TabsList`.
+- `Avatar` always needs `AvatarFallback`.
+- Buttons do not have magic loading props. Compose loading with `disabled`, `Spinner`, and clear text.
+
+## Forms And Inputs
+
+- Use the app's shadcn form primitives instead of raw div stacks.
+- If `Field`, `FieldGroup`, `FieldSet`, or `InputGroup` are installed or worth adding, use them for form layout, grouped fields, and input add-ons.
+- Do not place buttons inside inputs with absolute positioning. Use `InputGroup` and `InputGroupAddon` when available.
+- Use `ToggleGroup` for small option sets, `RadioGroup` for one-of-many choices, `Checkbox` for multi-select, `Switch` for settings toggles, `Select` or `Combobox` for predefined choices, and `Slider` or numeric input for numeric values.
+- Validation must be accessible: pair visual invalid states with `aria-invalid`, and connect descriptions/errors to controls.
+
+## Styling And Theming
+
+- Use semantic tokens (`bg-background`, `text-foreground`, `text-muted-foreground`, `bg-primary`, `border-border`, `text-destructive`) instead of raw colors for reusable app UI.
+- Prefer built-in variants and sizes before custom classes.
+- Use `className` mostly for layout and spacing; avoid overriding component colors and typography unless the component is intentionally being extended.
+- Use `gap-*` instead of `space-x-*` / `space-y-*`.
+- Use `size-*` when width and height are equal.
+- Use `truncate` for single-line clipping.
+- Use `cn()` for conditional classes.
+- Do not add manual `z-index` to overlay primitives unless you are fixing a verified stacking bug.
+- Add custom colors as CSS variables in the existing Tailwind CSS file reported by shadcn info. For Tailwind v4, register variables with `@theme inline`.
+
+## Icons
+
+- Agent-native apps use `@tabler/icons-react`. Do not add `lucide-react` because a registry example used it.
+- If registry code imports a different icon package, replace those imports with Tabler equivalents before finishing.
+- Let shadcn components size icons through their CSS. Avoid manual icon sizing inside buttons, menus, alerts, and sidebars unless the local component API requires it.
+
+## Base-Specific APIs
+
+Check the project context before using trigger composition APIs:
+
+- Radix-based components use `asChild` for custom triggers.
+- Base UI components may use `render` and sometimes `nativeButton={false}`.
+
+Do not wrap triggers in extra divs just to place a Button or Link inside them.
+
+## Related Skills
+
+- **frontend-design** — Product UX, visual direction, responsive polish, and verification
+- **actions** — Data fetching and mutation patterns for agent-native apps
+- **security** — User data, forms, external input, and action safety

package/src/templates/default/AGENTS.md

@@ -9,7 +9,7 @@ This is an **@agent-native/core** application -- the AI agent and UI share state
 1. **Shared SQL database** -- All app state lives in SQL (SQLite locally, cloud DB via `DATABASE_URL` in production). Core stores: `application_state`, `settings`, `oauth_tokens`, `sessions`, `resources`.
 2. **All AI through agent chat** -- No inline LLM calls. UI delegates to the AI via `sendToAgentChat()` / `agentChat.submit()`.
 3. **Actions for agent operations** -- `pnpm action <name>` dispatches to callable action files in `actions/`.
-4. **Polling for real-time sync** -- Database writes trigger version counter increments that the UI polls to stay in sync.
+4. **Polling for real-time sync** -- Database writes trigger version counter increments that the UI polls to stay in sync. **When you (the agent) write data, the UI must reflect the change without a manual refresh.** This is non-negotiable. Use `useActionQuery` (auto-covered) or fold `useChangeVersions([<source>, "action"])` into raw `useQuery` keys. See the `real-time-sync` and `adding-a-feature` skills.
 5. **Agent can update code** -- The agent can modify this app's source code directly.
 
 ### Authentication
@@ -90,28 +90,31 @@ You do NOT get auto-injected screen state. **Call `pnpm action view-screen` at t
 
 Skills in `.agents/skills/` provide detailed guidance for each architectural rule. Read them before making changes.
 
-| Skill                 | When to read                                                    |
-| --------------------- | --------------------------------------------------------------- |
-| `storing-data`        | Before storing or reading any app state                         |
-| `delegate-to-agent`   | Before adding LLM calls or AI delegation                        |
-| `actions`             | Before creating or modifying actions                            |
-| `real-time-sync`      | Before wiring up real-time UI sync                              |
-| `self-modifying-code` | Before editing source, components, or styles                    |
-| `capture-learnings`   | Before recording user preferences or corrections                |
-| `frontend-design`     | Before building or restyling any UI component, page, or layout  |
-| `agent-engines`       | Before switching LLM providers or registering a custom engine   |
-| `notifications`       | Before surfacing alerts/progress to the user or adding channels |
-| `progress`            | Before running any task that takes more than a few seconds      |
+| Skill                 | When to read                                                                      |
+| --------------------- | --------------------------------------------------------------------------------- |
+| `adding-a-feature`    | **Read first when adding ANY new feature** — the four-area parity checklist       |
+| `real-time-sync`      | Before wiring data fetching for anything the agent can mutate (must auto-refresh) |
+| `storing-data`        | Before storing or reading any app state                                           |
+| `delegate-to-agent`   | Before adding LLM calls or AI delegation                                          |
+| `actions`             | Before creating or modifying actions                                              |
+| `self-modifying-code` | Before editing source, components, or styles                                      |
+| `capture-learnings`   | Before recording user preferences or corrections                                  |
+| `frontend-design`     | Before building or restyling any UI component, page, or layout                    |
+| `shadcn-ui`           | Before adding, updating, or debugging shadcn/ui components                        |
+| `agent-engines`       | Before switching LLM providers or registering a custom engine                     |
+| `notifications`       | Before surfacing alerts/progress to the user or adding channels                   |
+| `progress`            | Before running any task that takes more than a few seconds                        |
 
 ## When Adding Features
 
-As you build out this app, follow this checklist for each new feature:
+**Read the `adding-a-feature` skill first** — it has the full four-area checklist (UI / Action / Skills / App-State). Quick summary:
 
-1. **Add navigation state entries** -- extend `app/hooks/use-navigation-state.ts` to track new routes
-2. **Enhance view-screen** -- make the view-screen script return relevant context for the new view
-3. **Create domain actions** -- add scripts for CRUD operations on new data models
-4. **Create domain skills** -- add `.agents/skills/<feature>/SKILL.md` documenting the data model, storage patterns, and agent operations
-5. **Update this AGENTS.md** -- add the new actions, state keys, and common tasks
+1. **Add navigation state entries** — extend `app/hooks/use-navigation-state.ts` to track new routes
+2. **Enhance view-screen** — make the view-screen script return relevant context for the new view
+3. **Create domain actions** — add actions in `actions/` for CRUD operations on new data models
+4. **Wire UI for auto-refresh** — use `useActionQuery` (auto-covered) OR fold `useChangeVersions([<source>, "action"])` into raw `useQuery` keys with `placeholderData`. When the agent mutates this data, the UI must reflect the change without a manual refresh. See `real-time-sync` skill.
+5. **Create domain skills** — add `.agents/skills/<feature>/SKILL.md` documenting the data model, storage patterns, and agent operations
+6. **Update this AGENTS.md** — add the new actions, state keys, and common tasks
 
 ---
 

package/src/templates/default/actions/navigate.ts

@@ -35,6 +35,9 @@ export async function run(args: Record<string, string>): Promise<string> {
   const nav: Record<string, string> = {};
   if (args.view) nav.view = args.view;
   if (args.path) nav.path = args.path;
+  // Unique-per-write token so the UI's `use-navigation-state` hook can dedup
+  // race-driven re-reads of the same command.
+  nav._writeId = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
   await writeAppState("navigate", nav);
   return `Navigating to ${args.view || args.path}`;
 }

package/src/templates/default/app/hooks/use-navigation-state.ts

@@ -1,4 +1,4 @@
-import { useEffect } from "react";
+import { useEffect, useRef } from "react";
 import { useLocation, useNavigate } from "react-router";
 import { useQuery, useQueryClient } from "@tanstack/react-query";
 import {
@@ -10,6 +10,10 @@ import {
 export interface NavigationState {
   view: string;
   path?: string;
+  /** Optional unique-per-write token. Used by the UI to dedup the same
+   * command being re-read when the fire-and-forget DELETE below loses its
+   * race against the next polling refetch. */
+  _writeId?: string;
 }
 
 export function useNavigationState() {
@@ -31,7 +35,11 @@ export function useNavigationState() {
     }).catch(() => {});
   }, [location.pathname]);
 
-  const { data: navCommand } = useQuery({
+  // Default React Query structuralSharing reuses the previous reference when
+  // the JSON is unchanged, so repeated invalidations driven by `useDbSync`
+  // (which fire on every relevant app-state event) don't re-fire the
+  // useEffect with a brand-new object containing the same command.
+  const { data: navCommand } = useQuery<NavigationState | null>({
     queryKey: ["navigate-command"],
     queryFn: async () => {
       const res = await fetch(
@@ -39,19 +47,35 @@ export function useNavigationState() {
       );
       if (!res.ok) return null;
       const data = await res.json();
-      return data ? { ...data, _ts: Date.now() } : null;
+      return data ?? null;
     },
     refetchInterval: 2_000,
-    structuralSharing: false,
   });
 
+  const lastProcessedDedupKeyRef = useRef<string | null>(null);
+
   useEffect(() => {
     if (!navCommand) return;
+    const cmd = navCommand;
+    const dedupKey =
+      cmd._writeId ?? JSON.stringify({ view: cmd.view, path: cmd.path });
+    if (lastProcessedDedupKeyRef.current === dedupKey) {
+      // Same command we already handled — the consume-DELETE races against
+      // the next polling refetch, so when it loses the same command can show
+      // up again. Re-fire DELETE and bail rather than navigate again.
+      fetch(agentNativePath("/_agent-native/application-state/navigate"), {
+        method: "DELETE",
+        headers: { "X-Agent-Native-CSRF": "1" },
+      }).catch(() => {});
+      qc.setQueryData(["navigate-command"], null);
+      return;
+    }
+    lastProcessedDedupKeyRef.current = dedupKey;
+
     fetch(agentNativePath("/_agent-native/application-state/navigate"), {
       method: "DELETE",
       headers: { "X-Agent-Native-CSRF": "1" },
     }).catch(() => {});
-    const cmd = navCommand as NavigationState;
 
     const path = routerPath(cmd.path || pathFromView(cmd.view));
     navigate(path);