@vellumai/assistant 0.5.16 → 0.6.1

package/src/config/bundled-skills/app-builder/SKILL.md

@@ -238,7 +238,7 @@ export const Header: FunctionComponent<HeaderProps> = ({ title, count }) => (
 
 file_write("{workspaceDir}/data/apps/project-tracker/src/styles.css", `.app { padding: var(--v-spacing-lg); }
 .header { display: flex; justify-content: space-between; align-items: center; }
-.badge { background: var(--v-accent); color: white; padding: var(--v-spacing-xs) var(--v-spacing-sm); border-radius: var(--v-radius-pill); }`)
+.badge { background: var(--v-accent); color: var(--v-aux-white); padding: var(--v-spacing-xs) var(--v-spacing-sm); border-radius: var(--v-radius-pill); }`)
 
 # After all files are written, compile and refresh:
 app_refresh(app_id)
@@ -290,9 +290,12 @@ Available design tokens:
 | **Typography**  | `--v-font-family`, `--v-font-mono`, `--v-font-size-xs` (10px) / `-sm` (11px) / `-base` (14px) / `-lg` (17px) / `-xl` (22px) / `-2xl` (26px), `--v-line-height` |
 | **Animation**   | `--v-duration-fast` (0.15s) / `-standard` (0.25s) / `-slow` (0.4s)                                                                                             |
 | **Palettes**    | `--v-slate-{950..50}`, `--v-emerald-*`, `--v-violet-*`, `--v-indigo-*`, `--v-rose-*`, `--v-amber-*`                                                            |
+| **Constant**    | `--v-aux-white` (always `#FFFFFF` in both modes — use for text on filled/accent backgrounds)                                                                    |
 
 Utility classes: `.v-button` (`.secondary`/`.danger`/`.ghost`), `.v-card`, `.v-list`/`.v-list-item`, `.v-badge` (`.success`/`.warning`/`.danger`), `.v-input-row`, `.v-empty-state`, `.v-toggle`.
 
+**Never hardcode `color: white` or `color: #fff`.** Use `var(--v-aux-white)` for text on filled/accent backgrounds, or `var(--v-text)` / `var(--v-text-secondary)` for text on surface backgrounds. Hardcoded white causes invisible text on light surfaces.
+
 **Custom themes:** When the user wants a specific branded look, write complete CSS with hardcoded colors and `@media (prefers-color-scheme: dark)` for dark variants. Don't mix `--v-*` auto-switching variables with hardcoded colors in the same element.
 
 **Theme detection in JavaScript:**

package/src/config/bundled-skills/contacts/SKILL.md

@@ -6,7 +6,6 @@ metadata:
   emoji: "👥"
   vellum:
     display-name: "Contacts"
-    feature-flag: "contacts"
 ---
 
 Manage the user's contacts, relationship graph, access control (trusted contacts), and invite links. This skill covers contact CRUD with multi-channel tracking, controlling who can message the assistant through external channels (Telegram, phone), and creating/managing invite links that grant access.

package/src/config/bundled-skills/contacts/TOOLS.json

@@ -47,14 +47,6 @@
                 "is_primary": {
                   "type": "boolean",
                   "description": "Whether this is the primary channel for this type"
-                },
-                "external_user_id": {
-                  "type": "string",
-                  "description": "Platform-native user ID (e.g. Slack user ID like U12345). Used to cache user lookups."
-                },
-                "external_chat_id": {
-                  "type": "string",
-                  "description": "Platform-native chat/DM channel ID (e.g. Slack DM channel like D12345). Used to cache DM channel lookups."
                 }
               },
               "required": ["type", "address"]

package/src/config/bundled-skills/contacts/tools/contact-upsert.ts

