@aitne-sh/aitne 0.1.7 → 0.1.9

package/agent-assets/skills/mail/SKILL.delegated.claude.md

@@ -1,6 +1,6 @@
 ---
 name: mail
-description: Load when the task touches Gmail and Gmail is in cross-backend delegated mode (DM session is Claude Code; `delegatedBackend` is non-Claude). Gmail accounts route through `POST /api/integrations/gmail/exec`; non-Gmail accounts (IMAP/Outlook/iCloud/Yahoo) keep the direct-mode `/api/mail/*` surface.
+description: Load when the task touches Gmail AND Gmail is cross-backend delegated from a Claude DM session (`delegatedBackend` is non-Claude). Gmail routes through `POST /api/integrations/gmail/exec`; non-Gmail accounts (IMAP/Outlook/iCloud/Yahoo) keep `/api/mail/*`.
 allowed-tools:
   - Bash(curl *)
   - Read
@@ -90,7 +90,7 @@ Response shape on success:
 `outputSchema` is **required** — the subprocess emits exactly one JSON
 object as its final message and the daemon validates it. Schemas
 larger than 4 KB are rejected (`schema_too_large`). Caps default to
-`maxToolCalls=7`, `maxBudgetUsd=0.05`, `timeoutMs=60000` — bump them via
+`maxToolCalls=8`, `maxBudgetUsd=0.05`, `timeoutMs=60000` — bump them via
 the request body up to the hard caps (15 / 0.50 / 300000) when a task
 genuinely needs more.
 
@@ -206,10 +206,18 @@ curl -s -X POST http://localhost:8321/api/integrations/gmail/exec \
 
 The setup wizard pre-populates `gmail.deniedTools` with the connector's
 destructive defaults (send / batch label mutate / etc.). `/exec`
-honors the deny list: a task that requires a denied tool surfaces as
-`tool_unavailable` (not 403) — the subprocess reports the gap and the
-daemon returns 502. Surface that to the user and ask whether to lift
-the deny before retrying.
+honors the deny list, and the response distinguishes two cases:
+
+- **Every connector tool is denied** → `403 denied_tool`. There is no
+  surface to plan against, so the daemon rejects the task up front
+  without spawning the subprocess.
+- **The connector still has usable tools but the specific tool a planned
+  task needs is denied (or no tool fits)** → `502 tool_unavailable`. The
+  subprocess plans, finds no permitted tool for the intent, and reports
+  the gap.
+
+In both cases, surface that to the user and ask whether to lift the
+relevant deny before retrying.
 
 ## Decision rules
 
@@ -236,6 +244,7 @@ Discriminator: `body.mode === "delegated"`.
 | 400 | `validation_error` / `schema_too_large` | no | Fix the request body. |
 | 409 | `mode_mismatch` | no | Gmail isn't delegated, OR your DM backend matches `delegatedBackend`. Re-read `integrations.md` and stop. |
 | 409 | `precondition` | no | Mode/backend was flipped while the call queued. Re-read `integrations.md` and re-plan. |
+| 403 | `denied_tool` | no | Every tool in the connector is denied — task mode has no surface to plan against. Surface to the user and ask whether to lift the deny. |
 | 429 | `task_quota_exhausted` | no | Daily cap reached; wait or surface. |
 | 502 | `parse_error` / `schema_violation` | no (daemon already retried once) | Consider a simpler schema. |
 | 502 | `tool_unavailable` | no | No connector tool fits the intent. Surface the gap to the user. |

package/agent-assets/skills/mail/SKILL.delegated.codex.md

@@ -1,6 +1,6 @@
 ---
 name: mail
-description: Load when the task touches Gmail and Gmail is in cross-backend delegated mode (DM session is Codex; `delegatedBackend` is non-Codex). Gmail accounts route through `POST /api/integrations/gmail/exec`; non-Gmail accounts (IMAP/Outlook/iCloud/Yahoo) keep the direct-mode `/api/mail/*` surface.
+description: Load when the task touches Gmail AND Gmail is cross-backend delegated from a Codex CLI DM session (`delegatedBackend` is non-Codex). Gmail routes through `POST /api/integrations/gmail/exec`; non-Gmail accounts (IMAP/Outlook/iCloud/Yahoo) keep `/api/mail/*`.
 ---
 
 # Mail (delegated, cross-backend)
