@agent-native/core 0.14.8 → 0.15.1

package/docs/content/dispatch.md

@@ -17,7 +17,7 @@ Reach for Dispatch when any of these are true:
 
 - You're running a [multi-app workspace](/docs/multi-app-workspace) — mail, calendar, analytics, content, recruiting — and you don't want one Slack bot per app.
 - You want **one inbox for "the agent"** so users DM a single bot and the right specialist app picks up the work behind the scenes.
-- You have **workspace-wide secrets** (Stripe key, OpenAI key, third-party API tokens) that several apps need but you'd rather grant per-app than copy into every `.env`.
+- You have **workspace-wide secrets** (Stripe key, OpenAI key, third-party API tokens) that several apps need and you want one vault instead of copying values into every `.env`.
 - You want a **runtime approval flow** in front of sensitive changes (saved destinations, policy edits) so non-admins can request and admins can sign off without a code deploy.
 - You want **shared skills, instructions, and agent profiles** that every app in the workspace inherits — change once, reach all.
 
@@ -35,7 +35,7 @@ See [Messaging](/docs/messaging) for the credentials and webhook URLs for each p
 
 ### Secret vault
 
-Store credentials once in Dispatch's vault and grant them to the apps that need them. Non-admins can **request** a secret for an app; admins **approve**, which creates the secret + grant in one step. Every read, grant, sync, and rotation is captured in an audit log. `sync-vault-to-app` pushes granted secrets into the target app's env so you don't have to redeploy or re-paste anything.
+Store credentials once in Dispatch's vault. By default, vault access is **all apps**: every saved key is available to every workspace app, and `sync-vault-to-app` pushes the full vault to the target app. Workspaces that need stricter separation can switch the vault to **manual** mode, where explicit per-app grants are required before sync. Non-admins can **request** a secret for an app; admins **approve**, which creates the secret and, in manual workflows, the grant. Every read, grant, sync, and rotation is captured in an audit log.
 
 This is what makes "rotate the OpenAI key" a one-click operation across ten apps instead of ten PRs.
 
@@ -83,7 +83,7 @@ Three short steps:
 2. **Connect messaging.** Open **Settings → Messaging** in Dispatch and click connect for Slack, Email, Telegram, or WhatsApp. The form fields match the env vars in the [Messaging](/docs/messaging) doc — refer there for what each platform needs.
 3. **Add other apps.** Run `npx @agent-native/core add-app` from the workspace root for each domain app. They auto-appear as A2A peers in Dispatch's `list-workspace-apps` — no manual registration, no agent-card editing. Dispatch will start delegating to them as soon as their agent cards are reachable.
 
-Then add credentials to the vault, grant them to the apps that need them, and (optionally) author workspace skills under **Resources** and sync them out.
+Then add credentials to the vault, sync them to apps, and (optionally) author workspace skills under **Resources** and sync them out. If you need per-app secret isolation, switch the vault access setting to manual before granting individual apps.
 
 ## See also {#see-also}
 

package/docs/content/multi-app-workspace.md

@@ -146,6 +146,11 @@ Active organization flows automatically: `session.orgId` → `AGENT_ORG_ID` →
 
 The workspace root `.env` is loaded into every app automatically. Put shared keys once at the root — `ANTHROPIC_API_KEY`, `A2A_SECRET`, `BETTER_AUTH_SECRET`, `DATABASE_URL`, `BUILDER_PRIVATE_KEY`, etc. — and every app picks them up. Per-app overrides go in `apps/<name>/.env` and win on conflict.
 
