@agent-native/core 0.122.4 → 0.123.0

package/corpus/core/docs/content/template-mail-inbox.mdx

@@ -0,0 +1,118 @@
+---
+title: "Mail: Inbox, Search & Automations"
+description: "Read, search, and triage your Gmail inbox in Mail — keyboard shortcuts, bulk cleanup, auto-triage rules, native Gmail filters, and CRM context on a thread."
+---
+
+# Inbox, Search & Automations
+
+This page covers day-to-day inbox work in [Mail](/docs/template-mail): reading and triaging messages, searching across every connected account, cleaning up in bulk, and the two ways to automate recurring triage. It's written for anyone using Mail, not just developers.
+
+## Reading and triaging
+
+Move through your inbox without touching the mouse:
+
+| Key       | Action                      |
+| --------- | --------------------------- |
+| `J`       | Next email                  |
+| `K`       | Previous email              |
+| `Up/Down` | Same as J/K                 |
+| `Enter`   | Open focused email          |
+| `E`       | Archive email or thread     |
+| `D`       | Trash email or thread       |
+| `S`       | Star or unstar              |
+| `R`       | Reply                       |
+| `U`       | Toggle read/unread          |
+| `C`       | Compose new email           |
+| `/`       | Focus search bar            |
+| `Cmd+K`   | Open command palette        |
+| `G I`     | Go to Inbox                 |
+| `G S`     | Go to Starred               |
+| `G T`     | Go to Sent                  |
+| `G D`     | Go to Drafts                |
+| `G A`     | Go to Archive               |
+| `Esc`     | Close thread / clear search |
+
+Everything a shortcut does, you can also ask for: "archive all Netlify bot emails older than a week," "star anything from Priya," "mark everything in this thread as read."
+
+## Searching across every connected inbox
+
+Type in the search bar, or ask the agent — one query searches across every connected Gmail account at once, not just whichever tab happens to be open. If you've connected personal and work accounts, "find the invoice from Acme" checks both.
+
+## Bulk actions for inbox cleanup
+
+Archiving, starring, and marking read all work in bulk against your real connected Gmail accounts — select several messages (or ask the agent to act on "all of these") and Mail batches the requests per account instead of one call per message. A separate date-based cleanup ("archive anything older than 30 days") and a JSON export of a view are also available, but both currently operate on the local demo mailbox rather than a connected Gmail account.
+
+For clearing out a large backlog of unread mail in one account, use "mark everything unread as read" rather than asking the agent to open and mark each conversation one at a time — Mail runs that as a single verified bulk operation and reports how many messages actually changed.
+
+## Auto-triage rules vs. native Gmail filters
+
+Mail has two distinct ways to automate what happens to incoming mail — pick deliberately:
+
+<Callout tone="info">
+
+**Automation rules** match new mail against a plain-English condition you write ("from a newsletter," "subject contains invoice") using AI, and apply an action (label, archive, mark read, star, trash). They run automatically about once a minute inside Mail.
+
+**Gmail filters** are Gmail's own native mechanism — they run inside Gmail itself, before automation rules ever see the message, and use Gmail's exact search syntax (`from:`, `older_than:`, has-attachment, size, and so on). They keep working even when Mail isn't open.
+
+Use a Gmail filter when the rule is expressible in Gmail's own criteria; use an automation rule when the condition needs judgment ("if this looks like a sales pitch").
+
+</Callout>
+
+<Diagram id="doc-block-mail4" title="Automation rule lifecycle" summary={"A rule you describe in plain English runs against new inbound mail on a recurring schedule and applies its action automatically."}>
+
+```html
+<div class="diagram-flow">
+  <div class="diagram-node">
+    You describe a rule<br /><small class="diagram-muted"
+      >"from a newsletter" → archive</small
+    >
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-panel center">
+    <span class="diagram-pill accent">New inbound mail</span
+    ><small class="diagram-muted">checked every minute</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-box">
+    AI matches condition<br /><small class="diagram-muted"
+      >per rule, per message</small
+    >
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-box">
+    Action applied<br /><small class="diagram-muted"
+      >label · archive · mark read · star · trash</small
+    >
+  </div>
+</div>
+```
+
+```css
+.diagram-flow {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  flex-wrap: wrap;
+}
+.diagram-flow .center {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 4px;
+}
+```
+
+</Diagram>
+
+## CRM context on a thread
+
+Open a thread and Mail's contact sidebar can show CRM context for whoever sent it. HubSpot is the one connected end to end today — ask the agent "who is this and what deals do they have open," and it looks up the contact, up to 5 associated deals, and up to 5 associated tickets from your configured HubSpot account.
+
+Gong, Pylon, and Apollo appear in the same sidebar panel, but only when you've added their API keys in Settings, and only as a read-only sidebar view — the agent cannot pull a Gong call or a Pylon ticket into chat today, only HubSpot.
+
+## What's next
+
+- [**Drafting, Scheduling & the Draft Queue**](/docs/template-mail-drafts-and-queue) — replying to what you just triaged
+- [**Talking to the Agent**](/docs/template-mail-agent) — prompts by task, and when to escalate beyond the canned actions
+- [**Developer Guide**](/docs/template-mail-developers) — the full action inventory behind this page
+- [**Mail overview**](/docs/template-mail) — back to the app summary