@@ -85,7 +85,7 @@ Response shape on success:
 `outputSchema` is **required** — the subprocess emits exactly one JSON
 object as its final message and the daemon validates it. Schemas
 larger than 4 KB are rejected (`schema_too_large`). Caps default to
-`maxToolCalls=7`, `maxBudgetUsd=0.05`, `timeoutMs=60000` — bump them
+`maxToolCalls=8`, `maxBudgetUsd=0.05`, `timeoutMs=60000` — bump them
 via the request body up to the hard caps (15 / 0.50 / 300000) when a
 task genuinely needs more.
 
@@ -193,9 +193,12 @@ curl -sS -X POST http://localhost:8321/api/integrations/gmail/exec \
 ## Default deny floor
 
 The setup wizard pre-populates `gmail.deniedTools` with the connector's
-destructive defaults. `/exec` honors the deny list: a task that
-requires a denied tool surfaces as `tool_unavailable` — surface that
-to the user and ask whether to lift the deny before retrying.
+destructive defaults. `/exec` honors the deny list, distinguishing two
+cases: if **every** connector tool is denied → `403 denied_tool` (no
+surface to plan against, rejected up front); if usable tools remain but
+the specific tool a planned task needs is denied (or no tool fits) →
+`502 tool_unavailable`. In both cases, surface that to the user and ask
+whether to lift the relevant deny before retrying.
 
 ## Decision rules
 
@@ -218,6 +221,7 @@ Discriminator: `body.mode === "delegated"`.
 | 400 | `validation_error` / `schema_too_large` | no | Fix the request body. |
 | 409 | `mode_mismatch` | no | Gmail isn't delegated, OR your DM backend matches `delegatedBackend`. Re-read `integrations.md` and stop. |
 | 409 | `precondition` | no | Mode/backend was flipped during queue wait. Re-read `integrations.md` and re-plan. |
+| 403 | `denied_tool` | no | Every tool in the connector is denied — no surface to plan against. Surface to the user and ask whether to lift the deny. |
 | 429 | `task_quota_exhausted` | no | Daily cap reached; wait or surface. |
 | 502 | `parse_error` / `schema_violation` | no (daemon already retried once) | Consider a simpler schema. |
 | 502 | `tool_unavailable` | no | No connector tool fits. Surface the gap. |

package/agent-assets/skills/mail/SKILL.delegated.gemini.md

@@ -1,6 +1,6 @@
 ---
 name: mail
-description: Load when the task touches Gmail and Gmail is in cross-backend delegated mode (DM session is Gemini; `delegatedBackend` is non-Gemini). Gmail accounts route through `POST /api/integrations/gmail/exec`; non-Gmail accounts (IMAP/Outlook/iCloud/Yahoo) keep the direct-mode `/api/mail/*` surface.
+description: Load when the task touches Gmail AND Gmail is cross-backend delegated from a Gemini CLI DM session (`delegatedBackend` is non-Gemini). Gmail routes through `POST /api/integrations/gmail/exec`; non-Gmail accounts (IMAP/Outlook/iCloud/Yahoo) keep `/api/mail/*`.
 ---
 
 # Mail (delegated, cross-backend)
@@ -83,7 +83,7 @@ Response shape on success:
 `outputSchema` is **required** — the subprocess emits exactly one JSON
 object as its final message and the daemon validates it. Schemas
 larger than 4 KB are rejected (`schema_too_large`). Caps default to
-`maxToolCalls=7`, `maxBudgetUsd=0.05`, `timeoutMs=60000` — bump them
+`maxToolCalls=8`, `maxBudgetUsd=0.05`, `timeoutMs=60000` — bump them
 via the request body up to the hard caps (15 / 0.50 / 300000) when a
 task genuinely needs more.
 
@@ -187,9 +187,12 @@ curl -sS -X POST http://localhost:8321/api/integrations/gmail/exec \
 ## Default deny floor
 
 The setup wizard pre-populates `gmail.deniedTools` with the connector's