+For runtime app credentials, prefer the Dispatch vault over hand-editing `.env`
+files. The vault defaults to all-apps access, so every saved vault key is
+available to every workspace app and can be pushed with `sync-vault-to-app`.
+Switch the vault to manual mode only when apps need explicit per-key grants.
+
 ```text
 my-company-platform/
 ├── .env                           # shared: ANTHROPIC_API_KEY=... , A2A_SECRET=... , ...

package/docs/content/tracking.md

@@ -130,6 +130,18 @@ Only `name` and `track` are required. `identify` and `flush` are optional — im
 - **Best-effort delivery** — provider errors are caught and logged. A failing analytics integration never crashes the caller or blocks request handling.
 - **Global singleton** — the registry uses a `Symbol.for` key on `globalThis` so multiple ESM graph instances (dev-mode Vite + Nitro, symlinks) share one provider set.
 
+## Browser defaults {#browser-defaults}
+
+Template roots call `configureTracking()` once at startup. Browser events sent with `trackEvent()` automatically include app/template context plus the current LLM connection when the app can resolve it:
+
+- `llm_connection` — normalized provider label such as `builder`, `anthropic`, `openai`, `google`, or `none`
+- `llm_engine` — the engine id, for example `builder` or `ai-sdk:openai`
+- `llm_model` — the selected/default model when known
+- `llm_connection_source` — `app_secrets`, `settings`, or `env`
+- `llm_connection_configured` — whether an LLM connection is available
+
+The framework also tracks `builder connect clicked` from Connect Builder CTAs, and the server-side Builder connect routes track started/succeeded/failed lifecycle events.
+
 ## Using track() in templates {#templates}
 
 Call `track()` from action handlers to record user or agent activity:

package/docs/content/workspace-management.md

@@ -184,7 +184,7 @@ The [Dispatch](/docs/dispatch) app is the workspace's runtime control plane. It
 | Concern                         | Git / GitHub                  | Dispatch                                   |
 | ------------------------------- | ----------------------------- | ------------------------------------------ |
 | Who can change code             | CODEOWNERS, branch protection | —                                          |
-| Who can access secrets          | —                             | Vault grants + request workflow            |
+| Who can access secrets          | —                             | Vault policy, grants, request workflow     |
 | What instructions agents follow | —                             | Workspace resources (skills, instructions) |
 | Which agents are shared         | —                             | Workspace agent profiles                   |
 | Integration inventory           | —                             | Integrations catalog                       |
@@ -196,12 +196,47 @@ The [Dispatch](/docs/dispatch) app is the workspace's runtime control plane. It
 
 ### What Dispatch Manages
 
-- **Vault** — store credentials centrally, grant them to specific apps, sync on demand. Non-admins can request access; admins approve.
+- **Vault** — store credentials centrally and sync on demand. The default policy makes all vault keys available to all workspace apps; manual mode requires specific app grants. Non-admins can request access; admins approve.
 - **Integrations catalog** — see which credentials each app needs, what's configured, what's missing, what's granted from the vault.
 - **Workspace resources** — share skills, behavioral instructions, and reusable agent profiles across apps. Scope to all apps or grant per-app.
 - **Approvals** — require review before runtime changes (destinations, settings) take effect.
 - **Audit** — full history of secret access, grants, syncs, and changes.
 
+### Public App Routes
+
+Workspace apps are internal by default. For a public site with login-only admin
+pages, set a public audience and protect the admin prefix in that app's
+`package.json`:
+
+```json
+{
+  "agent-native": {
+    "workspaceApp": {
+      "audience": "public",
+      "protectedPaths": ["/admin"]
+    }
+  }
+}
+```
+
+For mostly internal apps with a few public pages, leave the audience internal and
+list page prefixes:
+
+```json
+{
+  "agent-native": {
+    "workspaceApp": {
+      "publicPaths": ["/", "/share"]
+    }
+  }
+}
+```
+
+These settings only affect read-only page navigation. Framework tools, agent
+chat, A2A, vault access, and arbitrary APIs stay authenticated unless the app
+explicitly declares public prefixes with
+`createAuthPlugin({ publicPaths: [...] })`.
+
 ## Setup Checklist
 
 For a new workspace, after running `agent-native create`:
@@ -216,8 +251,8 @@ For a new workspace, after running `agent-native create`:
 **Dispatch:**
 
 - [ ] Add shared secrets to the vault (API keys, OAuth credentials, etc.)
-- [ ] Grant secrets to the apps that need them
-- [ ] Sync granted secrets to push them to apps
+- [ ] Keep the default all-apps vault policy or switch to manual per-app grants
+- [ ] Sync vault secrets to push them to apps
 - [ ] Add workspace-wide skills and instructions via the Resources page
 - [ ] Configure the approval policy and approver emails
 - [ ] Set up SendGrid (`SENDGRID_API_KEY`, `SENDGRID_FROM_EMAIL`) for admin notifications

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.14.8",
+  "version": "0.15.1",
   "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