@agent-native/core 0.122.4 → 0.123.1

package/corpus/templates/macros/.agents/skills/storing-data/SKILL.md

@@ -0,0 +1,178 @@
+---
+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.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Storing Data — SQL is the Source of Truth
+
+## Rule
+
+All application data lives in **SQL** (SQLite locally, persistent database in production). The agent and UI share the same database. SQL stores structured records, metadata, references, and searchable text — not large raw file payloads. Do not store durable app data in the filesystem unless the app is explicitly running a Local File Mode artifact flow described below.
+
+Large binary or file-like payloads (images, video/audio, PDFs, ZIPs, screenshots, session replay chunks, thumbnails, generated assets, `data:` URLs, and base64 file bodies) must go through configured file/blob storage such as `uploadFile()` or `putPrivateBlob()`. Persist only the returned URL, asset id, or opaque blob handle in SQL. If storage is unavailable in hosted or persistent-database mode, fail closed with setup guidance instead of falling back to base64 in `application_state`, `settings`, `resources`, or app tables. Local SQLite-only dev fallbacks may exist for tiny assets, but they must be capped, documented as dev-only, and kept off hot list/read paths.
+
+**Local File Mode exception:** some artifact apps (Content, Plans, Slides, Dashboards, Designs, etc.) can intentionally use repo files as the source of truth for the artifact itself. This must be explicit via `agent-native.json`, `AGENT_NATIVE_MODE=local-files`, or an app-owned local-file action helper. In that mode, the UI and agent still go through app actions, but those actions read/write scoped files through `@agent-native/core/local-artifacts` instead of SQL rows. App state, auth, settings, credentials, collaboration metadata, and hosted database mode remain SQL. File-to-database or file-to-provider synchronization is an explicit sync step, not an implicit side effect of editing.
+
+When you add a data model, a list, or a read path, also follow the `performance` skill: project only the columns a list renders, index the columns hot queries filter/sort on, and avoid query waterfalls — so apps stay fast as data grows.
+
+## How It Works
+
+Agent-native apps use Drizzle ORM over the configured SQL backend. Local development works out of the box with a SQLite file at `data/app.db`; production and shared preview deploys need a persistent `DATABASE_URL` because container/serverless filesystems can reset. The code should behave the same across backends, but the local SQLite file is not durable once deployed.
+
+For app code, use Drizzle's schema/query DSL by default. Raw SQL is an escape hatch for additive migrations, health checks, or one-off maintenance, not the normal way to build features.
+
+### Naming migrations
+
+When you add an entry to a `runMigrations([...])` list (`@agent-native/core/db`), always give it a unique `name:` slug (e.g. `name: "analytics-alert-rules-table"`) alongside its `version`. Never renumber or reuse version numbers on existing entries.
+
+Why: version numbers alone are not a safe identity. Two branches that each independently extend the same migration list can ship different DDL under the same version numbers — whichever branch deploys first "claims" those version numbers in the bookkeeping table, and the other branch's DDL is silently treated as already applied even though it never ran. This exact collision took down analytics: parallel branches both extended their migration list through v75-v83 with different DDL, so `analytics_alert_rules`, `analytics_alert_incidents`, and `session_recordings.network_error_count` never made it to production despite the bookkeeping table showing every version as applied. A `name:` slug is tracked independently of version numbers, so it applies exactly once per database regardless of what any other branch already recorded.
+
+Existing unnamed migrations don't need to be renamed retroactively (the two gating strategies coexist), but any new entry should always carry a name.
+
+### 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()` / `putSetting()`            |
+| `oauth_tokens`      | OAuth credentials                                    | `@agent-native/core/oauth-tokens`          |
+| `sessions`          | Auth sessions                                        | `@agent-native/core/server`               |
+
+### Domain Data (per-template)
+
+Define schema with the framework Drizzle helpers in `server/db/schema.ts`. Get a database instance with `const db = getDb()` from `server/db/index.ts`. All queries are async.
+
+```ts
+import { eq } from "drizzle-orm";
+import { table, text, integer, now } from "@agent-native/core/db/schema";
+
+export const tasks = table("tasks", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  completed: integer("completed", { mode: "boolean" })
+    .notNull()
+    .default(false),
+  createdAt: text("created_at").notNull().default(now()),
+});
+
+const rows = await db.select().from(tasks).where(eq(tasks.id, taskId));
+```
+
+Never import `sqliteTable` / `pgTable` or column helpers from `drizzle-orm/sqlite-core` or `drizzle-orm/pg-core` in app templates. Use `@agent-native/core/db/schema` so the same schema can run against SQLite, Postgres, libSQL/Turso, D1, and other supported backends.
+
+| 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 app-specific actions to read/write the database. Core DB scripts are for inspection and maintenance, not for implementing normal product behavior:
+
+- `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 "UPDATE ..."` — Last-resort ad-hoc maintenance for short columns, multi-column writes, or computed updates when no domain action exists. 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 — **always prefer these over raw SQL when one exists.** They encode business rules, power the client action hooks, and for editor-backed tables (documents, slides) also push live Yjs updates to open collaborative editors. `db-patch` is the generic fallback for tables without a dedicated edit action.
+
+**For one-off maintenance, 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 using React Query hooks from the client API. The framework owns the HTTP transport behind these hooks, so components should not call action routes with raw `fetch`.
+
+```ts
+import { useActionQuery, useActionMutation } from "@agent-native/core/client/hooks";
+
+// Read data
+const { data } = useActionQuery("list-meals", { date: "2025-01-01" });
+
+// Write data
+const { mutate } = useActionMutation("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.
+
+### Production / Cloud Deployment
+
+Local SQLite works out of the box for development. To deploy to production or any environment where data must survive restarts:
+
+1. Set `DATABASE_URL` to a persistent SQL database.
+2. Set `DATABASE_AUTH_TOKEN` only when the provider requires a separate token, such as Turso/libSQL.
+3. No code changes should be needed when the schema and queries stay portable.
+
+Turso is one valid option, not the required option. Common choices include Neon or Supabase Postgres, Turso/libSQL, plain Postgres, durable SQLite, Cloudflare D1 bindings, and managed platform SQL environments when available.
+
+### 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 Drizzle query builder methods (`select`, `insert`, `update`, `delete`) and portable operators from `drizzle-orm` (`eq`, `and`, `or`, `inArray`, `desc`, etc.) for app reads/writes
+- Use framework schema helpers from `@agent-native/core/db/schema`, not dialect-specific Drizzle imports
+- 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 `uploadFile()` or `putPrivateBlob()` for large files/blob data and store only URLs, ids, or handles in SQL
+- 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 store large files, base64 blobs, `data:` URLs, screenshots, videos, audio, PDFs, ZIPs, or session replay chunks directly in SQL rows, `application_state`, `settings`, or `resources`
+- Don't implement product features with raw SQL or `getDbExec()` when Drizzle can express the query
+- Don't write SQLite-only or Postgres-only SQL in app code
+- 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
+- **client-methods** — Keep route details behind named client helpers/hooks
+- **self-modifying-code** — The agent can also modify the app's source code

package/corpus/templates/macros/app/entry.client.tsx

@@ -1,7 +1,10 @@
 import { appBasePath } from "@agent-native/core/client/api-path";
+import { installRouteChunkRecovery } from "@agent-native/core/client/route-chunk-recovery";
 import { hydrateRoot } from "react-dom/client";
 import { HydratedRouter } from "react-router/dom";
 
+installRouteChunkRecovery();
+
 const basePath = appBasePath();
 const pathname = window.location.pathname;
 const routerBasePath =

package/corpus/templates/mail/.agents/skills/actions/SKILL.md

@@ -18,6 +18,8 @@ Actions in `actions/` are the **single source of truth** for app operations. The
 
 Before creating any custom REST/API route for app data, inspect `actions/` and the action table in `AGENTS.md`. If an action already exists, call it directly from the agent or with `useActionQuery` / `useActionMutation` from the UI. If the capability is missing, create or update a `defineAction`. Do not add `/api/*`, `server/routes/*`, or other pass-through endpoints whose main job is to call, repackage, or re-export an action.
 
+**Stop trigger:** the moment you are about to create a file under `server/routes/api/` — or add server middleware to guard one — stop and check it against the exception list in *When You Still Need Custom `/api/` Routes* below. If it is not on that list, write a `defineAction` instead. This applies even when you already started the route; abandoning a half-written action to hand-roll routes is the exact failure this rule exists to prevent.
+
 ## Why
 
 Actions give the agent callable tools with structured input/output, AND they give the frontend a typed client contract through hooks. One implementation serves both the agent and the UI. They keep the agent's chat context clean, they're reusable, and they can be tested independently.
@@ -390,12 +392,28 @@ This is the canonical approach for new apps. Action names must be lowercase with
 
 ## When You Still Need Custom `/api/` Routes
 
-Most operations should be actions. You only need custom routes in `server/routes/api/` for:
+This is the complete exception list. A route in `server/routes/api/` is only
+justified when the caller is not your own UI or agent, or when the payload is
+not JSON:
 
 - **File uploads** — actions receive JSON params, not multipart form data
 - **Streaming responses** — SSE or chunked responses that need direct H3 control
 - **Webhooks** — external services POST to a specific URL
 - **OAuth callbacks** — redirect-based flows that need specific URL patterns
+- **Public unauthenticated endpoints** — SEO/OG images, share links, and other
+  URLs opened directly by a browser or crawler
+- **Binary or non-JSON responses** — media, exports, generated assets
+
+Everything else is an action: CRUD, settings, search, list/detail reads, auth
+state, and anything the UI fetches as JSON. If a route needs new middleware to
+scope it to the current user, that is a signal it should be an action — actions
+already run inside request context with access checks.
+
+Existing first-party templates still contain a shrinking, explicitly
+grandfathered set of older `/api/*` CRUD routes for app data. The repository's
+`guard:no-action-twin-routes` CI check ratchets that baseline down across the
+first-party template route trees (with the separately owned Plan template
+fenced out); it is not a substitute for keeping generated apps action-first.
 
 When the agent needs a durable image or file URL, call the core `upload-image`
 action or use `uploadFile()` in server code. Do not write base64 into SQL,

package/corpus/templates/mail/.agents/skills/contacts-and-crm/SKILL.md

@@ -14,6 +14,11 @@ description: >-
 Use `find-contact` before asking the user for someone's email address, and
 before guessing a pattern like `firstinitiallastname@company.com`.
 
+`find-contact` is backed by `loadContactsForEmail`, which merges Google People
+API "connections" (boosted `count += 5`) and "other contacts" with real
+send/receive history. Because it sees actual interaction history, it is strictly
+better than guessing an address pattern.
+
 - `find-contact --query="<name or partial email>" --limit=5` matches
   case-insensitively against name and email, splitting the query into
   whitespace-separated terms that must ALL match (`"jacqueline lamb"` requires
@@ -54,6 +59,11 @@ before guessing a pattern like `firstinitiallastname@company.com`.
   - If the user asks the agent to pull a Gong call or Pylon ticket from Mail,
     say plainly that integration is visible in the UI sidebar only today; do
     not fabricate a result or imply `provider-api-request` can reach it.
+- **Provider API-key connections are Settings-UI only.** Gong, Pylon, Apollo,
+  and HubSpot keys are saved through raw `/api/*` routes from the Settings UI —
+  there are no `save-*-key` actions. The agent can read HubSpot data via
+  `get-hubspot-contact` but cannot configure any of these connections on the
+  user's behalf; ask the user to add the key in Settings.
 - For HubSpot data outside contact lookup (deals search, ticket creation,
   property metadata), use `provider-api-catalog` / `provider-api-docs` with
   `provider: "hubspot"`, then `provider-api-request` — `get-hubspot-contact`

package/corpus/templates/mail/.agents/skills/draft-queue/SKILL.md

@@ -16,6 +16,9 @@ The draft queue is for teammate-requested emails that need the owner to review b
 - Slack requests should queue drafts, not send raw emails.
 - `queue-email-draft` returns `reviewUrl`; include that URL when replying to Slack so the owner can open the exact draft.
 - Slack intake verifies the sender email via Slack `users.info` when the app has `users:read.email`, and passes verified sender name/email into the agent context. If that scope is missing, Slack intake cannot resolve a real email and will not queue anything — tell the requester to ask an admin to grant `users:read.email` rather than guessing their address from their Slack display name.
+- Managed Slack installs request `users:read.email` through the generated OAuth
+  manifest; an existing install must be reconnected after the scope is granted.
+  Legacy bot-token installs must add the scope in Slack manually.
 - `ownerEmail` accepts more than an exact email: `resolveOrgMemberEmail` also
   matches an unambiguous local-part prefix (e.g. `"jane"` matches
   `jane@co.com` if she's the only `jane*` member). If more than one member

package/corpus/templates/mail/.agents/skills/email-drafts/SKILL.md

@@ -158,8 +158,13 @@ via the media endpoint, not retrying the same `filename`.
 ## What Actually Happens on Send
 
 `send-email` requires explicit user intent to send — it is `needsApproval:
-true` and pauses for human approval before the real Gmail call happens. It
-branches on whether the user has a connected Google account:
+true` and pauses for human approval before the real Gmail call happens. This is
+the canonical, intentionally rare use of the human-in-the-loop gate in this
+framework. An authenticated A2A caller may carry the user's exact chat
+authorization for one matching send; otherwise the loop pauses for approval.
+Drafting and queueing are unaffected by the gate.
+
+It branches on whether the user has a connected Google account:
 
 - **Connected:** resolves an access token (refreshing if the account's
   `expiry_date` is within 60s), resolves reply threading (`inReplyTo` /
@@ -183,6 +188,25 @@ branches on whether the user has a connected Google account:
   one can fetch the original message, and uses that account as the sender if
   `account` wasn't explicit.
 
+## Scheduled Sends
+
+Scheduled sends use job ids prefixed `scheduled-`; `send-scheduled-email-now`
+and `cancel-scheduled-email` both strip that prefix internally before looking
+up the job — pass the id as shown to the user either way.
+
+## Snippets
+
+`manage-snippets` lists, creates, updates, and deletes saved reply snippets.
+Users insert them from the compose slash menu, so a snippet the agent saves
+becomes available there immediately.
+
+## Aliases Are Settings-UI Only
+
+Aliases (Settings → Aliases) are managed only through raw `/api/*` routes from
+the Settings UI — there is no `manage-aliases` action, so the agent cannot add,
+edit, or remove an alias on the user's behalf. Point the user at Settings →
+Aliases instead.
+
 ## Important Notes
 
 - The `id` field in the JSON MUST match the `{id}` in the key name (`compose-{id}`)

package/corpus/templates/mail/.agents/skills/frontend-design/SKILL.md

@@ -1,14 +1,17 @@
 ---
 name: frontend-design
 description: >-
-  Create distinctive, production-grade frontend interfaces with high design
-  quality. Use when building web components, pages, artifacts, posters, or
-  applications (websites, landing pages, dashboards, React components,
-  HTML/CSS layouts, or when styling/beautifying any web UI). Generates
-  creative, polished UI that avoids generic AI aesthetics.
+  Sets the visual direction for a new or redesigned surface, with production
+  quality that avoids generic AI aesthetics. Use when building a new page,
+  app, or marketing surface, defining visual identity, or doing a design pass
+  ("make this look good"). Do not load it for routine UI edits: adding a field
+  to an existing form, fixing spacing, wiring a button, or changing copy.
 scope: dev
 license: Complete terms in LICENSE.txt
 source: https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md
+local-changes: >-
+  Description narrowed and Verification rescoped deliberately; an upstream sync
+  must not restore the broad auto-load triggers or screenshot-everything step.
 metadata:
   internal: true
 ---
@@ -141,11 +144,22 @@ Avoid:
 
 ## Verification
 
+Match verification effort to the size of the change. For one component, one
+form, one page, or a restyle, run the app's existing checks — formatter,
+`pnpm typecheck`, existing tests — and stop there.
+
+Escalate to browser verification only when the user asks for it, or when the
+change is a multi-step user-visible flow that cannot be confirmed any other
+way. Never author a new Playwright/Puppeteer script, add a browser-automation
+dependency, or stand up an e2e harness to check work the user did not ask you
+to test that way; use an available browser tool, or say what you could not
+verify.
+
 For substantial frontend work:
 
 1. Run the relevant formatter/checks.
 2. Start the dev server when the app needs one.
-3. Verify with browser screenshots at desktop and mobile widths.
+3. Verify with the available browser tooling at desktop and mobile widths.
 4. Check interactive states: hover, focus, loading, empty, error, and destructive confirmations.
 5. When registering or changing a company adapter, run
    `@agent-native/toolkit/conformance`, including mixed-overlay focus,

package/corpus/templates/mail/.agents/skills/inbox-automations/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: inbox-automations
+description: >-
+  Natural-language inbox automation rules (manage-automations,
+  trigger-automations) and provider-native Gmail filters
+  (manage-gmail-filters), including how the two differ. Use when the user asks
+  to auto-label, auto-archive, auto-star, or otherwise handle incoming mail
+  automatically, or to create/replace/delete a Gmail filter.
+---
+
+# Inbox Automations and Gmail Filters
+
+## Automation rules
+
+`manage-automations` rules match new inbound mail against a natural-language
+`condition` using AI, then apply `actions` (`label`, `archive`, `mark_read`,
+`star`, `trash`). Rules run on a per-minute cron automatically;
+`trigger-automations` forces immediate processing (debounced — a
+just-triggered run may report "skipped, try again in 30 seconds").
+
+## Gmail filters are a different mechanism
+
+Gmail filters (`manage-gmail-filters`) are a distinct, provider-native
+mechanism from automation rules — filters run inside Gmail itself, apply
+before automations, and support raw Gmail criteria/actions. Gmail has no
+filter-update endpoint: the `replace` operation works by creating a new
+filter and deleting the old one.
+
+Pick the mechanism deliberately: use a Gmail filter when the rule is
+expressible in Gmail's own criteria and should apply even when this app isn't
+running; use an automation rule when the condition needs natural-language
+judgement.
+
+## Related Skills
+
+- `inbox-reads-and-triage` — one-off triage and refreshing the UI afterwards.
+- `mail-backends` — Gmail filters require a connected Google account.

package/corpus/templates/mail/.agents/skills/inbox-reads-and-triage/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: inbox-reads-and-triage
+description: >-
+  Listing and searching mail with coverage-aware inventory envelopes, refreshing
+  the UI after mutations, and bulk unread cleanup. Use when reading, searching,
+  counting, archiving, starring, moving, or marking mail read, or when reporting
+  how much of an inbox was covered.
+---
+
+# Inbox Reads and Triage
+
+## Coverage-aware inventory reads
+
+`list-emails` remains the compatibility list action for the UI and internal
+callers. External MCP callers receive its structured inventory envelope by
+default (or pass `format: "inventory"`). Inventory reads use `accountEmails`
+for an explicit set; the legacy singular `account` alias cannot be combined
+with it. The response reports each account's success, empty result, exhaustion
+or bounded error, so partial coverage must never be described as complete.
+Inventory items are intentionally compact metadata only — use `get-email` or
+`get-thread` only after selecting a specific result when body content is
+needed.
+
+## Refresh after mutations
+
+After backend mail mutations (archive, trash, star, mark-read, move, send),
+call `refresh-list` so the UI refetches. Actions that already write
+`refresh-signal` internally (e.g. `mark-thread-read`, `move-email`,
+`respond-calendar-invite`) don't need a second call.
+
+## Bulk unread cleanup
+
+For broad unread cleanup in one account, call `mark-read` once with
+`scope: "all-unread"`, the exact `accountEmail`, and any protected
+conversation IDs in `excludeThreadIds`. Do not loop `mark-thread-read` over
+many conversations. The bulk result's matched, excluded, changed, failure,
+and remaining-unread counts are the proof of completion.
+
+## Knowing what the user is looking at
+
+Use `view-screen` when the active thread, selected message, draft, or queue
+item is unclear. Use `get-thread` for full conversation context instead of
+relying on ambient screen text.
+
+## Moving the UI
+
+`navigate` accepts `view` (`inbox`, `starred`, `sent`, `drafts`, `scheduled`,
+`archive`, `trash`, `draft-queue`, `settings`), plus `threadId`,
+`settingsSection` (`drafting`, `automations`, `gmail-filters`, `aliases`,
+`tracking`, `slack`, `team`), `queuedDraftId`, or `composeDraftId`.
+
+## Related Skills
+
+- `mail-backends` — whether a read hit real Gmail or the local fallback.
+- `provider-api-scans` — reads beyond the canned actions, and staging large
+  scans for analysis.
+- `email-drafts` — replying to something you just read.
+- `inbox-automations` — automating recurring triage instead of repeating it.

package/corpus/templates/mail/.agents/skills/mail-backends/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: mail-backends
+description: >-
+  How Mail actions pick between the real Gmail API and synthetic local-emails
+  fallback data per user. Use when mail data looks fake or empty, when a user
+  has no connected Google account, or before claiming a message really was
+  sent or fetched from Gmail.
+---
+
+# Mail Backends
+
+## Rule
+
+**Two mail backends, chosen automatically per user.** When the user has a
+connected Google account (`isConnected(ownerEmail)`), actions call the real
+Gmail API. When no account is connected, the same actions fall back
+transparently to synthetic `local-emails` data stored via `getUserSetting` /
+`putUserSetting`. Never assume Gmail is connected — actions like
+`search-emails`, `list-emails`, `get-thread`, `get-email`, and `move-email`
+branch on this internally, so call them the same way either way.
+
+## Why it matters
+
+The fallback exists so the app is usable and demoable without OAuth. It is not
+a queue that later flushes to Gmail. If you are in fallback mode, do not tell
+the user that mail left their real inbox or that a real Gmail record changed —
+say the data is local demo state.
+
+## Related Skills
+
+- `inbox-reads-and-triage` — reading mail and reporting coverage honestly.
+- `email-drafts` — what `send-email` does in each mode, including the synthetic
+  "Sent" item written to `local-emails`.

package/corpus/templates/mail/.agents/skills/provider-api-scans/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: provider-api-scans
+description: >-
+  Call raw Gmail, Google Calendar, or HubSpot endpoints through
+  provider-api-catalog / provider-api-docs / provider-api-request, and stage
+  large result sets with stageAs plus query-staged-dataset. Use when a canned
+  Mail action lacks the exact endpoint, filter, pagination, or API version, or
+  when scanning/aggregating many messages.
+---
+
+# Provider API and Staged Scans
+
+## Rule
+
+Treat provider-specific actions as shortcuts, not capability limits. When the
+exact Gmail, Google Calendar, or HubSpot endpoint/filter/pagination/API
+version matters, use `provider-api-catalog`, `provider-api-docs`, and
+`provider-api-request` against the real provider API.
+
+## Staging large scans
+
+For large scans, stage results with `stageAs` and analyze them with
+`query-staged-dataset` (`list-staged-datasets` / `delete-staged-dataset`
+manage the scratch rows). Staging keeps big provider payloads out of the
+conversation: pass ids, counts, and bounded summaries instead of pasting raw
+dumps.
+
+## What Mail can reach
+
+Mail's catalog resolves to `gmail`, `google_calendar`, and `hubspot` only
+(`MAIL_PROVIDER_API_IDS` / `listProviderApiIdsForTemplateUse("mail")` in
+`server/lib/provider-api.ts`). Gong, Pylon, and Apollo are not reachable
+through `provider-api-request` in this app — see `contacts-and-crm`.
+
+## Related Skills
+
+- `contacts-and-crm` — which CRM providers are agent-reachable in Mail.
+- `inbox-reads-and-triage` — prefer the canned read actions when they already
+  express the query.

package/corpus/templates/mail/.agents/skills/security/SKILL.md

@@ -127,6 +127,8 @@ Two more CI guards (also wired into `pnpm prep`) target the 2026-04 cross-tenant
 - `scripts/guard-no-env-mutation.mjs` — bans `process.env.<KEY> = …` (and bracket / compound forms) anywhere in production code. On serverless, every warm container handles many concurrent requests in one Node process, so `process.env` mutation leaks across in-flight requests (the "restore" line at the end of a handler races and never helps — most recently the Zoom webhook). Use `runWithRequestContext({ userEmail, orgId, timezone }, fn)` from `@agent-native/core/server` instead — it's AsyncLocalStorage-backed and per-request safe. Allowlisted paths: `scripts/`, `*.spec.ts` / `*.test.ts`, `packages/core/src/dev**`, `templates/*/test/`, anything under `/cli/` or `/scaffold/`. Per-line opt-out: `process.env.X = y // guard:allow-env-mutation — <reason>`.
 - `scripts/guard-no-localhost-fallback.mjs` — bans the literal `"local@localhost"` / `'local@localhost'` / `` `local@localhost` `` in production code. The bug class: `getRequestUserEmail() ?? "local@localhost"` silently pools every unauthenticated request into a single shared tenant, leaking credentials, tools, and `application_state` rows between accounts. The right behavior is to throw / 401 when there's no session. Allowlisted paths: the dev-mode auth shim (`packages/core/src/server/auth.ts`), `packages/core/src/dev**`, tests, `scripts/`, `seed/` / `seeds/`, plus a few framework helpers that intentionally inspect or migrate the dev identity. SQL DDL `DEFAULT 'local@localhost'` and the Drizzle helper `.default('local@localhost')` are skipped per-line — schema column defaults are intentional dev fixtures, not the dangerous fallback pattern. Per-line opt-out: `email ?? "local@localhost" // guard:allow-localhost-fallback — <reason>`.
 