-destructive defaults. `/exec` honors the deny list: a task that
-requires a denied tool surfaces as `tool_unavailable` — surface that
-to the user and ask whether to lift the deny before retrying.
+destructive defaults. `/exec` honors the deny list, distinguishing two
+cases: if **every** connector tool is denied → `403 denied_tool` (no
+surface to plan against, rejected up front); if usable tools remain but
+the specific tool a planned task needs is denied (or no tool fits) →
+`502 tool_unavailable`. In both cases, surface that to the user and ask
+whether to lift the relevant deny before retrying.
 
 ## Decision rules
 
@@ -212,6 +215,7 @@ Discriminator: `body.mode === "delegated"`.
 | 400 | `validation_error` / `schema_too_large` | no | Fix the request body. |
 | 409 | `mode_mismatch` | no | Gmail isn't delegated, OR your DM backend matches `delegatedBackend`. Re-read `integrations.md` and stop. |
 | 409 | `precondition` | no | Mode/backend was flipped during queue wait. Re-read `integrations.md` and re-plan. |
+| 403 | `denied_tool` | no | Every tool in the connector is denied — no surface to plan against. Surface to the user and ask whether to lift the deny. |
 | 429 | `task_quota_exhausted` | no | Daily cap reached; wait or surface. |
 | 502 | `parse_error` / `schema_violation` | no (daemon already retried once) | Consider a simpler schema. |
 | 502 | `tool_unavailable` | no | No connector tool fits. Surface the gap. |

package/agent-assets/skills/mail/SKILL.md

@@ -220,122 +220,17 @@ curl -s "http://localhost:8321/api/mail/ACCT/messages/MSG/body?format=raw&chunk=
 
 ## 6. Worked examples
 
-### Reply with context
-```bash
-# 1. Find the thread — start local.
-curl -s "http://localhost:8321/api/mail/search?q=from:alice+proposal&limit=5"
-# → pick the hit, note accountId + providerMsgId.
-
-# 2. Fetch the thread.
-curl -s "http://localhost:8321/api/mail/acct-1/threads/THREAD_ID"
-# → last message has rfc822MsgId, references[], providerMsgId.
-
-# 3. Create a draft threaded to it. Drafts are Autonomous tier.
-curl -sX POST "http://localhost:8321/api/mail/acct-1/drafts" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "to": ["alice@example.com"],
-    "subject": "Re: Proposal",
-    "textBody": "Thanks Alice — ...",
-    "reply": {
-      "inReplyToRfc822Id": "<abc@mail.example.com>",
-      "references": ["<root@mail.example.com>", "<abc@mail.example.com>"],
-      "providerThreadId": "THREAD_ID",
-      "parentProviderMsgId": "PARENT_MSG_ID"
-    }
-  }'
-```
+Three direct-mode worked examples — reply with context, file a
+message (read + tag + archive), cross-account search → pick account
+→ send — are in the examples reference below. The delegated /
+native variants of this skill carry their own examples.
 
-### File a message (read + tag + archive)
-```bash
-curl -sX POST "http://localhost:8321/api/mail/acct-1/messages/MSG/read" \
-  -d '{"read": true}'
-curl -sX POST "http://localhost:8321/api/mail/acct-1/messages/MSG/tags" \
-  -d '{"add": ["followup"], "remove": []}'
-curl -sX POST "http://localhost:8321/api/mail/acct-1/messages/MSG/archive"
-```
-On IMAP, confirm `followup` is in `GET /mail/:acct/tags` `.userDefined`
-first — unknown keywords get dropped.
-
-### Cross-account search → pick account → send
-```bash
-# Find recipient's earlier emails across all accounts.
-curl -s "http://localhost:8321/api/mail/search?q=from:bob@acme.com&limit=10"
-# → hits carry accountId. Use whichever account received the earlier thread
-#   so the reply comes from a familiar address.
-
-curl -sX POST "http://localhost:8321/api/mail/acct-2/messages/send" \
-  -H "Content-Type: application/json" \
-  -d '{"to": ["bob@acme.com"], "subject": "...", "textBody": "..."}'
-```
+{{> ref:examples }}
 
 ## 7. API reference
 
