@agent-native/core 0.152.1 → 0.153.0

package/corpus/templates/analytics/server/lib/first-party-analytics-backend.ts

@@ -24,7 +24,7 @@ export interface FirstPartyAnalyticsBackendConfig {
   backfillCompleted?: boolean;
 }
 
-interface FirstPartyAnalyticsBackfillCursor {
+export interface FirstPartyAnalyticsBackfillCursor {
   receivedAt: string;
   id: string;
 }
@@ -90,6 +90,9 @@ export interface FirstPartyAnalyticsBackfillOptions {
   lookbackDays?: number;
   skipEventNames?: string[];
   now?: () => string;
+  rangeStart?: FirstPartyAnalyticsBackfillCursor | null;
+  rangeEnd?: FirstPartyAnalyticsBackfillCursor | null;
+  rangeEndInclusive?: boolean;
 }
 
 export interface FirstPartyAnalyticsInsertOptions {
@@ -1204,12 +1207,23 @@ function backfillBranchSql(
   cursor: FirstPartyAnalyticsBackfillCursor,
   lookbackStart: string,
   skipEventNames: string[],
+  rangeStart: FirstPartyAnalyticsBackfillCursor | null,
+  rangeEnd: FirstPartyAnalyticsBackfillCursor | null,
+  rangeEndInclusive: boolean,
+  order: "ASC" | "DESC" = "ASC",
 ): {
   sql: string;
   args: unknown[];
 } {
-  const cursorSql = cursor.receivedAt ? "(received_at, id) > (?, ?)" : "";
-  const cursorArgs = cursor.receivedAt ? [cursor.receivedAt, cursor.id] : [];
+  const lowerCursor = cursor.receivedAt ? cursor : rangeStart;
+  const cursorSql = lowerCursor ? "(received_at, id) > (?, ?)" : "";
+  const cursorArgs = lowerCursor
+    ? [lowerCursor.receivedAt, lowerCursor.id]
+    : [];
+  const rangeEndSql = rangeEnd
+    ? `(received_at, id) ${rangeEndInclusive ? "<=" : "<"} (?, ?)`
+    : "";
+  const rangeEndArgs = rangeEnd ? [rangeEnd.receivedAt, rangeEnd.id] : [];
   const skipSql =
     skipEventNames.length === DEFAULT_BACKFILL_SKIP_EVENTS.length &&
     skipEventNames[0] === DEFAULT_BACKFILL_SKIP_EVENTS[0]
@@ -1217,24 +1231,78 @@ function backfillBranchSql(
       : skipEventNames.length
         ? `(event_name IS NULL OR event_name NOT IN (${skipEventNames.map(() => "?").join(", ")}))`
         : "";
-  const filters = ["received_at >= ?", skipSql].filter(Boolean);
+  const filters = ["received_at >= ?", skipSql, rangeEndSql].filter(Boolean);
   return {
     sql: `SELECT id, received_at
       FROM analytics_events
       WHERE ${predicate}
         AND ${filters.join("\n        AND ")}${cursorSql ? `\n        AND ${cursorSql}` : ""}
-      ORDER BY received_at ASC, id ASC LIMIT ?`,
+      ORDER BY received_at ${order}, id ${order} LIMIT ?`,
     args: [
       ...predicateArgs,
       lookbackStart,
       ...(skipSql === "event_name IS DISTINCT FROM 'http.response'"
         ? []
         : skipEventNames),
+      ...rangeEndArgs,
       ...cursorArgs,
     ],
   };
 }
 
+export async function getFirstPartyAnalyticsBackfillHighWaterMark(
+  scope: FirstPartyAnalyticsScope,
+  options?: Pick<
+    FirstPartyAnalyticsBackfillOptions,
+    "lookbackDays" | "skipEventNames" | "now"
+  >,
+): Promise<FirstPartyAnalyticsBackfillCursor | null> {
+  const db = getDbExec();
+  const lookbackDays = configuredLookbackDays(options?.lookbackDays);
+  const lookbackStart = backfillLookbackStart(
+    options?.now?.() ?? new Date().toISOString(),
+    lookbackDays,
+  );
+  const skipEventNames = configuredSkipEventNames(options?.skipEventNames);
+  const branches = scope.orgId
+    ? [
+        { predicate: "org_id = ?", args: [scope.orgId] },
+        {
+          predicate: "org_id IS NULL AND owner_email = ?",
+          args: [scope.userEmail],
+        },
+      ]
+    : [
+        {
+          predicate: "org_id IS NULL AND owner_email = ?",
+          args: [scope.userEmail],
+        },
+      ];
+  const rows: Record<string, unknown>[] = [];
+  for (const branch of branches) {
+    const scoped = backfillBranchSql(
+      branch.predicate,
+      branch.args,
+      { receivedAt: "", id: "" },
+      lookbackStart,
+      skipEventNames,
+      null,
+      null,
+      false,
+      "DESC",
+    );
+    const result = await db.execute({
+      sql: scoped.sql,
+      args: [...scoped.args, 1],
+      timeoutMs: 20_000,
+      maxAttempts: 1,
+    });
+    rows.push(...(result.rows as Record<string, unknown>[]));
+  }
+  rows.sort((left, right) => compareBackfillRows(right, left));
+  return rows.length ? backfillRowCursor(rows[0]!) : null;
+}
+
 function backfillRowsByIdsSql(ids: string[]): {
   sql: string;
   args: string[];
@@ -1296,6 +1364,9 @@ export async function backfillFirstPartyAnalyticsBatch(
     lookbackDays,
   );
   const skipEventNames = configuredSkipEventNames(options?.skipEventNames);
+  const rangeStart = options?.rangeStart ?? null;
+  const rangeEnd = options?.rangeEnd ?? null;
+  const rangeEndInclusive = options?.rangeEndInclusive === true;
   const branches = scope.orgId
     ? [
         { predicate: "org_id = ?", args: [scope.orgId] },
@@ -1318,6 +1389,9 @@ export async function backfillFirstPartyAnalyticsBatch(
       parsedCursor,
       lookbackStart,
       skipEventNames,
+      rangeStart,
+      rangeEnd,
+      rangeEndInclusive,
     );
     const result = await db.execute({
       sql: scoped.sql,

package/corpus/templates/analytics/server/plugins/db.ts

@@ -1576,6 +1576,90 @@ export const runAnalyticsMigrations = runMigrations(
       ON analytics_event_volume_usage (updated_at)`,
       },
     },
+    {
+      version: 142,
+      name: "analytics-bigquery-backfill-shards",
+      sql: {
+        postgres: `CREATE TABLE IF NOT EXISTS analytics_bigquery_backfill_shards (
+      shard_id TEXT PRIMARY KEY,
+      job_id TEXT,
+      org_id TEXT NOT NULL,
+      owner_email TEXT NOT NULL,
+      table_ref TEXT NOT NULL,
+      start_at TEXT NOT NULL,
+      start_id TEXT NOT NULL DEFAULT '',
+      end_at TEXT NOT NULL,
+      end_id TEXT NOT NULL DEFAULT '',
+      end_inclusive BOOLEAN NOT NULL DEFAULT FALSE,
+      batch_size INTEGER NOT NULL DEFAULT 250,
+      backfill_cursor TEXT,
+      backfill_cursor_at TEXT,
+      backfill_cursor_id TEXT,
+      status TEXT NOT NULL DEFAULT 'pending' CHECK (status IN ('pending', 'running', 'completed')),
+      copied_count INTEGER NOT NULL DEFAULT 0,
+      lease_token TEXT,
+      lease_expires_at TEXT,
+      next_run_at TEXT NOT NULL DEFAULT (now()::text),
+      last_error TEXT,
+      completed_at TEXT,
+      updated_at TEXT NOT NULL DEFAULT (now()::text)
+    );
+    CREATE INDEX IF NOT EXISTS analytics_bigquery_backfill_shards_due_idx
+      ON analytics_bigquery_backfill_shards (status, next_run_at, lease_expires_at, updated_at);
+    CREATE INDEX IF NOT EXISTS analytics_bigquery_backfill_shards_scope_time_idx
+      ON analytics_bigquery_backfill_shards (org_id, owner_email, start_at, end_at)`,
+        sqlite: `CREATE TABLE IF NOT EXISTS analytics_bigquery_backfill_shards (
+      shard_id TEXT PRIMARY KEY,
+      job_id TEXT,
+      org_id TEXT NOT NULL,
+      owner_email TEXT NOT NULL,
+      table_ref TEXT NOT NULL,
+      start_at TEXT NOT NULL,
+      start_id TEXT NOT NULL DEFAULT '',
+      end_at TEXT NOT NULL,
+      end_id TEXT NOT NULL DEFAULT '',
+      end_inclusive INTEGER NOT NULL DEFAULT 0,
+      batch_size INTEGER NOT NULL DEFAULT 250,
+      backfill_cursor TEXT,
+      backfill_cursor_at TEXT,
+      backfill_cursor_id TEXT,
+      status TEXT NOT NULL DEFAULT 'pending' CHECK (status IN ('pending', 'running', 'completed')),
+      copied_count INTEGER NOT NULL DEFAULT 0,
+      lease_token TEXT,
+      lease_expires_at TEXT,
+      next_run_at TEXT NOT NULL DEFAULT (datetime('now')),
+      last_error TEXT,
+      completed_at TEXT,
+      updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+    CREATE INDEX IF NOT EXISTS analytics_bigquery_backfill_shards_due_idx
+      ON analytics_bigquery_backfill_shards (status, next_run_at, lease_expires_at, updated_at);
+    CREATE INDEX IF NOT EXISTS analytics_bigquery_backfill_shards_scope_time_idx
+      ON analytics_bigquery_backfill_shards (org_id, owner_email, start_at, end_at)`,
+      },
+    },
+    {
+      version: 143,
+      name: "analytics-bigquery-backfill-shard-columns",
+      sql: {
+        postgres: `ALTER TABLE analytics_bigquery_backfill_shards ADD COLUMN IF NOT EXISTS job_id TEXT;
+        ALTER TABLE analytics_bigquery_backfill_shards ADD COLUMN IF NOT EXISTS start_id TEXT NOT NULL DEFAULT '';
+        ALTER TABLE analytics_bigquery_backfill_shards ADD COLUMN IF NOT EXISTS end_id TEXT NOT NULL DEFAULT '';
+        ALTER TABLE analytics_bigquery_backfill_shards ADD COLUMN IF NOT EXISTS end_inclusive BOOLEAN NOT NULL DEFAULT FALSE;
+        ALTER TABLE analytics_bigquery_backfill_shards ADD COLUMN IF NOT EXISTS backfill_cursor_at TEXT;
+        ALTER TABLE analytics_bigquery_backfill_shards ADD COLUMN IF NOT EXISTS backfill_cursor_id TEXT;
+        CREATE INDEX IF NOT EXISTS analytics_bigquery_backfill_shards_job_due_idx
+          ON analytics_bigquery_backfill_shards (job_id, status, next_run_at, lease_expires_at, start_at);`,
+        sqlite: `ALTER TABLE analytics_bigquery_backfill_shards ADD COLUMN IF NOT EXISTS job_id TEXT;
+        ALTER TABLE analytics_bigquery_backfill_shards ADD COLUMN IF NOT EXISTS start_id TEXT NOT NULL DEFAULT '';
+        ALTER TABLE analytics_bigquery_backfill_shards ADD COLUMN IF NOT EXISTS end_id TEXT NOT NULL DEFAULT '';
+        ALTER TABLE analytics_bigquery_backfill_shards ADD COLUMN IF NOT EXISTS end_inclusive INTEGER NOT NULL DEFAULT 0;
+        ALTER TABLE analytics_bigquery_backfill_shards ADD COLUMN IF NOT EXISTS backfill_cursor_at TEXT;
+        ALTER TABLE analytics_bigquery_backfill_shards ADD COLUMN IF NOT EXISTS backfill_cursor_id TEXT;
+        CREATE INDEX IF NOT EXISTS analytics_bigquery_backfill_shards_job_due_idx
+          ON analytics_bigquery_backfill_shards (job_id, status, next_run_at, lease_expires_at, start_at);`,
+      },
+    },
   ],
   { table: "analytics_migrations" },
 );

package/corpus/templates/assets/.agents/skills/adding-a-feature/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: adding-a-feature
+description: >-
+  The four-area checklist every new feature must complete. Use when adding any
+  feature, integration, or capability to ensure the agent and UI stay in parity.
+scope: dev
+metadata:
+  internal: true
+---
+
+# 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.
+
+Scope check first: this is the checklist for a feature that adds app data or a new capability. A restyle, a copy change, or a screen with no new data model and no new agent-visible operation only needs the areas it actually touches — do not manufacture actions, state keys, or a skill for it.
+
+## 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 scripts is invisible to the user. A feature without app-state sync means the agent is blind to what the user is doing.
+
+## The Checklist
+
+When you add a new feature, work through these four areas in order:
+
+### 1. UI Component
+
+Build the user-facing interface — a page, component, dialog, or route. Use `useActionQuery` and `useActionMutation` from `@agent-native/core/client` to call actions for data fetching and mutations. Do not create a custom REST endpoint just so React can call action-backed data; the action endpoint already exists.
+
+**Auto-refresh on agent writes is non-negotiable** — when the agent mutates data, the UI must reflect the change without a manual refresh. There are two paths, and you must pick the right one:
+
+- **`useActionQuery` / `useActionMutation`** — covered automatically. The framework's `useDbSync` invalidates `["action"]` on every change event, so every `useActionQuery` hook refetches on agent activity. No extra wiring required. **Prefer this path.**
+- **Raw `useQuery` with custom keys** — 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 (`"dashboards"`, `"analyses"`, `"settings"`, etc.) is bonus when emitted. Without this wiring, agent writes will be invisible until manual refresh — that breaks the framework's #1 promise.
+
+  ```tsx
+  import { useChangeVersions } from "@agent-native/core/client/hooks";
+  import { useQuery } from "@tanstack/react-query";
+
+  const v = useChangeVersions(["dashboards", "action"]);
+  useQuery({
+    queryKey: ["dashboard", id, v],
+    queryFn: () => fetchDashboard(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 UI calls it through `useActionQuery` / `useActionMutation` while the framework owns the HTTP transport. Set `http: { method: "GET" }` for read actions, leave default for writes, or set `http: false` for agent-only actions like `navigate` and `view-screen`.
+
+Before adding a new route or endpoint, inspect the existing actions. Reuse an
+action if it already covers the business operation, extend it if the shared
+contract is incomplete, or create a new `defineAction` if the agent and UI both
+need the capability. Do not add pass-through `/api/*` routes that re-export
+actions. If client code needs a new framework/app route, expose a named helper
+or hook first and use that helper from components and docs.
+
+For provider-backed analysis/query/reporting integrations, do not turn every
+provider endpoint or filter into a rigid action. Prefer the shared
+`provider-api-catalog` / `provider-api-docs` / `provider-api-request` pattern
+from `@agent-native/core/provider-api`, then add narrow convenience actions only
+for workflows that truly deserve a first-class shortcut. Treat this as a
+capability requirement, not a nice-to-have: convenience actions must not become
+the ceiling of what the agent can ask the provider to do. Pair broad provider
+access with staging or sandboxed code execution when responses may be too large
+for chat context. If provider credentials live on resource/share rows, add the
+scoped resolver first so broad access preserves the same ownership boundary as
+the app UI.
+
+If the feature needs credentials, design the credential path in the same change.
+Never hardcode API keys, tokens, webhook URLs, signing secrets, private
+Builder/internal data, or customer data in the action, UI, seed data, fixtures,
+docs, prompts, or generated extension/app content. Register required secrets,
+use OAuth helpers, or read scoped values from the vault/credential store.
+
+If the feature involves attachments, images, recordings, screenshots, exports,
+or other file-like payloads, design the upload path in the same change:
+provider upload first, then URL/id/blob handle in SQL. Do not add base64/binary
+columns or stuff files into `application_state`.
+
+If the feature adds a server-side dependency carrying a native binary or heavy
+runtime — headless browser, ffmpeg, image/video processing, ML runtime — read
+the `performance` skill §9 before adding it. A deployed app has one `/*` page
+function that every visitor's cache miss wakes, and it ships whatever the server
+bundle depends on. Run that work from a background function or a job so the page
+function never carries the weight.
+
+**If the action produces or lists a navigable resource**, add a `link` builder that returns `{ url: buildDeepLink({ app, view, params }), label }`. External coding agents and MCP hosts (Claude / ChatGPT / Claude Code / Cowork / Codex, over MCP/A2A) then surface an "Open in … →" deep link that drops the user back into the running UI focused on the record — for free. If a compatible MCP host should render an inline review/edit surface, also add `mcpApp` with `embedApp()` so the action embeds the real React app route instead of a one-off HTML UI. The `link` builder and `mcpApp` metadata must be pure and synchronous (no I/O). Any external-agent read/ingest action must be `http: { method: "GET" }` + `readOnly: true` + `publicAgent: { expose: true, readOnly: true, requiresAuth: true }`. See the `external-agents` skill.
+
+### 3. Skills / Instructions
+
+Update `AGENTS.md` 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`.
+
+Reusable actions are part of the app contract, not just implementation detail. When an action is useful outside one screen, update agent instructions in the same change so app agents know when to call it, which arguments matter, and what output to preserve. If the capability is workflow-heavy, cross-app, provider-backed, or has a non-obvious sequence of actions, add or update a skill instead of burying the behavior in one long `AGENTS.md` paragraph.
+
+Instruction examples may name secret keys like `SLACK_WEBHOOK`, but must use
+placeholders such as `${keys.SLACK_WEBHOOK}` or `<SLACK_WEBHOOK>`. Do not paste
+real keys, internal data, or customer data into instructions as examples.
+
+If the feature adds or changes visible UI copy, prompts, toasts, labels, empty
+states, or formatting, update the English source copy. Read the optional
+`internationalization` skill and update additional catalogs only when
+`translations.locales` in `agent-native.config.ts` includes them.
+
+For app-backed skills, declare skill visibility in the app-skill manifest:
+
+- `internal` — only the app's own agents should use it.
+- `exported` — marketplace installs receive it, but the app does not need it loaded internally.
+- `both` — shared between the app's internal agents and exported marketplace bundles.
+
+### 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.
+
+## Examples
+
+### Adding "compose email" to a mail app
+
+| Area            | What to build                                                                            |
+| --------------- | ---------------------------------------------------------------------------------------- |
+| UI              | Compose panel with tabs, to/cc/bcc fields, body editor. Use `useActionQuery`/`useActionMutation` for data. |
+| Action          | `manage-draft` action (create/update/delete drafts), `send-email` action                 |
+| Skills/AGENTS   | Document compose state shape, draft lifecycle, action args in AGENTS.md                  |
+| App-state sync  | `compose-{id}` keys for each draft tab, `navigation` includes compose state              |
+
+### Adding "create form" to a forms app
+
+| Area            | What to build                                                                            |
+| --------------- | ---------------------------------------------------------------------------------------- |
+| UI              | Form builder page with drag-and-drop fields, preview, settings. Use `useActionQuery` for lists. |
+| Action          | `create-form` action, `update-form` action, `list-forms` action (GET)                    |
+| Skills/AGENTS   | Document form schema shape, field types, validation rules in AGENTS.md                   |
+| App-state sync  | `navigation` includes `{ view: "form-builder", formId: "..." }`, `view-screen` fetches form data |
+
+### Adding "chart type" to an analytics app
+
+| Area            | What to build                                                                            |
+| --------------- | ---------------------------------------------------------------------------------------- |
+| UI              | New chart component, chart type selector in dashboard                                    |
+| Action          | `create-chart` or `update-dashboard` action that sets chart type and config              |
+| Skills/AGENTS   | Document supported chart types, config options, data requirements                        |
+| App-state sync  | `navigation` includes selected chart/dashboard, `view-screen` returns chart config       |
+
+## Adding a new route
+
+Templates are single-page apps with client-side routing. The app shell (AgentSidebar + top-level nav) MUST persist across navigation — it is mounted once, either in `root.tsx` around `<Outlet />` or via a pathless `_app.tsx` layout route that all authed routes nest under.
+
+**Never wrap each new route in its own `<AppLayout>` / `<Layout>`.** That causes React to unmount the entire app shell on every navigation, reloading the agent sidebar and destroying in-progress work.
+
+- If the template has `<AppLayout>` in `root.tsx` — just render page content in your new route file, nothing else.
+- If the template has `app/routes/_app.tsx` (pathless layout) — name your new route `_app.<segment>.tsx` to inherit the shell, or bare `<segment>.tsx` for public routes that should NOT have the shell.
+- If a page needs per-route data (e.g. highlighting the active item in the sidebar), read it in the layout from `useParams()` / `useLocation()`. Don't pass it as a prop through every route file.
+
+See the "Client-Side Routing" section in the root `CLAUDE.md` for full details.
+
+## Anti-Patterns
+
+- **Per-route `<AppLayout>` wrappers** — Every route file wraps its content in `<AppLayout>` or `<Layout>`. React sees a different component at the outlet on each nav and unmounts the whole shell, causing the agent sidebar to reload on every click. Mount the shell once above `<Outlet />` (root.tsx or `_app.tsx` pathless layout).
+- **UI without actions** — The user can create forms but the agent cannot. The agent says "I don't have access to that" when it should be able to do it.
+- **Actions without AGENTS.md** — The actions exist but the agent doesn't know about them because they're not documented. The agent reinvents solutions instead of using the actions.
+- **Duplicate API routes** — Creating `/api/` routes for operations that actions already handle, including pass-through routes that just call or repackage an action. Use `useActionQuery`/`useActionMutation` instead.
+- **Raw client route calls** — Teaching or adding `fetch("/_agent-native/...")`,
+  `fetch(agentNativePath(...))`, or template `/api/*` calls in components for
+  normal app work. Add a named client helper/hook and call that instead.
+- **Features without app-state** — The agent cannot see that the user is looking at a specific form, email, or chart. It asks "which one?" instead of acting on the current selection.
+- **Actions without UI** — The agent can do something the user cannot. This is less common but still breaks parity.
+
+## Verification
+
+After completing all four areas, verify:
+
+1. Can the user perform the operation from the UI?
+2. Can the agent perform the same operation via actions?
+3. Does `pnpm action view-screen` show the relevant state when the user is using the feature?
+4. Can the agent navigate to the feature view via the `navigate` action?
+5. Is the feature documented in AGENTS.md with action names and args?
+6. Are credentials and sensitive data supplied only through approved runtime
+   channels, with no hardcoded real keys, tokens, webhook URLs, Builder/internal
+   data, or customer data?
+
+## One more area — sharing
+
+If the feature stores **user-authored resources** (documents, dashboards, forms, decks, etc.), make them ownable so they get private-by-default semantics and a share dialog for free. See the `sharing` skill.
+
+TL;DR: spread `ownableColumns()` into the resource table, pair it with `createSharesTable(...)`, call `registerShareableResource(...)`, wrap list/read queries with `accessFilter`, guard writes with `assertAccess`, and drop `<ShareButton>` in the resource header. The `share-resource`, `unshare-resource`, `list-resource-shares`, and `set-resource-visibility` actions are auto-mounted framework-wide.
+
+## One more area — who inside the app may do it
+
+If the feature is one **only some teammates should be able to perform inside this app** (an admin-only import, a settings reset), that is a per-app role — not a new organization, and not a share grant. See the `authentication` skill.
+
+TL;DR: declare the vocabulary once with `defineAppRoles({ appId, roles, defaultRole })`, guard the action with `authorize: appAccess.requireAny("...")`, and render the picker with `<TeamPage appRoles={descriptor} />`. `defaultRole` is display only — it never satisfies a guard — and `authorize` gates the operation while `accessFilter` / `assertAccess` still scope the rows.
+
+## Related Skills
+
+- **authentication** — Per-app member roles (`defineAppRoles`) when only some teammates may use a feature
+- **sharing** — How to make a new resource ownable (private by default, share with users/orgs/public)
+- **context-awareness** — How to expose UI state to the agent (area 4 in detail)
+- **actions** — How to create actions with `defineAction` and the `http` option (area 2 in detail)
+- **external-agents** — Add a `link` builder so external agents (MCP/A2A) get an "Open in … →" deep link
+- **create-skill** — How to create skills for new patterns (area 3 in detail)
+- **storing-data** — Where to store the feature's data
+- **real-time-sync** — How the UI stays in sync when the agent writes data
+- **performance** — Query/load cost, and (§9) cold-start artifact size when a
+  feature adds a server-side dependency
+- **internationalization** — How to update localized UI copy and catalogs

package/corpus/templates/assets/.agents/skills/context-awareness/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: context-awareness
+description: >-
+  How the agent knows what the user is looking at. Use when exposing UI state to
+  the agent, implementing view-screen or navigate actions, wiring navigation
+  state, or debugging agent context issues.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Context Awareness
+
+## Rule
+
+The agent must always know what the user is currently viewing. The UI writes navigation state on every route change. The agent reads it before acting.
+
+## Why
+
+Without context awareness, the agent is blind. It asks "which email?" when the user is staring at one. It cannot act on the current selection, cannot provide relevant suggestions, and cannot modify what the user sees. Context awareness is what makes the agent feel like a collaborator rather than a disconnected chatbot.
+
+## The Core Patterns
+
+### 1. Navigation State (`navigation` key)
+
+The UI writes a `navigation` key to application-state on every route change. This tells the agent the semantic screen state: view, open IDs, active tab, and focused object.
+
+**UI side** — `useNavigationState`, an app-owned hook (not a framework import) that every template ships at `app/hooks/use-navigation-state.ts`. It is a thin wrapper around the framework primitive `useAgentRouteState`, handling both directions: writing `navigation` on route change and consuming the agent's `navigate` command.
+
+```tsx
+// app/hooks/use-navigation-state.ts
+import { useAgentRouteState } from "@agent-native/core/client/navigation";
+import { TAB_ID } from "@/lib/tab-id";
+
+export function useNavigationState() {
+  useAgentRouteState({
+    browserTabId: TAB_ID,
+    requestSource: TAB_ID,
+    getNavigationState: ({ pathname, searchParams }) => ({
+      view: pathname === "/" ? "home" : pathname.slice(1),
+      // Optional semantic alias. Raw query params are already exposed in
+      // <current-url> and controllable with set-search-params.
+      label: searchParams.get("label"),
+    }),
+    getCommandPath: (command: any) => command.path ?? "/",
+  });
+}
+```
+
+**Agent side** — read before acting:
+
+```ts
+import { readAppState } from "@agent-native/core/application-state";
+
+const navigation = await readAppState("navigation");
+// e.g. { view: "thread", threadId: "abc123", subject: "Re: Q3 Planning" }
+```
+
+**What to include in navigation state:**
+
+- `view` — the current page/section (e.g., "inbox", "form-builder", "dashboard")
+- Item IDs — the selected/open item (e.g., `threadId`, `formId`, `issueKey`)
+- Semantic aliases — label names, active tabs, focused row, or stable filter names the agent should reason about
+- Any durable selection — focused item, selected text range, active tab
+
+Raw URL query params are already synced by the framework to `__url__` and shown to the built-in agent as `<current-url>`. Keep shareable filters in URL state, then use `view-screen` to summarize important query params as `activeFilters` when helpful.
+
+Keep `application_state` values small. Do not store pasted files, base64 images,
+recording chunks, screenshots, or other large blobs in navigation or app-state
+keys; upload them and store only a URL or storage handle.
+
+### 2. Current URL (`__url__` key)
+
+`AgentPanel` automatically writes `__url__` with `{ pathname, search, hash, searchParams }`. The built-in agent sees it as a `<current-url>` block in every turn.
+
+Use this for URL-reachable filters and search state. The agent can update it with the built-in `set-search-params` and `set-url-path` tools; do not duplicate the whole query string into `navigation`.
+
+### 3. The `view-screen` Script
+
+Every template should have a `view-screen` script. It reads navigation state,
+the current URL if filters matter, and selection state. It fetches the relevant
+data from existing domain actions, shared data helpers, or Drizzle queries, and
+returns a snapshot of what the user sees. Do not add REST wrappers just so
+`view-screen` can read app data. This is the agent's eyes.
+
+```ts
+// actions/view-screen.ts
+import { readAppState } from "@agent-native/core/application-state";
+
+export default async function main() {
+  const navigation = await readAppState("navigation");
+  const url = (await readAppState("__url__")) as {
+    searchParams?: Record<string, string>;
+  } | null;
+  const screen: Record<string, unknown> = { navigation };
+
+  if (url?.searchParams) {
+    screen.activeFilters = url.searchParams;
+  }
+
+  // Fetch data based on what the user is viewing
+  if (navigation?.view === "inbox") {
+    const emails = await fetchEmailList(navigation.label);
+    screen.emailList = emails;
+  }
+  if (navigation?.threadId) {
+    const thread = await fetchThread(navigation.threadId);
+    screen.thread = thread;
+  }
+
+  console.log(JSON.stringify(screen, null, 2));
+}
+```
+
+**Navigation state is auto-injected into every user message as a `<current-screen>` block**, so the agent always has basic context without calling any tool. The `view-screen` action is still useful when you need a richer snapshot (e.g., fetching the full email thread or form data for the current view).
+
+### 4. The `navigate` Script
+
+The agent writes a one-shot `navigate` command to application-state. The UI reads it, performs the navigation, and deletes the entry.
+
+**Agent side:**
+
+```ts
+import { writeAppState } from "@agent-native/core/application-state";
+
+// Navigate the user to a specific thread
+await writeAppState("navigate", { view: "inbox", threadId: "abc123" });
+```
+
+**UI side** — use `useAgentRouteState`, shown above. It polls command keys,
+dedupes `_writeId`, deletes consumed commands, and applies app-local routing.
+
+When a destination has a real URL, let the `navigate` command carry that local
+`path` (plus semantic fields when useful) and have the UI prefer `path` before
+falling back to semantic routing. Keep app navigation single-channel: do not
+also write `__set_url__` for the same navigation. `__set_url__` belongs to the
+framework URL tools (`set-url-path`, `set-search-params`) and URL-only filter
+changes. If a command can arrive while a chat stream is rendering, prefer
+`navigate(path, { replace: true, flushSync: true })` over a view-transition
+wrapper so the URL and visible route commit together.
+
+## Jitter Prevention
+
+When the agent writes to application-state via script helpers (`writeAppState`), the write is tagged with `requestSource: "agent"`. The UI uses the `ignoreSource` option on `useDbSync()` with a per-tab ID so it ignores its own writes while still picking up changes from agents, other tabs, and scripts.
+
+Client code can use `useAgentRouteState`, `useSemanticNavigationState`, `setClientAppState`, `writeClientAppState`, `readClientAppState`, and `deleteClientAppState` from `@agent-native/core/client` instead of hand-written `fetch` calls. Pass `{ requestSource: TAB_ID }` on UI writes when pairing with `useDbSync({ ignoreSource: TAB_ID })`; pass `{ keepalive: true }` for short-lived writes such as selection cleanup during unload.
+
+```ts
+// app/root.tsx
+import { TAB_ID } from "@/lib/tab-id";
+
+useDbSync({
+  queryClient,
+  ignoreSource: TAB_ID,  // ignore events from this tab's own writes
+});
+```
+
+The UI sends its tab ID via `X-Request-Source` header on PUT/DELETE requests. The server stores this as the event's `requestSource`. When processing sync events, the UI filters out events matching its own `ignoreSource` value. This prevents the UI from refetching data it just wrote.
+
+## Gold-Standard Example: Mail Template
+
+The mail template demonstrates these patterns working together:
+
+**Navigation state shape:**
+```json
+{ "view": "inbox", "threadId": "thread-123", "focusedEmailId": "msg-456", "label": "important" }
+```
+
+**view-screen output:**
+- Reads navigation state
+- Reads `__url__` if URL query filters matter
+- Fetches email list matching current view/filter state
+- Fetches thread messages if a thread is open
+- Returns everything as a single JSON snapshot
+
+**navigate command:**
+- `{ "view": "starred" }` — switch to starred view
+- `{ "view": "inbox", "threadId": "thread-123" }` — open a specific thread
+- For pure query-filter changes, use `set-search-params`
+
+## Do
+
+- Use the auto-injected `<current-screen>` block for basic context — call `view-screen` only when you need richer data
+- Include semantic route state in the `navigation` key (view, item IDs, active tab, focused row)
+- Keep shareable filters in URL query params so `<current-url>` and `set-search-params` work
+- Update `view-screen` when adding new features — it should return data for every view
+- Use `useAgentRouteState` or `useSemanticNavigationState` for UI-side navigation sync and command consumption
+- Use the one-shot `navigate` command pattern for app navigation; include a same-origin `path` when the target URL is known
+- Tag agent writes with `requestSource: "agent"` (the script helpers do this automatically)
+
+## Don't
+
+- Don't assume the user is on a specific page — always check navigation state
+- Don't hardcode navigation paths in scripts — read the current state and branch
+- Don't write to the `navigation` key from the agent — it belongs to the UI. Use `navigate` instead.
+- Don't write both `navigate` and `__set_url__` for one app navigation; competing consumers can make the browser URL change before React Router commits the page.
+- Don't ignore the `<current-screen>` block — it tells you where the user is
+- Don't duplicate whole URL query strings into `navigation` when `<current-url>` already exposes them
+- Don't store fetched data in navigation state — it holds IDs and semantic UI state only. The `view-screen` script fetches the actual data.
+
+## Related Skills
+
+- **adding-a-feature** — Context awareness is area 4 of the four-area checklist
+- **real-time-sync** — How `useDbSync` delivers app-state changes to the UI
+- **actions** — How to create the `view-screen` and `navigate` actions
+- **storing-data** — Application-state is one of the core SQL stores