+  The same guard also bans the **ambient process identity** as a request-scoped fallback: `?? process.env.AGENT_USER_EMAIL`, `|| process.env.WORKSPACE_OWNER_EMAIL`, and `?? getAmbientUserEmail()`. Those name the identity of the *deployment*, not the caller, so a handler reading one authorizes whoever the deploy env names rather than whoever signed in — it fails open toward more privilege. Exempt paths are the ones with no request by construction: `scripts/` (including `templates/*/scripts/`), `src/cli/`, `src/scripts/`, `script-helpers.ts` / `script-entries.ts`, tests, and seeds. It deliberately matches only the `??` / `||` fallback position, so reading the same env var to build an admin allowlist (`envEmails("WORKSPACE_OWNER_EMAIL").includes(email)`) is untouched. Known gaps, both requiring dataflow analysis the guard does not do: an env read aliased through a local (`const fallback = process.env.AGENT_USER_EMAIL; … ?? fallback`) and a destructured `const { AGENT_USER_EMAIL } = process.env`.
+
 ## Auth
 
 - All actions are protected by the auth guard automatically.

package/corpus/templates/mail/.agents/skills/self-modifying-code/SKILL.md

@@ -1,9 +1,10 @@
 ---
 name: self-modifying-code
 description: >-
-  How the agent can modify the app's own source code. Use when the agent needs
-  to edit components, routes, styles, or scripts, when designing UI for agent
-  editability, or when deciding what the agent should and shouldn't modify.
+  Tiers, checkpoints, and off-limits paths for an agent editing the app's own
+  source. Use when designing UI for agent editability, deciding whether a file
+  is safe for the agent to change, or when tempted to patch config, `.env`, or
+  an `@agent-native/*` package. Do not load it for ordinary source edits.
 scope: dev
 metadata:
   internal: true

package/corpus/templates/mail/.agents/skills/shadcn-ui/SKILL.md

@@ -1,11 +1,15 @@
 ---
 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.
+  The shadcn CLI, component composition, theming, and registry workflow. Use
+  when adding, replacing, upgrading, or debugging a shadcn/ui primitive itself,
+  or when changing a theme or registry. Do not load it for ordinary edits to a
+  file that happens to import a shadcn component.
 scope: dev
 source: https://ui.shadcn.com/docs/skills
+local-changes: >-
+  Description narrowed deliberately; an upstream sync must not restore the
+  "any project with a components.json file" trigger.
 metadata:
   internal: true
 ---