@@ -63,16 +63,12 @@ export async function executeContactUpsert(
         type: string;
         address: string;
         is_primary?: boolean;
-        external_user_id?: string;
-        external_chat_id?: string;
       }>
     | undefined;
   const channels = rawChannels?.map((ch) => ({
     type: ch.type,
     address: ch.address,
     isPrimary: ch.is_primary,
-    externalUserId: ch.external_user_id,
-    externalChatId: ch.external_chat_id,
   }));
 
   try {

package/src/config/bundled-skills/gmail/SKILL.md

@@ -28,22 +28,14 @@ Do not offer AgentMail as an option or mention it unless the user specifically a
 ### Gmail
 
 1. **Try connecting directly first.** Run `assistant oauth status google`. This will show whether or not the user had previously connected their google account. If so, they are ready to go.
-2. **If no connections are found:** The user needs to either use Vellum's managed google integration or set up their own google oauth app. 
-   - Call `skill_load` with `skill: "vellum-oauth-integrations"` with `provider-key: google` throughout.
-   - To use `your-own` mode, you will need to call `skill_load` with `skill: google-oauth-app-setup`. In this case:
-      - Tell the user Gmail isn't connected yet and briefly explain what the setup involves, then use `ui_show` with `surface_type: "confirmation"` to ask for permission to start:
-      - **message:** "Ready to set up Gmail?"
-      - **detail:** "I'll open a few pages in your browser and walk you through setting up Google Cloud credentials - creating a project, enabling APIs, and connecting your account. Takes about 5 minutes.\n\n**Your emails stay under your control** — I only ever create drafts. Nothing gets sent without your explicit say-so."
-      - **confirmLabel:** "Get Started"
-      - **cancelLabel:** "Not Now"
-      - If the user confirms, briefly acknowledge (e.g., "Setting up Gmail now...") and proceed with the setup guide. If they decline, acknowledge and let them know they can set it up later.
+2. **If no connections are found:** Call `skill_load` with `skill: "vellum-oauth-integrations"`. The skill will evaluate whether managed or your-own mode is appropriate and guide the user accordingly.
 
 ## Error Recovery
 
 When a Gmail tool fails with a token or authorization error:
 
 1. **Try to reconnect silently.** Call `assistant oauth ping google`. This often resolves expired tokens automatically.
-2. **If reconnection fails, go straight to setup.** Don't present options, ask which route the user prefers, or explain what went wrong technically. Just tell the user briefly (e.g., "Gmail needs to be reconnected - let me set that up") and immediately follow the connection setup flow for Gmail (e.g., install and load **google-oauth-app-setup**). The user came to you to get something done, not to troubleshoot OAuth - make it seamless.
+2. **If reconnection fails, go straight to setup.** Don't present options, ask which route the user prefers, or explain what went wrong technically. Just tell the user briefly (e.g., "Gmail needs to be reconnected - let me set that up") and immediately load **vellum-oauth-integrations**. The user came to you to get something done, not to troubleshoot OAuth - make it seamless.
 3. **Never try alternative approaches.** Don't use bash, curl, browser automation, or any workaround. If the Gmail tools can't do it, the reconnection flow is the answer.
 4. **Never expose error details.** The user doesn't need to see error messages about tokens, OAuth, or API failures. Translate errors into plain language.
 
@@ -164,9 +156,9 @@ Scan tools (`gmail_sender_digest`, `gmail_outreach_scan`) return a `scan_id` tha
 
 Before composing any email that references a date or time:
 
-1. Check the `<temporal_context>` block in the current turn for today's date and timezone
+1. Check the `timestamp:` field in the `<turn_context>` block for today's date and timezone
 2. Verify that "tomorrow" means the day after today's date, "next week" means the upcoming Monday–Friday, etc.
-3. If the email references a date from another message, cross-check it against the temporal context to ensure it's in the future
+3. If the email references a date from another message, cross-check it against the turn context to ensure it's in the future
 
 ## Confidence Scores
 

package/src/config/bundled-skills/google-calendar/SKILL.md

@@ -15,15 +15,7 @@ You are a Google Calendar assistant with full access to the user's calendar. Use
 Before using any Calendar tool, verify that Google Calendar is connected by attempting a lightweight call (e.g., `calendar_list_events` with a narrow date range). If the call fails with a token/authorization error:
 
 1. **Try connecting directly first.** Run `assistant oauth status google`. This will show whether or not the user had previously connected their google account. If so, they are ready to go.
-2. **If no connections are found:** The user needs to either use Vellum's managed google integration or set up their own google oauth app. 
-   - Call `skill_load` with `skill: "vellum-oauth-integrations"` with `provider-key: google` throughout.
-   - To use `your-own` mode, you will need to call `skill_load` with `skill: google-oauth-app-setup`. In this case:
-      - Tell the user Google account isn't connected yet and briefly explain what the setup involves, then use `ui_show` with `surface_type: "confirmation"` to ask for permission to start:
-      - **message:** "Ready to set up Google Calendar?"
-      - **detail:** "I'll open a few pages in your browser and walk you through setting up Google Cloud credentials - creating a project, enabling APIs, and connecting your account. Takes about 5 minutes.\n\n**Your emails stay under your control** — I only ever create drafts. Nothing gets sent without your explicit say-so."
-      - **confirmLabel:** "Get Started"
-      - **cancelLabel:** "Not Now"
-      - If the user confirms, briefly acknowledge (e.g., "Setting up Google Calendar now...") and proceed with the setup guide. If they decline, acknowledge and let them know they can set it up later.
+2. **If no connections are found:** Call `skill_load` with `skill: "vellum-oauth-integrations"`. The skill will evaluate whether managed or your-own mode is appropriate and guide the user accordingly.
 
 ## Capabilities
 

package/src/config/bundled-skills/messaging/SKILL.md

@@ -19,13 +19,13 @@ You are a unified messaging assistant with access to multiple platforms (Gmail,
 
 When composing messages on behalf of your user to external recipients, refer to yourself as an "assistant" (not "AI assistant"). Use your user's name and pronouns from USER.md. Don't volunteer that you are an AI unless directly asked.
 
-For Gmail management (archive, label, triage, declutter), load the **gmail** skill. For email sequences, load the **sequences** skill.
+For Email management (archive, label, triage, declutter), load the **gmail** or **outlook** skill. For email sequences, load the **sequences** skill.
 
 ## Email Routing Priority
 
-When the user mentions "email" - sending, reading, checking, decluttering, drafting, or anything else - **always default to the user's own email (Gmail)** unless they explicitly ask about the assistant's own email address (e.g., "set up your email", "send from your address", "check your inbox"). The vast majority of email requests are about the user's Gmail, not the assistant's AgentMail address.
+When the user mentions "email" - sending, reading, checking, decluttering, drafting, or anything else - **always default to the user's own email** unless they explicitly ask about the assistant's own email address (e.g., "set up your email", "send from your address", "check your inbox"). The vast majority of email requests are about the user's Gmail or Outlook, not the assistant's AgentMail address.
 
-Do not offer AgentMail as an option or mention it unless the user specifically asks. If Gmail is not connected, guide them through Gmail setup - do not suggest AgentMail as an alternative.
+Do not offer AgentMail as an option or mention it unless the user specifically asks. If Gmail and Outlookk are not connected, guide them through setup - do not suggest AgentMail as an alternative.
 
 ## Communication Style
 
@@ -44,33 +44,25 @@ Before using any messaging tool, verify that the platform is connected by callin
 
 ### Public Ingress (required for Telegram)
 
-Telegram setup requires webhook routing, but it does **not** always require ngrok. Before suggesting public ingress for Telegram, check managed callback availability with `assistant platform status --json`. If that reports `containerized: true` with a non-empty `assistantId` and `available: true`, use the platform callback route flow and do not prompt for ngrok. Only use the **public-ingress** skill for local assistants that genuinely need a public gateway URL. Slack uses Socket Mode and does not require public ingress. Gmail on the desktop app uses a loopback callback and does not require public ingress; the channel path (Path B in the google-oauth-app-setup skill) handles public ingress internally when needed.
+Telegram setup requires webhook routing, but it does **not** always require ngrok. Before suggesting public ingress for Telegram, check managed callback availability with `assistant platform status --json`. If that reports `isPlatform: true` with a non-empty `assistantId` and `available: true`, use the platform callback route flow and do not prompt for ngrok. Only use the **public-ingress** skill for local assistants that genuinely need a public gateway URL. Slack uses Socket Mode and does not require public ingress. Gmail/Outlook on the desktop app uses a loopback callback and does not require public ingress; the channel path (Path B in the vellum-oauth-integrations skill) handles public ingress internally when needed.
 
 ### Email Connection Flow
 
 When the user asks to "connect my email", "set up email", "manage my email", or similar - and has not named a specific provider:
 
-1. **Discover what's connected.** Call `messaging_auth_test` for `gmail` (and any other email-capable platforms). If one succeeds, tell the user it's already connected and proceed with their request.
+1. **Discover what's connected.** Call `messaging_auth_test` for `gmail`or `outlook` (and any other email-capable platforms). If one succeeds, tell the user it's already connected and proceed with their request.
 2. **If nothing is connected**, ask which provider they use - but keep it brief and conversational (e.g., "Which email do you use - Gmail, Outlook, etc.?"), not a numbered list of options with descriptions.
-3. **Once the provider is known, act immediately.** Don't present setup options or explain OAuth. If it's Gmail, follow the Gmail section below. For any other provider, let the user know that only Gmail is fully supported right now, and offer to set up Gmail instead.
+3. **Once the provider is known, act immediately.** Don't present setup options or explain OAuth. If it's Gmail or Outlook, follow the sections below. For any other provider, let the user know that only Gmail and Outlook are fully supported right now, and offer to set up Gmail/Outlook instead.
 
 ### Gmail
 
 1. **Try connecting directly first.** Run `assistant oauth status google`. This will show whether or not the user had previously connected their google account. If so, they are ready to go.
-2. **If no connections are found:** The user needs to either use Vellum's managed google integration or set up their own google oauth app.
-   - Call `skill_load` with `skill: "vellum-oauth-integrations"` with `provider-key: google` throughout.
-   - To use `your-own` mode, you will need to call `skill_load` with `skill: google-oauth-app-setup`. In this case:
-     - Tell the user Gmail isn't connected yet and briefly explain what the setup involves, then use `ui_show` with `surface_type: "confirmation"` to ask for permission to start:
-     - **message:** "Ready to set up Gmail?"
-     - **detail:** "I'll open a few pages in your browser and walk you through setting up Google Cloud credentials - creating a project, enabling APIs, and connecting your account. Takes about 5 minutes."
-     - **confirmLabel:** "Get Started"
-     - **cancelLabel:** "Not Now"
-     - If the user confirms, briefly acknowledge (e.g., "Setting up Gmail now...") and proceed with the setup guide. If they decline, acknowledge and let them know they can set it up later.
+2. **If no connections are found:** Call `skill_load` with `skill: "vellum-oauth-integrations"`. The skill will evaluate whether managed or your-own mode is appropriate and guide the user accordingly.
 
 ### Outlook
 
 1. **Try connecting directly first.** Run `assistant oauth status outlook`. This will show whether the user has previously connected their Outlook account.
-2. **If no connections are found:** Guide the user to connect their Microsoft account through the OAuth flow.
+2. **If no connections are found:** Call `skill_load` with `skill: "vellum-oauth-integrations"`. The skill will evaluate whether managed or your-own mode is appropriate and guide the user accordingly.
 
 ### Slack
 
@@ -101,7 +93,7 @@ The guardian-verify-setup skill handles the full outbound verification flow for
 When a messaging tool fails with a token or authorization error:
 
 1. **Try to reconnect silently.** Run `assistant oauth ping <provider>`. This often resolves expired tokens automatically.
-2. **If reconnection fails, go straight to setup.** Don't present options, ask which route the user prefers, or explain what went wrong technically. Just tell the user briefly (e.g., "Gmail needs to be reconnected - let me set that up") and immediately follow the connection setup flow for that platform (e.g., install and load **google-oauth-app-setup** for Gmail). The user came to you to get something done, not to troubleshoot OAuth - make it seamless.
+2. **If reconnection fails, go straight to setup.** Don't present options, ask which route the user prefers, or explain what went wrong technically. Just tell the user briefly (e.g., "Gmail needs to be reconnected - let me set that up") and immediately load **vellum-oauth-integrations**. The user came to you to get something done, not to troubleshoot OAuth - make it seamless.
 3. **Never try alternative approaches.** Don't use bash, curl, browser automation, or any workaround. If the messaging tools can't do it, the reconnection flow is the answer.
 4. **Never expose error details.** The user doesn't need to see error messages about tokens, OAuth, or API failures. Translate errors into plain language.
 
@@ -114,7 +106,7 @@ When a messaging tool fails with a token or authorization error:
 
 ## Capabilities
 
-### Universal (Gmail)
+### Gmail
 
 - **Auth Test**: Verify connection and show account info
 - **List Conversations**: Show inboxes, DMs with unread counts
@@ -156,6 +148,7 @@ Telegram is supported as a messaging provider with limited capabilities compared
 - `send_notification` is provided by the **notifications** skill (always active) -- use it when the user asks for an alert/notification (for example "send this as a desktop notification").
 - Use `messaging_send` when the user asks to send a message into a specific chat/email destination.
 - `send_notification` channel routing is LLM-driven; `preferred_channels` are hints, not hard channel forcing.
+- Before using `messaging_send` or `send_notification`, look up the recipient's contact record with `contact_search` to inform tone and content (see **Recipient Context** below).
 
 ## Personalized Drafting
 
@@ -165,6 +158,12 @@ If no style items exist and the user asks you to draft a message, suggest runnin
 
 > "I can analyze your sent messages to learn your writing style so drafts sound like you. Want me to do that?"
 
+## Recipient Context
+
+Before composing or sending a message to someone, look up their contact record with `contact_search` using their name or channel address. If the contact has notes (e.g. relationship context, communication preferences, response expectations), use that context to inform the message's tone, level of detail, and content. This ensures outbound messages are personalized to the recipient — not just the sender's style.
+
+If no contact record exists, proceed without recipient context.
+
 ## Confidence Scores
 
 Medium and high risk tools require a confidence score between 0 and 1:

package/src/config/bundled-skills/messaging/tools/messaging-analyze-style.ts

@@ -1,10 +1,9 @@
-import { and, eq } from "drizzle-orm";
+import { and, eq, sql } from "drizzle-orm";
 import { v4 as uuid } from "uuid";
 
 import { getDb } from "../../../../memory/db.js";
-import { computeMemoryFingerprint } from "../../../../memory/fingerprint.js";
 import { enqueueMemoryJob } from "../../../../memory/jobs-store.js";
-import { memoryItems } from "../../../../memory/schema.js";
+import { memoryGraphNodes } from "../../../../memory/schema.js";
 import { clampUnitInterval } from "../../../../memory/validation.js";
 import { extractStylePatterns } from "../../../../messaging/style-analyzer.js";
 import type {
@@ -14,6 +13,12 @@ import type {
 import { truncate } from "../../../../util/truncate.js";
 import { err, getProviderConnection, ok, resolveProvider } from "./shared.js";
 
+/** Map legacy caller kinds to valid MemoryType values. */
+const KIND_TO_MEMORY_TYPE: Record<string, string> = {
+  style: "behavioral",
+  relationship: "semantic",
+};
+
 function upsertMemoryItem(opts: {
   kind: string;
   subject: string;
@@ -23,58 +28,60 @@ function upsertMemoryItem(opts: {
 }): void {
   const db = getDb();
   const now = Date.now();
-  const fingerprint = computeMemoryFingerprint(
-    opts.scopeId,
-    opts.kind,
-    opts.subject,
-    opts.statement,
-  );
+  const content = `${opts.subject}\n${opts.statement}`;
 
   const existing = db
     .select()
-    .from(memoryItems)
+    .from(memoryGraphNodes)
     .where(
       and(
-        eq(memoryItems.fingerprint, fingerprint),
-        eq(memoryItems.scopeId, opts.scopeId),
+        eq(memoryGraphNodes.content, content),
+        eq(memoryGraphNodes.scopeId, opts.scopeId),
+        sql`${memoryGraphNodes.fidelity} != 'gone'`,
       ),
     )
     .get();
 
   if (existing) {
-    db.update(memoryItems)
+    db.update(memoryGraphNodes)
       .set({
-        statement: opts.statement,
-        status: "active",
-        importance: clampUnitInterval(
-          Math.max(existing.importance ?? 0, opts.importance),
+        content,
+        type: KIND_TO_MEMORY_TYPE[opts.kind] ?? opts.kind,
+        fidelity: "vivid",
+        significance: clampUnitInterval(
+          Math.max(existing.significance ?? 0, opts.importance),
         ),
-        lastSeenAt: now,
-        sourceType: existing.sourceType === "tool" ? "tool" : "extraction",
+        lastAccessed: now,
+        sourceType: existing.sourceType === "direct" ? "direct" : "inferred",
       })
-      .where(eq(memoryItems.id, existing.id))
+      .where(eq(memoryGraphNodes.id, existing.id))
       .run();
-    enqueueMemoryJob("embed_item", { itemId: existing.id });
+    enqueueMemoryJob("embed_graph_node", { nodeId: existing.id });
   } else {
     const id = uuid();
-    db.insert(memoryItems)
+    db.insert(memoryGraphNodes)
       .values({
         id,
-        kind: opts.kind,
-        subject: opts.subject,
-        statement: opts.statement,
-        status: "active",
+        content,
+        type: KIND_TO_MEMORY_TYPE[opts.kind] ?? opts.kind,
+        created: now,
+        lastAccessed: now,
+        lastConsolidated: now,
+        emotionalCharge: '{"valence":0,"intensity":0.1,"decayCurve":"linear","decayRate":0.05,"originalIntensity":0.1}',
+        fidelity: "vivid",
         confidence: 0.8,
-        importance: clampUnitInterval(opts.importance),
-        fingerprint,
-        sourceType: "extraction",
+        significance: clampUnitInterval(opts.importance),
+        stability: 14,
+        reinforcementCount: 0,
+        lastReinforced: now,
+        sourceConversations: "[]",
+        sourceType: "inferred",
+        narrativeRole: null,
+        partOfStory: null,
         scopeId: opts.scopeId,
-        firstSeenAt: now,
-        lastSeenAt: now,
-        lastUsedAt: null,
       })
       .run();
-    enqueueMemoryJob("embed_item", { itemId: id });
+    enqueueMemoryJob("embed_graph_node", { nodeId: id });
   }
 }
 

package/src/config/bundled-skills/outlook/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: outlook
+description: Archive, categorize, draft, unsubscribe, and manage Outlook email
+compatibility: "Designed for Vellum personal assistants"
+metadata:
+  emoji: "\U0001F4E7"
+  vellum:
+    display-name: "Outlook"
+---
+
+This skill provides Outlook-specific tools beyond the shared **messaging** skill. For cross-platform messaging (send, read, search, reply), use the messaging skill. Outlook tools depend on the messaging skill's provider infrastructure - load messaging first if Outlook is not yet connected.
+
+## Tool Reference
+
+| Tool | Description |
+| --- | --- |
+| `outlook_attachments` | List and download email attachments |
+| `outlook_trash` | Move messages to Deleted Items |
+| `outlook_categories` | Manage message categories (add, remove, list available) |
+| `outlook_follow_up` | Track messages with Outlook's native flag system |
+| `outlook_draft` | Create email drafts in the Drafts folder (including reply drafts) |
+| `outlook_send_draft` | Send an existing draft (high-risk - requires explicit user confirmation) |
+| `outlook_forward` | Create forward drafts, preserving attachments |
+| `outlook_unsubscribe` | Unsubscribe from mailing lists via List-Unsubscribe header |
+| `outlook_sender_digest` | Scan inbox and group messages by sender for declutter workflows |
+| `outlook_outreach_scan` | Identify cold outreach senders (no List-Unsubscribe header) |
+| `outlook_rules` | Create, list, and delete server-side inbox message rules |
+| `outlook_vacation` | Get, enable, or disable auto-reply (out-of-office) settings |
+
+All tools above are Outlook-specific. For shared operations (send, read, search, reply, archive), use `messaging_send`, `messaging_search`, etc. from the messaging skill.
+
+## Email Routing Priority
+
+When the user mentions "email" - sending, reading, checking, decluttering, drafting, or anything else - **always default to the user's own email (Outlook)** unless they explicitly ask about the assistant's own email address (e.g., "set up your email", "send from your address", "check your inbox"). The vast majority of email requests are about the user's Outlook, not the assistant's AgentMail address.
+
+Do not offer AgentMail as an option or mention it unless the user specifically asks. If Outlook is not connected, guide them through Outlook setup - do not suggest AgentMail as an alternative.
+
+## Communication Style
+
+- **Be action-oriented.** When the user asks to do something ("declutter", "check my email"), start doing it immediately. Don't ask for permission to read their inbox - that's obviously what they want.
+- **Keep it human.** Never mention OAuth, tokens, APIs, sandboxes, credential proxies, or other technical internals. If something isn't working, say "Outlook needs to be reconnected" - not "the OAuth2 access token for outlook has expired."
+- **Show progress.** When running a tool that scans many emails, tell the user what you're doing: "Scanning your inbox for clutter..." Don't go silent.
+- **Be brief and warm.** One or two sentences per update is plenty. Don't over-explain what you're about to do - just do it and narrate lightly.
+
+## Error Recovery
+
+When an Outlook tool fails with a token or authorization error:
+
+1. **Try to reconnect silently.** Call `assistant oauth ping outlook`. This often resolves expired tokens automatically.
+2. **If reconnection fails, go straight to setup.** Don't present options, ask which route the user prefers, or explain what went wrong technically. Just tell the user briefly (e.g., "Outlook needs to be reconnected - let me set that up") and immediately follow the connection setup flow for Outlook. The user came to you to get something done, not to troubleshoot OAuth - make it seamless.
+3. **Never try alternative approaches.** Don't use bash, curl, browser automation, or any workaround. If the Outlook tools can't do it, the reconnection flow is the answer.
+4. **Never expose error details.** The user doesn't need to see error messages about tokens, OAuth, or API failures. Translate errors into plain language.
+
+## Drafting vs Sending (Outlook)
+
+Outlook uses a **draft-first workflow** where appropriate:
+
+- `messaging_send` (Outlook) sends messages directly via the Graph API.
+- `outlook_draft` creates a draft in the Outlook Drafts folder for user review before sending.
+- `outlook_forward` creates a forward draft, preserving attachments.
+
+When the user asks to "draft" or "compose" an email, use `outlook_draft`. When they say "send", use `messaging_send`. If ambiguous, prefer drafting so the user can review first.
+
+## Differences from Gmail
+
+Outlook and Gmail have different organizational models. Keep these distinctions in mind:
+
+| Concept | Gmail | Outlook |
+| --- | --- | --- |
+| **Organization** | Labels (multiple per message) | Folders (one per message) + Categories (multiple per message) |
+| **Categorization** | Labels serve dual purpose | Categories are color-coded tags independent of folder location |
+| **Follow-up** | Label-based tracking | Native flag system (`flagged`, `complete`, `notFlagged`) |
+| **Inbox rules** | Gmail filters | Outlook inbox rules (server-side) |
+| **Archive** | Remove INBOX label | Move to Archive folder |
+
+### Categories
+
+Categories are Outlook's tagging system for organizing messages. Unlike Gmail labels, categories are independent of folder structure - a message can be in any folder and have multiple categories. Categories are color-coded (Blue, Green, Orange, Purple, Red, Yellow, or custom names). Use categories to tag and organize messages without moving them between folders.
+
+### Follow-up Flags
+
+Outlook uses a native flag system for follow-up tracking:
+
+- `flagged` - message is marked for follow-up
+- `complete` - follow-up is done
+- `notFlagged` - no follow-up tracking
+
+This replaces Gmail's label-based follow-up approach. Use the Outlook flag system directly rather than creating custom folder-based workarounds.
+
+### Inbox Rules vs Gmail Filters
+
+Outlook inbox rules (`outlook_rules`) run server-side and support conditions like sender, subject, body keywords, and importance level. Actions include moving to folders, categorizing, flagging, forwarding, and deleting. Gmail filters (`gmail_filters`) are similar but use Gmail's query syntax and label-based actions. When a user asks to "filter" or "auto-sort" email, use `outlook_rules` - do not try to replicate Gmail's label-based filtering with Outlook folders.
+
+### Folders vs Labels
+
+Gmail uses labels - a message can have multiple labels and removing the INBOX label archives it. Outlook uses folders - a message lives in exactly one folder at a time. Moving a message to Archive removes it from Inbox. To tag a message with multiple categories without moving it, use `outlook_categories`. Do not create folder hierarchies to simulate Gmail's multi-label system.
+
+## Email Decluttering
+
+When a user asks to declutter, clean up, or organize their email - start scanning immediately. Don't ask what kind of cleanup they want or request permission to read their inbox. Go straight to scanning - but once results are ready, always show them via `ui_show` and let the user choose actions before archiving or unsubscribing.
+
+**CRITICAL**: Never call `messaging_archive_by_sender`, `outlook_unsubscribe`, or similar bulk actions unless the user has clicked an action button on the table for that specific batch. Each batch of results requires its own explicit user confirmation via the table UI. If the user says "keep going" or "keep decluttering," that means scan and present a new table - NOT auto-archive. Previous batch approvals do not carry forward, but **deselections DO carry forward**: when the user deselects senders from a cleanup table, the system records those deselections as user preferences. Before building the next cleanup table, check `<dynamic-user-profile>` for previously deselected senders and exclude them from future cleanup tables - the user already indicated they want to keep those.
+
+### Workflow
+
+1. **Scan**: Call `outlook_sender_digest`. Default query targets promotional messages from the last 90 days.
+2. **Present**: Show results as a `ui_show` table with `selectionMode: "multiple"`:
+   - **Columns (exactly 3)**: Sender, Emails Found, Unsub?
+     - **Unsub? cell values**: Use rich cell format: `{ "text": "Yes", "icon": "checkmark.circle.fill", "iconColor": "success" }` when `has_unsubscribe` is true, `{ "text": "No", "icon": "minus.circle", "iconColor": "muted" }` when false.
+   - **Pre-select all rows** (`selected: true`) - users deselect what they want to keep
+   - **Caption**: Include two parts separated by a newline: (1) data scope, e.g. "Newsletters, notifications, and outreach from last 90 days. Deselect anything you want to keep." (adjusted to match the query used), and (2) the Unsub? column legend: "Unsub? - \"Yes\" means these emails contain an unsubscribe link, so I can opt you out automatically. \"No\" means no unsubscribe link was found - these will be archived but you may continue receiving them."
+   - **Action buttons (exactly 2)**: "Archive & Unsubscribe" (primary), "Archive Only" (secondary). **NEVER offer Delete, Trash, or any destructive action.**
+3. **Wait for user action**: Stop and wait. Do NOT proceed to archiving or unsubscribing until the user clicks one of the action buttons on the table. When the user clicks an action button:
+   - **Dismiss the table immediately** with `ui_dismiss` - it collapses to a completion chip
+   - **Show a `task_progress` card** with steps for each phase (e.g., "Archiving 89 senders (2,400 emails)", "Unsubscribing from 72 senders"). Update each step from `in_progress` to `completed` as each phase finishes.
+   - When all senders are processed, set the progress card's `status: "completed"`.
+4. **Act on selection** - batch, don't loop:
+   - **Archive all at once**: Call `messaging_archive_by_sender` **once** with `scan_id` + **all** selected senders' `id` values in the `sender_ids` array. The tool resolves message IDs server-side and batches the API calls internally - never loop sender-by-sender.
+   - **Unsubscribe in bulk**: If the action is "Archive & Unsubscribe", call `outlook_unsubscribe` for each sender that has `has_unsubscribe: true` - but emit **all** unsubscribe tool calls in a **single assistant response** (parallel tool use) rather than one-at-a-time across separate turns.
+5. **Accurate summary**: The scan counts are exact - the `message_count` shown in the table matches the number of messages archived. Format: "Cleaned up [total_archived] emails from [sender_count] senders. Unsubscribed from [unsub_count]."
+6. **Ongoing protection offer**: After reporting results, offer inbox rules:
+   - "Want me to set up inbox rules so future emails from these senders skip your inbox?"
+   - If yes, call `outlook_rules` with `action: "create"` for each sender.
+   - Then offer a recurring declutter schedule: "Want me to scan for new clutter monthly?" If yes, use `schedule_create` to set up a monthly declutter check.
+
+### Edge Cases
+
+- **Zero results**: Tell the user "No newsletter emails found" and suggest broadening the query (e.g. extending the date range)
+- **Unsubscribe failures**: Report per-sender success/failure; the `outlook_unsubscribe` tool handles edge cases
+- **Truncation handling**: If `truncated` is true, the top senders are still captured - don't offer to scan more. Tell the user: "Scanned [N] messages - here are your top senders."
+- **Time budget exceeded**: If the scan returns `time_budget_exceeded: true`, present whatever results were collected. Do not retry or continue - the partial results are useful as-is.
+
+## Scan ID
+
+Scan tools (`outlook_sender_digest`, `outlook_outreach_scan`) return a `scan_id` that references message IDs stored server-side. This keeps thousands of message IDs out of the conversation context.
+
+- Pass `scan_id` + `sender_ids` to `messaging_archive_by_sender` instead of `message_ids`
+- Scan results expire after **30 minutes** - if archiving fails with an expiration error, re-run the scan
+- Raw `message_ids` still work as a fallback for non-scan workflows
+
+## Batch Operations
+
+- `messaging_archive_by_sender` supports `scan_id` + `sender_ids` (preferred for declutter workflows) or raw `message_ids`.
+- First scan to get a `scan_id`, then use `messaging_archive_by_sender` to batch-archive by sender.
+- Always confirm with the user before batch operations on large numbers of messages.
+
+## Common Workflows
+
+### Declutter Inbox
+
+1. Call `outlook_sender_digest` to scan for newsletters and promotions
+2. Present results via `ui_show` table (see Email Decluttering section for full workflow)
+3. Wait for user to select senders and click an action button
+4. Call `messaging_archive_by_sender` with `scan_id` + selected `sender_ids`
+5. If "Archive & Unsubscribe", also call `outlook_unsubscribe` for senders with `has_unsubscribe: true`
+6. Offer to create inbox rules for ongoing protection
+
+### Create a Mail Rule
+
+1. User says "auto-archive emails from newsletters@example.com"
+2. Call `outlook_rules` with `action: "create"`, specifying the sender condition and the move-to-folder action
+3. Confirm the rule was created and explain what it does
+
+### Set Vacation Auto-Reply
+
+1. User says "set my out-of-office for next week"
+2. Call `outlook_vacation` with `action: "enable"`, the date range, and the auto-reply message
+3. Confirm the auto-reply is active and when it expires
+
+### Manage Follow-ups
+
+1. User says "flag this email for follow-up" - call `outlook_follow_up` with `action: "track"` and the message ID
+2. User says "what emails am I tracking?" - call `outlook_follow_up` with `action: "list"` to show all flagged messages
+3. User says "mark that as done" - call `outlook_follow_up` with `action: "complete"` to clear the flag
+
+### Identify Cold Outreach
+
+1. Call `outlook_outreach_scan` to find senders without unsubscribe headers
+2. Present results for review - these are likely cold outreach or unsolicited emails
+3. User can choose to archive, create rules to block, or ignore
+
+## Confidence Scores
+
+Medium and high risk tools require a confidence score between 0 and 1:
+
+- **0.9-1.0**: User explicitly requested this exact action
+- **0.7-0.8**: Action is strongly implied by context
+- **0.5-0.6**: Reasonable inference but some ambiguity
+- **Below 0.5**: Ask the user to confirm before proceeding