-Base URL `http://localhost:8321`. `ACCT` = accountId from `accounts.md`.
-
-### Accounts
-```bash
-curl -s "http://localhost:8321/api/mail/accounts?active=1"
-# → { accounts: [{ id, kind, email, label?, authStatus, idleEnabled, active, createdAt }, ...] }
-```
-
-### Search (local FTS5, cross-account)
-```bash
-curl -s "http://localhost:8321/api/mail/search?q=...&limit=50&accountId=ACCT"
-# → { results: [{ accountId, providerMsgId, subject, snippet, receivedAtUtc,
-#                 from: { email } | null, isRead }], count, query }
-```
-
-### Read
-```bash
-# List / search via the provider.
-curl -s "http://localhost:8321/api/mail/ACCT/messages?q=is:unread&limit=20"
-# → { messages: [{ providerMsgId, threadId, from, subject, snippet,
-#                  receivedAtUtc, isRead, flags, hasAttachment }] }
-
-curl -s "http://localhost:8321/api/mail/ACCT/messages/MSG_ID"
-# → { message: { ..., body: { text, html }, attachments: [...] } }
-
-curl -s "http://localhost:8321/api/mail/ACCT/threads/THREAD_ID"
-# → { thread: { threadId, messages: [...], status: "full"|"partial", missingAncestors? } }
-
-curl -s "http://localhost:8321/api/mail/ACCT/folders"
-curl -s "http://localhost:8321/api/mail/ACCT/tags"
-```
-
-### Send / draft
-```bash
-# Direct send — Autonomous; rejected with 403 when the user has denied
-# the send tool. Call /api/notify yourself if the user should know.
-curl -sX POST "http://localhost:8321/api/mail/ACCT/messages/send" \
-  -H "Content-Type: application/json" \
-  -d '{"to": [...], "subject": "...", "textBody": "...", "reply"?: {...}}'
-# → { result: { id, isDraft: false, rfc822MsgId?, warnings? } }
-
-# Draft CRUD — Autonomous tier.
-curl -s "http://localhost:8321/api/mail/ACCT/drafts"
-curl -s "http://localhost:8321/api/mail/ACCT/drafts/DRAFT_ID"
-curl -sX POST   "http://localhost:8321/api/mail/ACCT/drafts" -d '{...}'
-curl -sX PATCH  "http://localhost:8321/api/mail/ACCT/drafts/DRAFT_ID" -d '{...}'
-# PATCH response: { status, id, warnings? }
-# - On Outlook, `warnings: ["reply_threading_immutable_after_create"]` if
-#   `reply` was supplied — reply headers are fixed at createDraft time.
-curl -sX DELETE "http://localhost:8321/api/mail/ACCT/drafts/DRAFT_ID"
-curl -sX POST   "http://localhost:8321/api/mail/ACCT/drafts/DRAFT_ID/send"
-```
+Direct-mode `/api/mail/*` surface — accounts, search, read,
+send / draft, modify / move, health — is in the api reference below.
+`ACCT` is the `accountId` resolved per §1.
 
-### Modify / move
-```bash
-curl -sX POST "http://localhost:8321/api/mail/ACCT/messages/MSG_ID/read"    -d '{"read": true}'
-curl -sX POST "http://localhost:8321/api/mail/ACCT/messages/MSG_ID/tags"    -d '{"add": ["Starred"], "remove": []}'
-curl -sX POST "http://localhost:8321/api/mail/ACCT/messages/MSG_ID/trash"
-curl -sX POST "http://localhost:8321/api/mail/ACCT/messages/MSG_ID/untrash"
-curl -sX POST "http://localhost:8321/api/mail/ACCT/messages/MSG_ID/archive"
-```
-
-### Health
-```bash
-curl -s "http://localhost:8321/api/mail/ACCT/health"
-# → { accountId, lastPollAtUtc, lastError, lastErrorAtUtc,
-#     consecutiveErrorCount, idleFallbackUntilUtc }
-```
+{{> ref:api }}

package/agent-assets/skills/mail/SKILL.native.claude.md

@@ -1,6 +1,6 @@
 ---
 name: mail
