@agent-native/core 0.14.8 → 0.15.1

package/dist/templates/workspace-core/.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/dist/templates/workspace-core/.agents/skills/sharing/SKILL.md

@@ -0,0 +1,217 @@
+---
+name: sharing
+description: >-
+  Framework-level sharing and privacy for user-authored resources
+  (dashboards, documents, forms, decks, etc.). Use when making a resource
+  table ownable, wiring list/read/update access checks, or dropping the
+  standard share dialog into a template.
+---
+
+# Sharing — Private by Default, Explicit Share
+
+## Rule
+
+Any resource a user **creates** (dashboards, documents, forms, decks, compositions, booking links, issues, analyses) is **private to the creator** by default and visible to others only when they have been **explicitly shared** with or when the creator changes visibility to `org` or `public`.
+
+This is the framework-level primitive. Every ownable resource gets it for free — same API, same UI, same skill.
+
+## Concepts
+
+### Three visibility levels
+
+- **`private`** — owner + explicit share grants only. Default.
+- **`org`** — owner + explicit grants + anyone in the same org (read-only).
+- **`public`** — owner + explicit grants + **anyone with the link** (read-only). Public docs do NOT appear in other users' list/sidebar/search results — `accessFilter` omits them by default. They're reachable by id (`resolveAccess` admits them) so direct links and SSR routes like `/p/:id` keep working. If a list endpoint legitimately needs cross-user public discovery (a template gallery, etc.), pass `accessFilter(table, shares, ctx, minRole, { includePublic: true })`.
+
+Visibility is coarse. Explicit share grants are fine-grained (per user or per org).
+
+### Roles on a share grant
+
+- **`viewer`** — read only.
+- **`editor`** — read + write.
+- **`admin`** — read + write + manage shares. Does NOT replace the single `owner_email` on the resource.
+
+### Anonymous public URLs stay separate
+
+Form "publish" slugs, booking-link slugs, any feature that exposes a URL to unauthenticated users — these are a different axis and are NOT controlled by the sharing system. Keep them alongside it.
+
+## Make a resource ownable
+
+In your template's `server/db/schema.ts`:
+
+```ts
+import {
+  table,
+  text,
+  integer,
+  now,
+  ownableColumns,
+  createSharesTable,
+} from "@agent-native/core/db/schema";
+
+export const decks = table("decks", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  data: text("data").notNull(),
+  createdAt: text("created_at").notNull().default(now()),
+  updatedAt: text("updated_at").notNull().default(now()),
+  ...ownableColumns(), // adds owner_email, org_id, visibility
+});
+
+export const deckShares = createSharesTable("deck_shares");
+```
+
+Then register it **in `server/db/index.ts`** (not the schema file — keeps the schema file free of the `getDb` closure and avoids circular imports):
+
+```ts
+// server/db/index.ts
+import * as schema from "./schema.js";
+import { createGetDb } from "@agent-native/core/db";
+import { registerShareableResource } from "@agent-native/core/sharing";
+
+export const getDb = createGetDb(schema);
+export { schema };
+
+registerShareableResource({
+  type: "deck",
+  resourceTable: schema.decks,
+  sharesTable: schema.deckShares,
+  displayName: "Deck",
+  titleColumn: "title",
+  getResourcePath: (deck) => `/deck/${deck.id}`,
+  getDb,
+});
+```
+
+The `type` string is the stable id the UI and actions use. `getDb` is required — the framework-level share actions use it to reach your template's DB.
+
+### Restricting public visibility and cross-org user shares
+
+Some resources should NOT be reachable by an arbitrary authenticated user even with the link, and should NOT be shareable to an email outside the org. Two optional registration flags lock these axes down:
+
+```ts
+registerShareableResource({
+  type: "extension",
+  // ...
+  allowPublic: false, // hides "Public" in the share dialog and rejects it server-side
+  requireOrgMemberForUserShares: true, // user shares must target an org member or pending invitee
+});
+```
+
+- **`allowPublic: false`** — `set-resource-visibility('public')` throws `ForbiddenError`, `accessFilter` / `resolveAccess` treat any stored `'public'` row as private (defense in depth against bad data), and the share popover hides the "Public" option. `list-resource-shares` returns `policy.allowPublic: false` so the UI follows the server.
+- **`requireOrgMemberForUserShares: true`** — `share-resource` looks up `principalId` in `org_members` and `org_invitations` (pending) for the resource's `orgId` and rejects user shares to anyone else. The same flag also pins `principalType: "org"` shares to the resource's own org — sharing to a *different* org would let that org's members run code in the viewer's auth context (same threat model as a public extension). (The flag name is kept for backward compatibility; treat it as "lock both user and org shares to the resource's org".)
+
+Use both for resources that execute code or expose privileged data with the *viewer's* credentials. Extensions ship with both set: an extension's HTML calls actions / SQL / the secrets-injecting proxy as the viewer, so a public or cross-org-shared extension would let a stranger run arbitrary code with someone else's auth context. `scripts/guard-extension-no-public.mjs` (CI + `pnpm prep`) statically enforces that the extension registration keeps both flags set.
+
+Defaults match historical behaviour: `allowPublic: true`, `requireOrgMemberForUserShares: false`. Resources that don't set the flags work as before.
+
+## Filter list/read queries
+
+```ts
+import { accessFilter } from "@agent-native/core/sharing";
+
+const rows = await db
+  .select()
+  .from(schema.decks)
+  .where(accessFilter(schema.decks, schema.deckShares));
+```
+
+`accessFilter` admits rows the current user owns, has been shared on, or that the user can reach via `org` visibility. `public` rows are NOT admitted by default — see the visibility section above for why and how to opt in.
+
+## Guard write actions
+
+```ts
+import { assertAccess } from "@agent-native/core/sharing";
+
+export default defineAction({
+  schema: z.object({ id: z.string(), title: z.string() }),
+  run: async (args) => {
+    await assertAccess("deck", args.id, "editor");
+    // ...proceed
+  },
+});
+```
+
+For delete actions use `"admin"` (or fold in `"owner"` to require the real owner).
+
+## Create actions must set owner
+
+When inserting a new row, fill `ownerEmail` and `orgId` from the request context:
+
+```ts
+import {
+  getRequestUserEmail,
+  getRequestOrgId,
+} from "@agent-native/core/server/request-context";
+
+await db.insert(schema.decks).values({
+  id: nanoid(),
+  title,
+  data,
+  ownerEmail: getRequestUserEmail() ?? "local@localhost",
+  orgId: getRequestOrgId(),
+  // visibility defaults to 'private'
+  // ...
+});
+```
+
+## Drop in the share UI
+
+```tsx
+import { ShareButton } from "@agent-native/core/client";
+
+// In the resource's header/toolbar:
+<ShareButton
+  resourceType="deck"
+  resourceId={deck.id}
+  resourceTitle={deck.title}
+/>;
+```
+
+For list views, show `<VisibilityBadge visibility={row.visibility} />` next to each resource.
+
+## Actions available everywhere
+
+The framework auto-mounts these actions in every template — no per-template boilerplate:
+
+| Action                     | Args                                                                           | Purpose                                   |
+| -------------------------- | ------------------------------------------------------------------------------ | ----------------------------------------- |
+| `share-resource`           | `resourceType, resourceId, principalType, principalId, role, notify?, resourceUrl?` | Grant a user or org access. `notify` defaults to true for individual user shares; `resourceUrl` can provide the direct app link used in the notification email. |
+| `unshare-resource`         | `resourceType, resourceId, principalType, principalId`                         | Revoke access.                            |
+| `list-resource-shares`     | `resourceType, resourceId`                                                     | Current visibility + all share grants.    |
+| `set-resource-visibility`  | `resourceType, resourceId, visibility`                                         | Change to `private` / `org` / `public`.  |
+
+Both the agent and the UI call these via the same endpoints.
+
+## Migration pattern for existing tables
+
+When retrofitting an existing resource table:
+
+1. Add `owner_email`, `org_id`, `visibility` columns (defaults `'local@localhost'`, `NULL`, `'private'`).
+2. Backfill `owner_email` from any prior creator trail; otherwise leave the default.
+3. Add the companion `{type}_shares` table.
+4. Register via `registerShareableResource`.
+5. Update list/read actions to use `accessFilter`.
+6. Update update/delete actions to `assertAccess` with the correct role.
+7. Add `<ShareButton>` to the resource header.
+8. Add `getResourcePath` in the registration so agent-triggered shares can email a direct link even when no UI supplied `resourceUrl`.
+
+## Templates that opt out
+
+Sharing doesn't apply to:
+
+- **Personal-data apps** (mail, macros) — user-scoped by design.
+- **External source-of-truth apps** (issues → Jira, recruiting → Greenhouse) — ACL lives in the upstream system.
+- **Demo/boilerplate** (starter) — no resources.
+
+For these, add a short note to the template's `AGENTS.md` explaining why.
+
+## Analytics (follow-up)
+
+Dashboards and analyses in the `analytics` template currently live in the settings KV store (`u:<email>:dashboard-*` keys), not SQL. Sharing requires either migrating them to SQL tables (then applying this skill) or extending the settings store with a parallel share overlay. This is a tracked follow-up — see the analytics template's `AGENTS.md`.
+
+## Debugging
+
+- `ForbiddenError` from an action means the current user isn't owner / hasn't been shared / can't meet the role bar.
+- If the agent can't see a resource it just created, check that the insert actually set `owner_email` from the request context.
+- If a share doesn't take effect in the UI, confirm the template's `list-*` action uses `accessFilter` — the share rows are there but nothing is reading them yet.

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