package/corpus/core/docs/content/template-mail.mdx

@@ -1,13 +1,13 @@
 ---
 title: "Mail"
-description: "An agent-powered email client. Connect your Gmail and the agent can read, draft, send, and organize email for you."
+description: "An agent-powered Gmail client — a fast keyboard-first inbox you drive yourself, with the agent using the same actions to read, draft, send, and organize email for you."
 ---
 
 # Mail
 
-An agent-powered email client. Connect your Gmail account and the agent can read, draft, send, and organize email for you — alongside a fast, keyboard-first inbox you can drive yourself. Think Superhuman, but the agent is a first-class citizen and the codebase is yours to own.
+Mail is an agent-powered email client for Gmail. Use the keyboard-first inbox yourself, or ask the agent to read, draft, send, and organize mail for you — the agent works through the exact same actions the UI does, so nothing it does is a black box. Think Superhuman, but the agent is a first-class citizen and the codebase is yours to own.
 
-<WireframeBlock id="doc-block-ofadgy">
+<WireframeBlock id="doc-block-mail1">
   <Screen
     surface="desktop"
     html={
@@ -16,9 +16,9 @@ An agent-powered email client. Connect your Gmail account and the agent can read
   />
 </WireframeBlock>
 
-When you open the app, the keyboard-first inbox and thread view stay focused on the mail itself. The agent always knows which view you're in and which thread you have open, so you can say "archive this" or "draft a friendly decline" without explaining what "this" is.
+When you open the app, the keyboard-first inbox and thread view stay focused on the mail itself. The agent always knows which view you're in and which thread you have open, so you can say "archive this" or "draft a friendly decline" without explaining what "this" is — see [Talking to the Agent](/docs/template-mail-agent) for how that works.
 
-<Diagram id="doc-block-jc9hab" title="How a mail request flows" summary={"Keyboard shortcuts and agent prompts run the same actions. Email lives in Gmail; drafts, automations, and tracking live in SQL and application_state."}>
+<Diagram id="doc-block-mail2" title="How a mail request flows" summary={"Keyboard shortcuts and agent prompts run the same actions. Email lives in Gmail; drafts, automations, tracking, and CRM lookups run through SQL, application_state, and the connected provider APIs."}>
 
 ```html
 <div class="diagram-flow">
@@ -36,7 +36,8 @@ When you open the app, the keyboard-first inbox and thread view stay focused on
   <div class="diagram-panel center">
     <span class="diagram-pill accent">Actions</span
     ><small class="diagram-muted"
-      >list-emails · get-thread · manage-draft · send</small
+      >list-emails · manage-draft · send-email · get-hubspot-contact ·
+      create-scheduled-job</small
     >
   </div>
   <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
@@ -46,7 +47,12 @@ When you open the app, the keyboard-first inbox and thread view stay focused on
     </div>
     <div class="diagram-box">
       SQL + application_state<br /><small class="diagram-muted"
-        >drafts · automations · tracking</small
+        >drafts · automations · tracking · queue</small
+      >
+    </div>
+    <div class="diagram-box">
+      HubSpot / raw provider APIs<br /><small class="diagram-muted"
+        >CRM lookup · escalation</small
       >
     </div>
   </div>
@@ -83,14 +89,11 @@ When you open the app, the keyboard-first inbox and thread view stay focused on
 
 ## What you can do with it
 
-- **Read and triage email** with keyboard shortcuts (`J`/`K` to move, `E` to archive, `R` to reply, `C` to compose).
-- **Connect multiple Gmail accounts** — personal and work in one inbox.
-- **Ask the agent to do anything you can do.** "Summarize my unread emails." "Draft a reply that politely declines." "Archive all Netlify bot emails older than a week."
-- **Queue drafts for review.** Teammates and Slack users can ask the agent to prepare an email for an org member; the owner reviews, edits, and sends it from Mail.
-- **Auto-triage with rules.** Set up automation rules in plain English ("from a newsletter") with actions (label, archive, mark read, star, trash).
-- **Track opens and clicks** on the emails you send.
-- **Search across every connected inbox** with one query.
-- **Bulk archive, export, and label** — useful for inbox cleanup.
+- **Read, search, and triage** with keyboard shortcuts or one-line agent prompts, and automate the repetitive parts with rules or native Gmail filters — see [Inbox, Search & Automations](/docs/template-mail-inbox).
+- **Draft, schedule, and send** in your own voice, and let a teammate queue a draft for you to review before it goes out — see [Drafting, Scheduling & the Draft Queue](/docs/template-mail-drafts-and-queue).
+- **Pull CRM context onto a thread.** Look up a sender's HubSpot contact, deals, and tickets without leaving Mail.
+- **Talk to the agent directly** from a full-page Agent tab, with the same screen awareness as chat — see [Talking to the Agent](/docs/template-mail-agent).
+- **Extend Mail** with a custom sidebar widget, or fork the whole template — see the [Developer Guide](/docs/template-mail-developers).
 
 ## Getting started
 
@@ -111,266 +114,12 @@ When you first open the app:
 
 Without a Google account connected, the app runs against an empty local mailbox (useful for screenshots and demos, not much else).
 
-## Talking to the agent
-
-The agent reads `application_state.navigation` on every turn, so it already knows which view you're in, which thread is open, and which message is focused — you don't have to tell it. You can just say things like:
-
-- "Summarize my unread emails."
-- "Find the latest thread from Alice about the budget."
-- "Draft a reply that politely declines."
-- "Archive all Netlify bot emails older than a week."
-- "Open my starred emails."
-- "Make this draft more formal."
-- "Did they open my email?"
-
-If you select text and hit Cmd+I, that selection travels with your next message — so "make this punchier" operates on exactly what you highlighted.
-
-## Keyboard shortcuts
-
-| Key       | Action                      |
-| --------- | --------------------------- |
-| `J`       | Next email                  |
-| `K`       | Previous email              |
-| `Up/Down` | Same as J/K                 |
-| `Enter`   | Open focused email          |
-| `E`       | Archive email or thread     |
-| `D`       | Trash email or thread       |
-| `S`       | Star or unstar              |
-| `R`       | Reply                       |
-| `U`       | Toggle read/unread          |
-| `C`       | Compose new email           |
-| `/`       | Focus search bar            |
-| `Cmd+K`   | Open command palette        |
-| `G I`     | Go to Inbox                 |
-| `G S`     | Go to Starred               |
-| `G T`     | Go to Sent                  |
-| `G D`     | Go to Drafts                |
-| `G A`     | Go to Archive               |
-| `Esc`     | Close thread / clear search |
-
-## For developers
-
-The rest of this doc is for anyone forking the Mail template or extending it.
-
-### Quick start
-
-Create a new workspace with the Mail template:
-
-```bash
-npx @agent-native/core@latest create my-mail --standalone --template mail
-cd my-mail
-pnpm install
-pnpm dev
-```
-
-Or add Mail to an existing agent-native workspace:
-
-```bash
-npx @agent-native/core@latest add-app
-```
-
-To connect Gmail in dev, you need a Google OAuth client:
-
-1. Open [Google Cloud Console](https://console.cloud.google.com/) and create a project.
-2. Enable the **Gmail API** under APIs & Services → Library.
-3. Create OAuth 2.0 credentials (type: Web application). Add `http://localhost:8085/_agent-native/google/callback` as an authorized redirect URI.
-4. Copy the Client ID and Client Secret into the Settings page of the running app, then click **Connect Google account**.
-
-Tokens are stored in the `oauth_tokens` SQL table and refresh automatically. You can connect multiple Gmail accounts once the first is set up.
-
-### Key features
-
-**Multi-account Gmail.** Connect one or more Google accounts, then list, search, draft, send, label, archive, star, or trash across connected inboxes.
-
-**Draft workflows.** Multiple compose drafts sync through application state, and queued SQL drafts let teammates or Slack users request mail for the owner to review and send.
-
-**Automations and tracking.** Natural-language triage rules can label, archive, mark read, star, trash, or trigger manually; sent messages can track opens and clicks.
-
-**Search, bulk actions, and previews.** Shared actions power inbox search, bulk archive/export, and inline thread previews the agent can embed in chat.
-
-### How the agent sees your context
-
-- **Current view and thread** — the UI writes `navigation` (view, threadId, focusedEmailId, search, label) whenever you navigate. The agent reads it via `readAppState("navigation")` or `pnpm action view-screen`.
-- **Open draft** — if you're composing a reply and ask "help me word this", the agent reads the matching `compose-{id}` entry to see your current subject and body, then writes an updated draft back. The UI picks up the edit live.
-- **Thread history** — for context mid-reply, the agent fetches the full thread with `pnpm action get-thread --id=<threadId>`.
-
-### How the agent takes action
-
-- **Mail operations** — archive, trash, star, mark read, send, draft — all run as `pnpm action <name>` scripts under `templates/mail/actions/`.
-- **Navigation** — to open a thread or switch views for you, the agent writes `application_state.navigate`, which the UI consumes and deletes. The `pnpm action navigate` script wraps this.
-- **Refresh** — after any change, the agent runs `pnpm action refresh-list` so the UI refetches.
-
-### Data model
-
-When a Google account is connected, email lives in Gmail — the app is a view on top. When no account is connected, emails live in the SQL settings store under `getSetting("local-emails")` (empty by default).
-
-| Store / Table                 | What it holds                                                  |
-| ----------------------------- | -------------------------------------------------------------- |
-| `getSetting("local-emails")`  | Local email fallback when no Google account is connected       |
-| `getSetting("labels")`        | System and user labels, with unread counts                     |
-| `getSetting("mail-settings")` | User profile, tracking preferences, signature, aliases         |
-| `getSetting("aliases")`       | Email aliases                                                  |
-| `queued_email_drafts` table   | Teammate-requested drafts awaiting owner review/send           |
-| `email_tracking` table        | Open-pixel events for sent messages                            |
-| `email_link_tracking` table   | Link-click events for sent messages                            |
-| `application_state` table     | `navigation`, `navigate`, `compose-{id}` entries (ephemeral)   |
-| `oauth_tokens` table          | Google OAuth tokens (provider `"google"`, one row per account) |
-
-Emails flowing through the API have the shape `{ id, threadId, from, to, cc, subject, snippet, body, date, isRead, isStarred, isArchived, isTrashed, labelIds, accountEmail, attachments }`.
-
-<DataModel
-  id="doc-block-12czj4z"
-  title="Mail SQL tables"
-  summary={
-    "Email itself lives in Gmail. The SQL tables hold what Gmail doesn't: queued drafts, send-tracking events, and OAuth tokens. Settings and ephemeral state live in the settings and application_state stores."
-  }
-  entities={[
-    {
-      id: "queued_email_drafts",
-      name: "queued_email_drafts",
-      note: "Teammate/Slack-requested drafts awaiting owner review",
-      fields: [
-        {
-          name: "id",
-          type: "id",
-          pk: true,
-        },
-        {
-          name: "assignedTo",
-          type: "string",
-          note: "org member who reviews/sends",
-        },
-        {
-          name: "subject",
-          type: "string",
-        },
-        {
-          name: "body",
-          type: "markdown",
-        },
-        {
-          name: "status",
-          type: "enum",
-          note: "review at /draft-queue/<id>",
-        },
-      ],
-    },
-    {
-      id: "email_tracking",
-      name: "email_tracking",
-      note: "Open-pixel events for sent messages",
-      fields: [
-        {
-          name: "id",
-          type: "id",
-          pk: true,
-        },
-        {
-          name: "messageId",
-          type: "string",
-        },
-        {
-          name: "openedAt",
-          type: "datetime",
-        },
-      ],
-    },
-    {
-      id: "email_link_tracking",
-      name: "email_link_tracking",
-      note: "Link-click events for sent messages",
-      fields: [
-        {
-          name: "id",
-          type: "id",
-          pk: true,
-        },
-        {
-          name: "messageId",
-          type: "string",
-          fk: "email_tracking.messageId",
-        },
-        {
-          name: "url",
-          type: "string",
-        },
-        {
-          name: "clickedAt",
-          type: "datetime",
-        },
-      ],
-    },
-    {
-      id: "oauth_tokens",
-      name: "oauth_tokens",
-      note: "Framework table — one row per connected Google account",
-      fields: [
-        {
-          name: "id",
-          type: "id",
-          pk: true,
-        },
-        {
-          name: "provider",
-          type: "string",
-          note: '"google"',
-        },
-        {
-          name: "accountEmail",
-          type: "string",
-        },
-        {
-          name: "accessToken",
-          type: "string",
-        },
-        {
-          name: "refreshToken",
-          type: "string",
-        },
-      ],
-    },
-  ]}
-  relations={[
-    {
-      from: "email_tracking",
-      to: "email_link_tracking",
-      kind: "1-n",
-      label: "click events",
-    },
-  ]}
-/>
-
-Routes in the UI:
-
-- `/_index.tsx` — redirects to the default inbox view.
-- `/$view.tsx` — a list view (`inbox`, `starred`, `sent`, `drafts`, `archive`, `trash`, etc.).
-- `/$view.$threadId.tsx` — a list view with a specific thread open.
-- `/email` — the embedded thread preview used in agent chat.
-- `/settings` — account connections, tracking, automations.
-- `/team` — team members and shared resources.
-
-### Customizing it
-
-Mail is yours to change. Everything important lives in a handful of places — start there.
-
-**Adding an agent capability.** Add a new file under `templates/mail/actions/` using `defineAction`. Your action becomes an agent tool, a CLI command (`pnpm action <name>`), and a typed frontend hook surface through `useActionQuery` / `useActionMutation`. Look at `templates/mail/actions/star-email.ts` for a short example or `templates/mail/actions/manage-automations.ts` for one with multiple sub-actions. See the [actions](/docs/actions) docs for the full pattern.
-
-**Changing the UI.** Routes are in `templates/mail/app/routes/` and components in `templates/mail/app/components/email/` and `templates/mail/app/components/layout/`. The app uses shadcn/ui primitives from `app/components/ui/` and Tabler Icons — stick to those.
-
-**Changing how the agent behaves.** Agent guidance lives in `templates/mail/AGENTS.md` and the skills in `templates/mail/.agents/skills/` (`email-drafts`, `real-time-sync`, `security`, `self-modifying-code`, and others). Agent behavior is changed by editing markdown — not code.
-
-**Changing data or settings.** Schemas for the tracking tables and related structures are in `templates/mail/server/db/`. Settings reads and writes go through `readSetting` / `writeSetting` from `@agent-native/core/settings`. Application state (navigation, drafts, one-shot commands) uses `readAppState` / `writeAppState` from `@agent-native/core/application-state`.
-
-**Adding a new automation action type.** Extend the action schema in `templates/mail/actions/manage-automations.ts` and the executor in `templates/mail/actions/trigger-automations.ts`.
-
-**Changing keyboard shortcuts.** Keybind handlers live in `templates/mail/app/components/email/` — search for `useHotkeys` or `addEventListener("keydown"` to find where each key is wired.
-
-Ask the agent to make any of these changes for you. The agent can edit its own source — see [Self-Modifying Code](/docs/key-concepts#agent-modifies-code).
-
 ## What's next
 
+- [**Inbox, Search & Automations**](/docs/template-mail-inbox) — shortcuts, search, bulk cleanup, and triage rules
+- [**Drafting, Scheduling & the Draft Queue**](/docs/template-mail-drafts-and-queue) — composing, scheduled sends, and teammate-requested drafts
+- [**Talking to the Agent**](/docs/template-mail-agent) — useful prompts, screen awareness, and when to escalate to a raw provider call
+- [**Developer Guide**](/docs/template-mail-developers) — actions, data model, routes, and how to customize Mail
 - [**Templates**](/docs/cloneable-saas) — the clone-and-own model, and every other domain template to start from
-- [**Getting Started**](/docs/getting-started) — the framework fundamentals: actions, application state, and live sync
 - [**Calendar**](/docs/template-calendar) — a sibling domain template covering scheduling and booking
-- [**Automations**](/docs/automations) — the event-triggered engine mail's auto-triage rules build on
-- [**Actions**](/docs/actions) — the action system chat, shortcuts, and automations all call
+- [**Getting Started**](/docs/getting-started) — the framework fundamentals: actions, application state, and live sync