-description: Load when the task touches Gmail and Gmail is in native mode bound to Claude (`nativeBackend === "claude"`). Use the in-session Gmail connector your harness exposes directly; the daemon does not proxy Gmail. Non-Gmail accounts (IMAP/Outlook/iCloud/Yahoo) keep the direct `/api/mail/*` surface.
+description: Load when the task touches Gmail AND Gmail is in native mode bound to Claude (`nativeBackend === "claude"`). Use the in-session Gmail connector directly; the daemon does not proxy Gmail. Non-Gmail accounts (IMAP/Outlook/iCloud/Yahoo) keep `/api/mail/*`.
 allowed-tools:
   - Bash(curl *)
   - Read

package/agent-assets/skills/mail/SKILL.native.codex.md

@@ -1,6 +1,6 @@
 ---
 name: mail
-description: Load when the task touches Gmail and Gmail is in native mode bound to Codex (`nativeBackend === "codex"`). Use the in-session Gmail connector your Codex harness exposes directly; the daemon does not proxy Gmail. Non-Gmail accounts (IMAP/Outlook/iCloud/Yahoo) keep the direct `/api/mail/*` surface.
+description: Load when the task touches Gmail AND Gmail is in native mode bound to Codex (`nativeBackend === "codex"`). Use the Gmail connector your Codex harness exposes directly; the daemon does not proxy Gmail. Non-Gmail accounts (IMAP/Outlook/iCloud/Yahoo) keep `/api/mail/*`.
 allowed-tools:
   - Bash(curl *)
   - Read

package/agent-assets/skills/mail/SKILL.native.gemini.md

@@ -1,6 +1,6 @@
 ---
 name: mail
-description: Load when the task touches Gmail and Gmail is in native mode bound to Gemini (`nativeBackend === "gemini"`). Use the in-session Gmail connector your Gemini harness exposes directly; the daemon does not proxy Gmail. Non-Gmail accounts (IMAP/Outlook/iCloud/Yahoo) keep the direct `/api/mail/*` surface.
+description: Load when the task touches Gmail AND Gmail is in native mode bound to Gemini (`nativeBackend === "gemini"`). Use the Gmail connector your Gemini harness exposes directly; the daemon does not proxy Gmail. Non-Gmail accounts (IMAP/Outlook/iCloud/Yahoo) keep `/api/mail/*`.
 allowed-tools:
   - Bash(curl *)
   - Read

package/agent-assets/skills/mail/references/api.md