@@ -0,0 +1,132 @@
+---
+name: storing-data
+description: >-
+  How to store application data in agent-native apps. All data lives in SQL.
+  Use when adding data models, deciding where to store data, or reading/writing
+  application data.
+---
+
+# Storing Data — SQL is the Source of Truth
+
+## Rule
+
+All application data lives in **SQL** (SQLite locally, cloud database in production). The agent and UI share the same database. There is no filesystem dependency for data.
+
+## How It Works
+
+Agent-native apps use SQLite via Drizzle ORM + `@libsql/client`. This works locally out of the box and upgrades seamlessly to cloud databases (Turso, Neon, Supabase, D1) by setting `DATABASE_URL`. **Local and production behave identically.**
+
+### Core SQL Stores (auto-created, available in all templates)
+
+| Store               | Purpose                                              | Access                                     |
+| ------------------- | ---------------------------------------------------- | ------------------------------------------ |
+| `application_state` | Ephemeral UI state (compose windows, navigation)     | `readAppState()` / `writeAppState()`       |
+| `settings`          | Persistent KV config (preferences, app settings)     | `getSetting()` / `setSetting()`            |
+| `oauth_tokens`      | OAuth credentials                                    | `@agent-native/core/oauth-tokens`          |
+| `sessions`          | Auth sessions                                        | `@agent-native/core/server`               |
+
+### Domain Data (per-template)
+
+Define schema with Drizzle ORM in `server/db/schema.ts`. Get a database instance with `const db = getDb()` from `server/db/index.ts`. All queries are async.
+
+| Template     | Tables                                        |
+| ------------ | --------------------------------------------- |
+| **Mail**     | emails, labels (+ Gmail API when connected)   |
+| **Calendar** | events, bookings                              |
+| **Forms**    | forms, responses                              |
+| **Content**  | documents                                     |
+| **Slides**   | decks (JSON stored in SQL)                    |
+| **Videos**   | compositions in registry + localStorage       |
+
+### Agent Access
+
+The agent uses actions to read/write the database:
+
+- `pnpm action db-schema` — Show all tables, columns, types
+- `pnpm action db-query --sql "SELECT * FROM forms"` — Run SELECT queries
+- `pnpm action db-exec --sql "INSERT INTO ..."` — Run INSERT / UPDATE / DELETE / REPLACE. Use for short columns, multi-column writes, computed updates. For several related writes, prefer `--statements '[{"sql":"...","args":[...]}]'` so they run sequentially in one transaction. Schema changes are blocked; use reviewed additive migrations/startup code instead.
+- `pnpm action db-patch --table <t> --column <c> --where "<clause>" --find "<old>" --replace "<new>"` — **Surgical search/replace on a large text column.** Sends the diff instead of re-transmitting the whole value, so it's dramatically more token-efficient than `db-exec UPDATE` when editing multi-kilobyte documents, slide HTML, dashboard/form JSON, etc. Targets exactly one row per call — narrow `--where` by primary key. Supports `--edits '[{find,replace},...]'` for batch edits and `--all` to replace every occurrence.
+- App-specific actions for domain operations (auto-exposed as HTTP endpoints) — **always prefer these over raw SQL when one exists.** They encode business rules, and for editor-backed tables (documents, slides) they also push live Yjs updates to open collaborative editors. `db-patch` is the generic fallback for tables without a dedicated edit action.
+
+**How to choose between `db-exec UPDATE` and `db-patch`:**
+
+| Scenario                                                       | Use          |
+| -------------------------------------------------------------- | ------------ |
+| `SET status = 'published'` on one row                          | `db-exec`    |
+| `SET calories = calories + 50`                                 | `db-exec`    |
+| Updating several columns at once                               | `db-exec`    |
+| Inserting/updating several rows as one logical operation        | `db-exec --statements` |
+| Fixing a typo in a 50KB markdown document's `content` column   | `db-patch`   |
+| Changing a single key in a dashboard's JSON blob               | `db-patch`   |
+| Tweaking one paragraph of slide HTML stored in `decks.data`    | `db-patch`   |
+| Any edit where you'd otherwise re-send thousands of characters | `db-patch`   |
+
+All of these honor the per-user / per-org data scoping — you can't read or write rows outside the current user's data, regardless of which tool you choose.
+
+### Frontend Access
+
+The frontend calls actions via their auto-mounted HTTP endpoints using React Query hooks:
+
+```ts
+import { useActionQuery, useActionMutation } from "@agent-native/core/client";
+
+// Read data (calls GET /_agent-native/actions/list-meals)
+const { data } = useActionQuery<Meal[]>("list-meals", { date: "2025-01-01" });
+
+// Write data (calls POST /_agent-native/actions/log-meal)
+const { mutate } = useActionMutation<Meal>("log-meal");
+```
+
+Actions are the **preferred way** for the frontend to access data. You rarely need custom `/api/` routes — only for file uploads, streaming, webhooks, or OAuth callbacks.
+
+### Cloud Deployment
+
+Local SQLite works out of the box. To deploy to production with a cloud database:
+
+1. Set `DATABASE_URL` (e.g. `libsql://your-db.turso.io`)
+2. Set `DATABASE_AUTH_TOKEN` for auth
+3. No code changes needed — `@libsql/client` handles both local and remote
+
+### Real-time Sync
+
+Polling streams database changes to the UI. When the agent writes to the database via scripts, the UI updates automatically via `useDbSync()` which invalidates React Query caches.
+
+## Do
+
+- Use Drizzle ORM for structured domain data (forms, bookings, documents)
+- Use the `settings` store for app configuration and user preferences
+- Use `application-state` for ephemeral UI state that the agent and UI share
+- Use `oauth-tokens` for OAuth credentials
+- Use core DB scripts (`db-schema`, `db-query`, `db-exec`, `db-patch`) for ad-hoc database operations
+- Use `db-exec --statements` instead of several separate `db-exec` calls for related writes; it is faster and rolls back the whole batch if one statement fails
+- Reach for `db-patch` instead of `db-exec UPDATE` whenever you're making a small change to a large text/JSON column — it's much cheaper on tokens
+
+## Don't
+
+- Don't store structured app data as JSON files
+- Don't store app state in localStorage, sessionStorage, or cookies (except for UI-only preferences like sidebar width)
+- Don't keep state only in memory (server variables, global stores)
+- Don't use Redis or any external state store for app data
+- Don't interpolate user input directly into SQL queries — use Drizzle ORM's query builder
+
+## Security
+
+- **SQL injection** — Use Drizzle ORM's query builder, never raw string interpolation for SQL queries
+- **Validate before writing** — Check data shape before writing, especially for user-submitted data
+
+## Application State and Context Awareness
+
+When storing app-state, include **navigation state** — the agent needs to know what the user is looking at. The `application_state` table holds ephemeral UI state that both the agent and UI share. Key patterns:
+
+- **`navigation` key** — the UI writes current view and selection on every route change. The agent reads this before acting.
+- **`navigate` key** — the agent writes one-shot commands to navigate the UI. The UI processes and deletes them.
+- **Domain-specific keys** (e.g., `compose-{id}`) — bidirectional state for features like email drafts.
+
+When adding a new data model or feature, also consider what navigation and selection state needs to be exposed via application-state. See the **context-awareness** skill for the full pattern.
+
+## Related Skills
+
+- **context-awareness** — How to expose navigation and selection state via application-state
+- **real-time-sync** — Set up polling so the UI updates when the database changes
+- **actions** — Create actions with `defineAction` to query the database (auto-exposed as HTTP endpoints)
+- **self-modifying-code** — The agent can also modify the app's source code

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