@@ -0,0 +1,110 @@
+---
+kind: reference
+name: api
+description: Direct-mode /api/mail/* reference — accounts, search, read, send/draft, modify/move, health. ACCT is the accountId resolved from accounts.md.
+---
+
+# /api/mail/* — Direct-mode reference
+
+Base URL `http://localhost:8321`. `ACCT` = `accountId` from
+`accounts.md` (resolved per §1 of the skill body).
+
+Cross-cutting rules (apply to every endpoint below):
+
+- The per-account `/api/mail/:acct/*` gate returns `410` for the
+  account's `kind` when Gmail / Outlook are in delegated or native
+  mode. Re-check `integrations.md` and switch to the matching
+  delegated / native skill body instead — do not retry through
+  `/api/mail/*`.
+- The trash / untrash / archive / send endpoints are Autonomous but
+  still respect the user's `deniedTools` for delegated-mode
+  connector tools (no equivalent gate in direct mode today).
+
+## Accounts
+
+```bash
+curl -s "http://localhost:8321/api/mail/accounts?active=1"
+# → { accounts: [{ id, kind, email, label?, authStatus, idleEnabled, active, createdAt }, ...] }
+```
+
+Always pass `?active=1` for recovery from a stale `accounts.md` —
+the unfiltered form returns dormant / unhealthy rows that every
+operation will reject.
+
+## Search (local FTS5, cross-account)
+
+```bash
+curl -s "http://localhost:8321/api/mail/search?q=...&limit=50&accountId=ACCT"
+# → { results: [{ accountId, providerMsgId, subject, snippet, receivedAtUtc,
+#                 from: { email } | null, isRead }], count, query }
+```
+
+`accountId` is optional — omit to search across every active account.
+The local index is zero provider round-trips, so prefer it for "find
+emails about X / from Y / last month" queries before falling back to
+per-account provider search.
+
+## Read
+
+```bash
+# List / search via the provider.
+curl -s "http://localhost:8321/api/mail/ACCT/messages?q=is:unread&limit=20"
+# → { messages: [{ providerMsgId, threadId, from, subject, snippet,
+#                  receivedAtUtc, isRead, flags, hasAttachment }] }
+
+curl -s "http://localhost:8321/api/mail/ACCT/messages/MSG_ID"
+# → { message: { ..., body: { text, html }, attachments: [...] } }
+
+curl -s "http://localhost:8321/api/mail/ACCT/threads/THREAD_ID"
+# → { thread: { threadId, messages: [...], status: "full"|"partial", missingAncestors? } }
+
+curl -s "http://localhost:8321/api/mail/ACCT/folders"
+curl -s "http://localhost:8321/api/mail/ACCT/tags"
+```
+
+For body understanding on large messages, use the extracted-body
+endpoint (`/messages/MSG/body?format=extracted&maxChars=…&chunk=…`)
+documented in §"Reading message bodies — use extracted chunks" of the
+skill body.
+
+## Send / draft
+
+```bash
+# Direct send — Autonomous. Direct mode has NO deny-tool gate: this
+# route validates the body and sends unconditionally (no 403/denied_tool
+# path; `deniedTools` only applies to delegated-mode connector tools).
+# Call /api/notify yourself if the user should know.
+curl -sX POST "http://localhost:8321/api/mail/ACCT/messages/send" \
+  -H "Content-Type: application/json" \
+  -d '{"to": [...], "subject": "...", "textBody": "...", "reply"?: {...}}'
+# → { result: { id, isDraft: false, rfc822MsgId?, warnings? } }
+
+# Draft CRUD — Autonomous tier.
+curl -s "http://localhost:8321/api/mail/ACCT/drafts"
+curl -s "http://localhost:8321/api/mail/ACCT/drafts/DRAFT_ID"
+curl -sX POST   "http://localhost:8321/api/mail/ACCT/drafts" -d '{...}'
+curl -sX PATCH  "http://localhost:8321/api/mail/ACCT/drafts/DRAFT_ID" -d '{...}'
+# PATCH response: { status, id, warnings? }
+# - On Outlook, `warnings: ["reply_threading_immutable_after_create"]` if
+#   `reply` was supplied — reply headers are fixed at createDraft time.
+curl -sX DELETE "http://localhost:8321/api/mail/ACCT/drafts/DRAFT_ID"
+curl -sX POST   "http://localhost:8321/api/mail/ACCT/drafts/DRAFT_ID/send"
+```
+
+## Modify / move
+
+```bash
+curl -sX POST "http://localhost:8321/api/mail/ACCT/messages/MSG_ID/read"    -d '{"read": true}'
+curl -sX POST "http://localhost:8321/api/mail/ACCT/messages/MSG_ID/tags"    -d '{"add": ["Starred"], "remove": []}'
+curl -sX POST "http://localhost:8321/api/mail/ACCT/messages/MSG_ID/trash"
+curl -sX POST "http://localhost:8321/api/mail/ACCT/messages/MSG_ID/untrash"
+curl -sX POST "http://localhost:8321/api/mail/ACCT/messages/MSG_ID/archive"
+```
+
+## Health
+
+```bash
+curl -s "http://localhost:8321/api/mail/ACCT/health"
+# → { accountId, lastPollAtUtc, lastError, lastErrorAtUtc,
+#     consecutiveErrorCount, idleFallbackUntilUtc }
+```

package/agent-assets/skills/mail/references/examples.md

@@ -0,0 +1,70 @@
+---
+kind: reference
+name: examples
+description: Worked examples for direct-mode mail — reply with context, file a message (read + tag + archive), cross-account search → pick account → send.
+---
+
+# Worked examples (direct mode)
+
+These examples target the direct-mode `/api/mail/*` surface. The
+delegated and native variants of this skill carry their own examples
+in their own bodies (Gmail via `/api/integrations/gmail/exec`,
+Outlook via the user's MCP). Use this reference only for
+direct-mode accounts.
+
+## Reply with context
+
+```bash
+# 1. Find the thread — start local.
+curl -s "http://localhost:8321/api/mail/search?q=from:alice+proposal&limit=5"
+# → pick the hit, note accountId + providerMsgId.
+
+# 2. Fetch the thread.
+curl -s "http://localhost:8321/api/mail/acct-1/threads/THREAD_ID"
+# → last message has rfc822MsgId, references[], providerMsgId.
+
+# 3. Create a draft threaded to it. Drafts are Autonomous tier.
+curl -sX POST "http://localhost:8321/api/mail/acct-1/drafts" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "to": ["alice@example.com"],
+    "subject": "Re: Proposal",
+    "textBody": "Thanks Alice — ...",
+    "reply": {
+      "inReplyToRfc822Id": "<abc@mail.example.com>",
+      "references": ["<root@mail.example.com>", "<abc@mail.example.com>"],
+      "providerThreadId": "THREAD_ID",
+      "parentProviderMsgId": "PARENT_MSG_ID"
+    }
+  }'
+```
+
+## File a message (read + tag + archive)
+
+```bash
+curl -sX POST "http://localhost:8321/api/mail/acct-1/messages/MSG/read" \
+  -d '{"read": true}'
+curl -sX POST "http://localhost:8321/api/mail/acct-1/messages/MSG/tags" \
+  -d '{"add": ["followup"], "remove": []}'
+curl -sX POST "http://localhost:8321/api/mail/acct-1/messages/MSG/archive"
+```
+
+On IMAP, confirm `followup` is in `GET /mail/:acct/tags` `.userDefined`
+first — unknown keywords get dropped.
+
+## Cross-account search → pick account → send
+
+```bash
+# Find recipient's earlier emails across all accounts.
+curl -s "http://localhost:8321/api/mail/search?q=from:bob@acme.com&limit=10"
+# → hits carry accountId. Use whichever account received the earlier thread
+#   so the reply comes from a familiar address.
+
+curl -sX POST "http://localhost:8321/api/mail/acct-2/messages/send" \
+  -H "Content-Type: application/json" \
+  -d '{"to": ["bob@acme.com"], "subject": "...", "textBody": "..."}'
+```
+
+Prefer drafts when the message goes to someone the user has not
+recently corresponded with — the §"Send vs draft" rule in the skill
+body applies whether or not you came from a cross-account search.

package/agent-assets/skills/mail/references/providers.md

@@ -9,14 +9,14 @@ on this kind — do NOT retry; tell the user and fall back.
 
 | Operation | Gmail | Outlook | Yahoo / iCloud (IMAP) |
 |---|---|---|---|
-| Read, search, list folders | ✅ | ✅ | ✅ (ASCII; non-ASCII degrades — see §4) |
-| Direct send (`POST /messages/send`) | ✅ | ✅ | ✅ |
-| `markRead` / `tags` / `trash` | ✅ | ✅ | ✅ |
-| `archive` / `untrash` | ✅ | ✅ | ✅ |
-| Thread read (`GET /threads/:id`) | ✅ | ✅ | ⚠️ client-walked; `status: "partial"` possible |
-| Draft read (`GET /drafts`, `GET /drafts/:id`) | ✅ | ✅ | ✅ |
-| Draft write (`POST`/`PATCH`/`DELETE /drafts`, `POST /drafts/:id/send`) | ✅ | ✅ | ❌ **501** — direct `/messages/send` only |
-| Attachment download (via `/receipts/:id/file`) | ✅ | ❌ 501 | ❌ 501 |
+| Read, search, list folders | yes | yes | yes (ASCII; non-ASCII degrades — see §4) |
+| Direct send (`POST /messages/send`) | yes | yes | yes |
+| `markRead` / `tags` / `trash` | yes | yes | yes |
+| `archive` / `untrash` | yes | yes | yes |
+| Thread read (`GET /threads/:id`) | yes | yes | partial (client-walked; `status: "partial"` possible) |
+| Draft read (`GET /drafts`, `GET /drafts/:id`) | yes | yes | yes |
+| Draft write (`POST`/`PATCH`/`DELETE /drafts`, `POST /drafts/:id/send`) | yes | yes | no — **501** — direct `/messages/send` only |
+| Attachment download (via `POST /api/receipts/:id/download`) | yes | no — 501 | no — 501 |
 
 **IMAP drafts** (Yahoo / iCloud): every draft *write* returns 501. To
 queue outbound mail for a non-Gmail IMAP user, send directly via