@@ -0,0 +1,150 @@
+---
+name: tracking
+description: >-
+  Server-side analytics tracking with pluggable providers. Use when adding
+  analytics events, registering custom tracking providers, or configuring
+  built-in providers (PostHog, Mixpanel, Amplitude, Webhook).
+---
+
+# Tracking
+
+## Rule
+
+The tracking system provides a single `track()` call that fans out to all registered providers. Built-in providers auto-register from env vars -- set the var and tracking starts. Custom providers can be registered for any analytics backend. Tracking is server-side only, best-effort, and never blocks request handling.
+
+## How It Works
+
+1. At server startup, `registerBuiltinProviders()` checks env vars and registers any configured providers.
+2. Application code calls `track(eventName, properties, meta)` from actions, plugins, or server routes.
+3. The registry fans out the event to every registered provider. Errors are caught and logged -- a failing provider never crashes the caller.
+4. Built-in providers batch HTTP calls (flush every 10 seconds or 50 events, whichever comes first).
+
+## API
+
+### `track(name, properties?, meta?)`
+
+Fire an analytics event.
+
+```ts
+import { track } from "@agent-native/core/tracking";
+
+track("meal.logged", { mealName: "Salad", calories: 350 }, { userId: "owner@example.com" });
+```
+
+### `identify(userId, traits?)`
+
+Identify a user with traits. Forwarded to providers that support it.
+
+```ts
+import { identify } from "@agent-native/core/tracking";
+
+identify("owner@example.com", { plan: "pro", company: "Example Co" });
+```
+
+### `registerTrackingProvider(provider)`
+
+Register a custom provider.
+
+```ts
+import { registerTrackingProvider } from "@agent-native/core/tracking";
+
+registerTrackingProvider({
+  name: "my-analytics",
+  track(event) {
+    // Send event to your backend
+  },
+  identify(userId, traits) {
+    // Optional
+  },
+  flush() {
+    // Optional -- called on graceful shutdown
+  },
+});
+```
+
+### `flushTracking()`
+
+Flush all providers (call before process exit).
+
+## Built-in Providers
+
+Set the env var and the provider auto-registers at startup. No SDK dependencies -- all providers use raw HTTP.
+
+| Provider   | Env vars                                                  |
+| ---------- | --------------------------------------------------------- |
+| PostHog    | `POSTHOG_API_KEY` (required), `POSTHOG_HOST` (optional, defaults to `https://us.i.posthog.com`) |
+| Mixpanel   | `MIXPANEL_TOKEN`                                          |
+| Amplitude  | `AMPLITUDE_API_KEY`                                       |
+| Agent Native Analytics | `AGENT_NATIVE_ANALYTICS_PUBLIC_KEY` (server), `AGENT_NATIVE_ANALYTICS_ENDPOINT` (optional, defaults to `https://analytics.agent-native.com/track`) |
+| Webhook    | `TRACKING_WEBHOOK_URL` (required), `TRACKING_WEBHOOK_AUTH` (optional, sent as `Authorization` header) |
+
+Multiple providers can be active simultaneously. All receive every event.
+
+Browser-side `trackEvent()` also forwards to Agent Native Analytics when `VITE_AGENT_NATIVE_ANALYTICS_PUBLIC_KEY` is present. Use `VITE_AGENT_NATIVE_ANALYTICS_ENDPOINT` to override the default browser endpoint. The built-in Agent Native Analytics sender is quiet on localhost/local dev by default; set `AGENT_NATIVE_ANALYTICS_ALLOW_LOCALHOST=true` only for an intentional local ingestion test.
+
+## Default Baseline Events
+
+Template roots call `configureTracking()` once during app startup. That installs default browser pageview tracking for hosted apps:
+
+- Event: `pageview`
+- Fires on initial load, `history.pushState`, `history.replaceState`, and `popstate`
+- De-dupes repeated events for the same URL
+- Includes `url`, `path`, `hostname`, `referrer`, `title`, `navigation_type`, `app`, and inferred `template`
+- Does not send first-party events from localhost/local dev
+
+### Visitor identity (`anonymousId` + `sessionId`)
+
+Every browser-side `trackEvent()` POST to the Agent Native Analytics `/track` endpoint includes:
+
+- `anonymousId` — persistent per-browser visitor ID stored in `localStorage` under `agent-native.anonymous_id`. Generated once and reused across sessions. Use this for unique-visitor and returning-visitor metrics.
+- `sessionId` — rotating per-visit ID stored in `localStorage` under `agent-native.session_id`, with a 30-minute idle timeout (matches GA4 / Mixpanel defaults). Use this for sessions-per-visitor, pages-per-session, and session-duration metrics.
+- `userId` — only set when the calling code passes `properties.userId`. Anonymous traffic leaves this NULL by design; `anonymousId` is the fallback.
+
+These fields land in the `analytics_events.anonymous_id`, `analytics_events.session_id`, and `analytics_events.user_id` columns in the analytics template. Storage access is wrapped in try/catch — private-browsing / blocked-storage clients silently degrade to NULL rather than crashing the page.
+
+Other framework-level baseline events:
+
+- `session status` from `useSession()`, with `signed_in`
+- `signup` from Better Auth user creation, with `auth_provider` and `auth_user_id`
+- `builder connect started`, `builder connect succeeded`, `builder connect failed`, `builder disconnect succeeded`, and `builder disconnect failed` from the Builder connection routes
+
+For new lifecycle events, call `track()` server-side when the server is the source of truth, and `trackEvent()` client-side only for browser interactions.
+
+## Provider Interface
+
+```ts
+interface TrackingProvider {
+  name: string;
+  track(event: TrackingEvent): void | Promise<void>;
+  identify?(userId: string, traits?: Record<string, unknown>): void | Promise<void>;
+  flush?(): void | Promise<void>;
+}
+
+interface TrackingEvent {
+  name: string;
+  properties?: Record<string, unknown>;
+  timestamp?: string;
+  userId?: string;
+}
+```
+
+## Design Decisions
+
+- **globalThis singleton** -- the registry uses a `Symbol.for` key on globalThis so multiple ESM graph instances (dev-mode Vite + Nitro, symlinks) share one provider set.
+- **Best-effort fan-out** -- provider errors are caught and logged, never propagated. A broken analytics integration must not break app functionality.
+- **Batched HTTP** -- built-in providers enqueue events and flush every 10 seconds or 50 events, minimizing outbound requests.
+- **NOT bridged to the event bus** -- tracking and the event bus are separate concerns. The event bus is for triggering automations; tracking is for analytics. Do not subscribe to `track()` calls from the event bus or vice versa.
+
+## Key Files
+
+| File                                           | Purpose                                     |
+| ---------------------------------------------- | ------------------------------------------- |
+| `packages/core/src/tracking/registry.ts`       | `track()`, `identify()`, `registerTrackingProvider()`, `flushTracking()` |
+| `packages/core/src/tracking/providers.ts`      | Built-in providers (PostHog, Mixpanel, Amplitude, Agent Native Analytics, Webhook) and `registerBuiltinProviders()` |
+| `packages/core/src/tracking/types.ts`          | `TrackingEvent` and `TrackingProvider` interfaces |
+
+## Related Skills
+
+- `secrets` -- API keys for tracking providers can be registered as secrets
+- `server-plugins` -- `registerBuiltinProviders()` is called by the core-routes plugin at startup
+- `actions` -- call `track()` from action handlers to record user/agent activity