@aitne-sh/aitne 0.1.5 → 0.1.7

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

@@ -1,12 +1,12 @@
 ---
 name: mail
-description: Load when the task touches Gmail and Gmail is in native mode bound to Claude (`nativeBackend === "claude"`). Use Claude's hosted Gmail connector 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 your harness exposes directly; the daemon does not proxy Gmail. Non-Gmail accounts (IMAP/Outlook/iCloud/Yahoo) keep the direct `/api/mail/*` surface.
 allowed-tools:
   - Bash(curl *)
   - Read
 ---
 
-# Mail (native — Claude Gmail connector)
+# Mail (native — in-session Gmail connector)
 
 > **Refusal directive — read first.** Gmail is in `native` mode bound to
 > Claude. Do **NOT** call any of:
@@ -17,10 +17,11 @@ allowed-tools:
 > - `/api/mail/<gmail-account-id>/*` (per-account 410 inside the mail
 >   handler; the daemon returns `{"error":"integration_native"}`)
 >
-> Reach Gmail through the `mcp__claude_ai_Gmail__*` MCP tools this
-> session already holds. The 410 is a contract, not an outage — the
-> route gate enforces native-mode exclusivity per
-> `INTEGRATION_NATIVE_MODE_DESIGN.md` §9.
+> Reach Gmail through the in-session Gmail connector your harness exposes.
+> Your tool menu lists every available tool at session start — pick the
+> Gmail one. The 410 is a contract, not an outage — the route gate
+> enforces native-mode exclusivity per `INTEGRATION_NATIVE_MODE_DESIGN.md`
+> §9.
 
 To confirm Gmail's current binding, read the `<integration_modes>`
 block in the system prompt (it carries `gmail="native"` and the
@@ -28,62 +29,49 @@ block in the system prompt (it carries `gmail="native"` and the
 fallback file `~/.personal-agent/integrations.md` shows the same
 information.
 
-## Gmail — Claude's hosted Gmail connector (native MCP)
+## Gmail — in-session connector
 
-Tool namespace: `mcp__claude_ai_Gmail__`
+The exact tool names depend on which Gmail connector your harness has
+loaded. Inspect your tool menu at session start and pick the matching
+capability. Capability-to-intent mapping you should look for:
 
-### Read-class tools (`requiredCapabilities` floor)
+### Read-class capabilities (`requiredCapabilities` floor)
 
-| Capability | Tool | Use |
+| Capability | What to do | How to use |
 |---|---|---|
-| `search` | `mcp__claude_ai_Gmail__search_threads` | List / search threads. Pass a Gmail query (`q="newer_than:1d in:inbox -label:Promotions"`). |
-| `read` | `mcp__claude_ai_Gmail__get_thread` | Fetch a full thread's messages by `threadId`. |
-| `label` | `mcp__claude_ai_Gmail__list_labels` | Enumerate available labels (label IDs are stable per user). |
+| `search` | Search / list Gmail threads | Pass a Gmail query string (e.g. `q="newer_than:1d in:inbox -label:Promotions"`). |
+| `read` | Fetch a single thread's messages | Pass the `threadId` returned by search. |
+| `label` | Enumerate available labels | Read-only listing — labels typically have stable IDs per user. |
 
-Canonical search call:
+Canonical search → read flow:
 
-```
-mcp__claude_ai_Gmail__search_threads(
-  q="newer_than:1d in:inbox -label:Promotions",
-  maxResults=50
-)
-```
-
-Canonical read call (after the search returns `threadId`s):
-
-```
-mcp__claude_ai_Gmail__get_thread(threadId="<id>")
-```
+1. Search recent inbox threads with a Gmail-style query, capping result
+   count to a reasonable number (≈50 for hourly windows).
+2. For each interesting thread id, fetch the full thread to read its
+   messages.
 
-### Draft-class tools (reversible — write-class, not destructive)
+### Draft-class capabilities (reversible — write-class, not destructive)
 
-| Capability | Tool | Confirmation |
+| Capability | What to do | Confirmation |
 |---|---|---|
-| `draft` | `mcp__claude_ai_Gmail__create_draft` | Autonomous — drafts are inert until the user sends from the Gmail web UI. Prefer drafts over direct send. |
-| `draft` | `mcp__claude_ai_Gmail__list_drafts` | Read. |
+| `draft` | Create or list drafts | Autonomous — drafts are inert until the user sends from the Gmail web UI. Prefer drafts over direct send. |
 
 Reply-thread chaining for drafts uses the same RFC-2822 headers documented in
-the direct-mode `mail` skill — Claude's connector exposes
-`inReplyTo` / `references` fields on `create_draft`. Fetch the thread, copy
+the direct-mode `mail` skill — most connectors expose `inReplyTo` /
+`references` fields on their create-draft function. Fetch the thread, copy
 the last message's `Message-Id` into `inReplyTo`, append it to `references`.
 
-### Destructive tools (require explicit user confirmation)
-
-Per the registry's `gmail.backendConnectors.claude.destructiveTools`:
-
-- `mcp__claude_ai_Gmail__label_message`
-- `mcp__claude_ai_Gmail__label_thread`
-- `mcp__claude_ai_Gmail__unlabel_message`
-- `mcp__claude_ai_Gmail__unlabel_thread`
-- `mcp__claude_ai_Gmail__create_label`
-
-Claude's hosted Gmail connector deliberately ships **no** send / forward /
-delete / trash / archive surface. The destructive set here is restricted to
-label mutations and label-taxonomy edits. Apply the same
-destructive-confirm contract as delegated mode: summarise the plan
-("apply label `urgent` to 4 threads"), wait for the user's explicit OK,
-then issue the call. The absolute-block layer
-(`docs/design/09-safety-cost.md` §6) continues to fire regardless of
+### Destructive capabilities (require explicit user confirmation)
+
+Per the registry's `gmail.backendConnectors.claude.destructiveTools`, any
+tool that mutates a thread's or message's labels — or modifies the user's
+label taxonomy — counts as destructive in native:claude mode (the hosted
+Gmail connector deliberately ships no send / forward / delete / trash /
+archive surface, so the destructive set is restricted to label mutation
+and label-taxonomy edits). Apply the same destructive-confirm contract as
+delegated mode: summarise the plan ("apply label `urgent` to 4 threads"),
+wait for the user's explicit OK, then issue the call. The absolute-block
+layer (`docs/design/09-safety-cost.md` §6) continues to fire regardless of
 mode — secret-file reads, recursive deletes, and privilege escalation are
 denied in every posture.
 
@@ -101,7 +89,7 @@ routing decision is per account `kind`:
 
 | Selected account `kind` | Path |
 |---|---|
-| `gmail` | native MCP tools above |
+| `gmail` | in-session Gmail connector (as above) |
 | `outlook` / `icloud` / `yahoo` / `imap` | direct: `/api/mail/<acct>/*` — see the base body for endpoint reference, account-resolution rules (§1), draft-vs-send contract, RFC-2822 reply-thread shape |
 
 Only the Gmail branch leaves the direct-mode surface. Account
@@ -119,25 +107,29 @@ verbatim; do **not** compute the hash yourself (LLM-side hashes drift
 between runs and from the delegated-sync-worker's hash, breaking
 `delegated → native` flip dedup).
 
+**Batch when you have more than one thread.** A single-curl
+`POST /api/observations/batch` accepting up to 200 items is the
+preferred shape — see the `observations` skill for the envelope. The
+single-item form below is for the rare "one new thread surfaced" case.
+
 ```bash
 curl -s -X POST http://localhost:8321/api/observations \
   -H 'Content-Type: application/json' \
   -d '{
-    "source": "gmail",
-    "type": "mail:lifecycle",
+    "source": "gmail:<accountId>",
     "ref": "<threadId>",
-    "actor": "user",
-    "receivedAt": "<ISO-8601 UTC>",
-    "summary_text": "<one-line subject + sender + snippet>",
-    "refs": {
-      "threadId": "<id>",
-      "subject": "<subject>",
-      "from": "<from-address>"
-    },
-    "payload": <verbatim MCP response object>
+    "changeType": "created",
+    "actor": "agent",
+    "payload": <verbatim connector response object>
   }'
 ```
 
+`actor` MUST be `"agent"` or `"system"` — the server rejects `"user"`
+(user-authored observations arrive through the vault / mail watchers,
+never this route). The `source` value follows the `"<integrationKey>:<scope>"`
+convention so the hourly_check consumer's
+`source_prefix=gmail:` filter matches.
+
 `/api/observations` is **never** native-gated — it is the chokepoint the
 native flow relies on for cross-mode dedup, so it stays reachable in
 every mode. The route also rejects late writes from a mode-flip race
@@ -151,10 +143,10 @@ window (§11.3.1) with HTTP 409; on 409 stop and re-read
   `routine.hourly_check.native.<backend>.md`. No drafts, labels,
   archives during the hourly pass — the morning / evening / DM
   flows are the write paths.
-- **Prefer drafts over send.** Claude's connector has no send surface,
-  so drafts are the default channel here. If the user explicitly wants
-  a message sent, point them at the Gmail web UI — explain that this
-  configuration is draft-only by design.
+- **Prefer drafts over send.** Hosted Gmail connectors typically expose
+  no send surface, so drafts are the default channel here. If the user
+  explicitly wants a message sent, point them at the Gmail web UI —
+  explain that this configuration is draft-only by design.
 - **Replies preserve the RFC-2822 chain.** Fetch the thread, copy
   `Message-Id` to `inReplyTo`, append it to `references`. The connector
   signs from the user's authenticated Google account; do not pass an

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

@@ -1,12 +1,12 @@
 ---
 name: mail
-description: Load when the task touches Gmail and Gmail is in native mode bound to Codex (`nativeBackend === "codex"`). Use Codex's hosted Gmail MCP 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 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.
 allowed-tools:
   - Bash(curl *)
   - Read
 ---
 
-# Mail (native — Codex Gmail MCP)
+# Mail (native — in-session Gmail connector)
 
 > **Refusal directive — read first.** Gmail is in `native` mode bound to
 > Codex. Do **NOT** call any of:
@@ -16,72 +16,69 @@ allowed-tools:
 > - `POST /api/integrations/gmail/reconcile` (410)
 > - `/api/mail/<gmail-account-id>/*` (per-account 410)
 >
-> Reach Gmail through the `mcp__codex_apps__gmail._*` MCP tools this
-> Codex session already holds.
+> Reach Gmail through the in-session Gmail connector your harness
+> exposes. Your tool menu lists every available tool at session start —
+> pick the Gmail one. The 410 is a contract, not an outage — the route
+> gate enforces native-mode exclusivity per
+> `INTEGRATION_NATIVE_MODE_DESIGN.md` §9.
 
 To confirm the binding, read `<integration_modes>` (carries
 `gmail="native"`) and the `<integration-routing-table>` block in the
 session preamble. `~/.personal-agent/integrations.md` mirrors the same
 information.
 
-## Gmail — Codex's hosted Gmail MCP (native)
+## Gmail — in-session connector
 
-Tool namespace: `mcp__codex_apps__gmail._`
+The exact tool names depend on which Gmail connector your harness has
+loaded. Inspect your tool menu at session start and pick the matching
+capability. Codex-side hosted connectors typically expose a richer
+surface than Claude's (search-emails / read-thread / draft + dedicated
+send / forward / delete / archive / label tools), but the surface
+varies by harness; rely on the capability classes below rather than
+specific names.
 
-The Codex namespace terminates with `._`, so the bare suffix below is
-what you write after the namespace (e.g. `_search_emails` =
-`mcp__codex_apps__gmail._search_emails`).
+### Read-class capabilities (`requiredCapabilities` floor)
 
-### Read-class tools (`requiredCapabilities` floor)
+| Capability | What to do |
+|---|---|
+| `search` | Search Gmail with a query string. Most connectors expose a results-with-payload primitive plus an ids-only paging variant — use the ids-only flavor when the result count would overflow a single page. |
+| `read` | Single-message read or full-thread read by id. If the connector exposes both, prefer the thread-walk primitive when you need the conversation context. |
+| `label` | Enumerate available labels (read-only). |
 
-| Capability | Tool(s) | Use |
-|---|---|---|
-| `search` | `_search_emails`, `_search_email_ids` | Search; `_search_email_ids` returns ids only when you need to page. |
-| `read` | `_read_email`, `_read_email_thread` | Single message read; full-thread read. |
-| `label` | `_list_labels` | Enumerate available labels. |
+Canonical search flow: invoke your connector's search function with
+`query="newer_than:1d in:inbox -label:Promotions"` and `max_results=50`.
+The exact argument names match the connector's schema (often `query` +
+`max_results`); inspect the tool definition to confirm.
 
-Canonical search call:
+Canonical thread read: invoke your connector's read-thread function
+(or single-message-read + iterate) with the `thread_id` / `message_id`
+returned by search.
 
-```
-mcp__codex_apps__gmail._search_emails(
-  query="newer_than:1d in:inbox -label:Promotions",
-  max_results=50
-)
-```
+### Draft-class capabilities (reversible — write-class, not destructive)
 
-Canonical thread read (after search returns thread/message ids):
+| Capability | What to do | Confirmation |
+|---|---|---|
+| `draft` | Create a draft. Autonomous — drafts are inert until the user sends. Prefer drafts. |
+| `draft` | List drafts (read). |
+| `update_draft` | Mutate a not-yet-sent draft. Reversible — the user can still review before sending. Write-class but not destructive. |
 
-```
-mcp__codex_apps__gmail._read_email_thread(thread_id="<id>")
-```
+Reply-thread chaining: most connectors expose RFC-2822 `in_reply_to` /
+`references` fields on their create-draft function. Fetch the thread
+first, copy the last message's `Message-Id` to `in_reply_to`, append it
+to `references`.
 
-### Draft-class tools (reversible — write-class, not destructive)
+### Destructive capabilities (require explicit user confirmation)
 
-| Capability | Tool | Confirmation |
-|---|---|---|
-| `draft` | `_create_draft` | Autonomous — drafts are inert until the user sends. Prefer drafts. |
-| `draft` | `_list_drafts` | Read. |
-| `update_draft` | `_update_draft` | Reversible — `update_draft` mutates a not-yet-sent draft; the user can still review before sending. Write-class but not destructive. |
-
-Reply-thread chaining: the connector accepts RFC-2822 `in_reply_to` /
-`references` fields on `_create_draft`. Fetch the thread first, copy
-the last message's `Message-Id` to `in_reply_to`, append it to
-`references`.
-
-### Destructive tools (require explicit user confirmation)
-
-Per the registry's `gmail.backendConnectors.codex.destructiveTools`:
-
-- `_send_email` — irreversible dispatch.
-- `_send_draft` — irreversible dispatch of a previously composed draft.
-- `_forward_emails` — irreversible dispatch.
-- `_delete_emails` — irreversible.
-- `_archive_emails` — reversible (archive can be unarchived) but
-  user-visible and treated as destructive in the registry.
-- `_apply_labels_to_emails` — label mutation.
-- `_bulk_label_matching_emails` — mass label mutation.
-- `_create_label` — taxonomy edit.
-- `_batch_modify_email` — mass mutation.
+Per the registry's `gmail.backendConnectors.codex.destructiveTools`,
+the following capability classes are destructive in native:codex mode:
+
+- **Send / forward** — irreversible dispatch (compose-and-send, send a
+  previously composed draft, forward a thread).
+- **Delete** — irreversible removal.
+- **Archive** — reversible but user-visible; treated as destructive.
+- **Apply / bulk-apply labels** — label mutation, single or mass.
+- **Create label** — taxonomy edit.
+- **Batch modify** — mass mutation across many messages.
 
 Apply the destructive-confirm contract:
 
@@ -92,10 +89,10 @@ Apply the destructive-confirm contract:
    the absolute-block layer or the `deniedTools` deny list rejected it
    for a reason.
 
-The starter `deniedTools` set (e.g. `_send_email`) is pre-populated by
-the setup wizard for safety; the dashboard's Tool Permissions card is
-the surface for widening it. Calls into a denied tool fail before they
-land at the connector.
+The starter `deniedTools` list (typically denies the send capability)
+is pre-populated by the setup wizard for safety; the dashboard's Tool
+Permissions card is the surface for widening it. Calls into a denied
+tool fail before they reach the connector.
 
 ## Non-Gmail accounts (IMAP / Outlook / iCloud / Yahoo)
 
@@ -105,7 +102,7 @@ alongside this skill) is the authoritative list. Routing:
 
 | Selected account `kind` | Path |
 |---|---|
-| `gmail` | native MCP tools above |
+| `gmail` | in-session Gmail connector (as above) |
 | `outlook` / `icloud` / `yahoo` / `imap` | direct: `/api/mail/<acct>/*` (see base body) |
 
 The base body's account-resolution rules (§1), send-vs-draft contract,
@@ -115,27 +112,28 @@ and RFC-2822 reply chain shape are unchanged for non-Gmail accounts.
 
 POST each materialised Gmail thread fetched in a routine to
 `/api/observations`. The daemon computes `contentHash` server-side via
-`@personal-agent/shared/observations-hash.ts`; pass `payload` verbatim:
+`@personal-agent/shared/observations-hash.ts`; pass `payload` verbatim.
+
+**Batch when you have more than one thread.** Use
+`POST /api/observations/batch` with up to 200 items in a single
+`observations[]` array (see the `observations` skill for the envelope).
+The single-item form below is for the rare "one new thread surfaced"
+case.
 
 ```bash
 curl -s -X POST http://localhost:8321/api/observations \
   -H 'Content-Type: application/json' \
   -d '{
-    "source": "gmail",
-    "type": "mail:lifecycle",
+    "source": "gmail:<accountId>",
     "ref": "<threadId>",
-    "actor": "user",
-    "receivedAt": "<ISO-8601 UTC>",
-    "summary_text": "<one-line subject + sender + snippet>",
-    "refs": {
-      "threadId": "<id>",
-      "subject": "<subject>",
-      "from": "<from-address>"
-    },
-    "payload": <verbatim MCP response object>
+    "changeType": "created",
+    "actor": "agent",
+    "payload": <verbatim connector response object>
   }'
 ```
 
+`actor` MUST be `"agent"` or `"system"` — the server rejects `"user"`.
+
 `/api/observations` is never gated. On HTTP 409 (lock-window race
 during a mode flip per §11.3.1), stop and re-read `<integration_modes>`
 — the integration has flipped under you.
@@ -145,14 +143,14 @@ during a mode flip per §11.3.1), stop and re-read `<integration_modes>`
 - **Hourly check is read-only** — inherits the constraint from
   `routine.hourly_check.native.codex.md`. No sends, archives, label
   writes during hourly.
-- **Prefer drafts over send.** `_create_draft` is autonomous;
-  `_send_email` / `_send_draft` require explicit user OK.
+- **Prefer drafts over send.** The create-draft capability is
+  autonomous; the send / send-draft capabilities require explicit user
+  OK.
 - **Replies preserve the RFC-2822 chain.** Pin `Message-Id` /
   `References` headers on the draft.
-- **Bulk operations: ask first.** A `_bulk_label_matching_emails` or
-  `_batch_modify_email` call that would touch more than ~3 messages
-  needs an explicit confirmation message summarising the criteria and
-  the count.
+- **Bulk operations: ask first.** A bulk-label or batch-modify call
+  that would touch more than ~3 messages needs an explicit confirmation
+  message summarising the criteria and the count.
 - **The reply account is implicit.** The connector signs from the
   authenticated Google account; do not pass an `accountId`.
 - **No `bcc` unless the user explicitly asks for it.**

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

@@ -1,12 +1,12 @@
 ---
 name: mail
-description: Load when the task touches Gmail and Gmail is in native mode bound to Gemini (`nativeBackend === "gemini"`). Use Gemini CLI's google-workspace extension 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 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.
 allowed-tools:
   - Bash(curl *)
   - Read
 ---
 
-# Mail (native — Gemini google-workspace extension)
+# Mail (native — in-session Gmail connector)
 
 > **Refusal directive — read first.** Gmail is in `native` mode bound to
 > Gemini. Do **NOT** call any of:
@@ -16,83 +16,86 @@ allowed-tools:
 > - `POST /api/integrations/gmail/reconcile` (410)
 > - `/api/mail/<gmail-account-id>/*` (per-account 410)
 >
-> Reach Gmail through the `mcp_google-workspace_gmail.*` MCP tools your
-> Gemini session already holds via the `google-workspace` extension.
+> Reach Gmail through the in-session Gmail connector your harness
+> exposes (typically Gemini CLI's `google-workspace` extension or a
+> user-installed equivalent). Your tool menu lists every available tool
+> at session start — pick the Gmail one.
 
 Confirm the binding by reading `<integration_modes>` (carries
 `gmail="native"`) and the `<integration-routing-table>` block in the
 session preamble. `~/.personal-agent/integrations.md` mirrors the same.
 
-## Gmail — google-workspace extension (native MCP)
+## Gmail — in-session connector
 
-Tool namespace: `mcp_google-workspace_gmail.`
+The exact tool names depend on which Gmail connector your harness has
+loaded. Inspect your tool menu at session start and pick the matching
+capability. Gemini CLI's `google-workspace` extension is the typical
+provider here; its surface is leaner than Codex's (no dedicated
+delete / forward — those compose from primitives, see below). Other
+user-installed Gmail MCP servers may differ; rely on the capability
+classes rather than specific tool names.
 
-Gemini CLI registers extension tools with single underscores and a
-`.` separator between server and tool, so the bare suffix below is what
-you write after the namespace (`search` =
-`mcp_google-workspace_gmail.search`).
+### Read-class capabilities (`requiredCapabilities` floor)
 
-### Read-class tools (`requiredCapabilities` floor)
-
-| Capability | Tool | Use |
-|---|---|---|
-| `search` | `search` | Gmail search (`q` accepts the same query grammar as the web UI). |
-| `read` | `get` | Fetch a single message by `id` (the extension does not expose a thread-walk primitive; compose search + per-message `get`). |
-| `label` | `listLabels` | Enumerate available labels. |
-
-Canonical search call:
+| Capability | What to do |
+|---|---|
+| `search` | Gmail search — pass a query string in the same grammar as the web UI. |
+| `read` | Fetch a single message by id. Some connectors expose no thread-walk primitive; compose search + per-message read in that case (see pattern below). |
+| `label` | Enumerate available labels (read-only). |
 
-```
-mcp_google-workspace_gmail.search(
-  q="newer_than:1d in:inbox -label:Promotions",
-  maxResults=50
-)
-```
+Canonical search flow: invoke your connector's search function with
+`q="newer_than:1d in:inbox -label:Promotions"` and (if supported)
+`maxResults=50`. See the Gemini-specific quirk below: some connectors
+silently ignore `maxResults`.
 
-Read pattern (the extension lacks `getThread`, so compose):
+Read pattern when the connector lacks a thread-walk primitive (compose
+search + per-message read):
 
 ```
-hits = mcp_google-workspace_gmail.search(q="threadId:<id>", maxResults=100)
+hits = <connector search>(q="threadId:<id>", maxResults=100)
 for msg_id in hits:
-    mcp_google-workspace_gmail.get(id=msg_id)
+    <connector get message>(id=msg_id)
 ```
 
-### Draft-class tools (reversible — write-class, not destructive)
+### Draft-class capabilities (reversible — write-class, not destructive)
 
-| Capability | Tool | Confirmation |
+| Capability | What to do | Confirmation |
 |---|---|---|
-| `draft` | `createDraft` | Autonomous — drafts are inert until the user sends. Prefer drafts over `send`. |
-| `read_attachment` | `downloadAttachment` | Read. |
+| `draft` | Create a draft. Autonomous — drafts are inert until the user sends. Prefer drafts over send. |
+| `read_attachment` | Download an attachment (read). |
 
-`createDraft` accepts `inReplyTo` and `references` fields for
-RFC-2822 thread chaining — fetch the thread first, pin the headers.
+The create-draft capability typically accepts `inReplyTo` and
+`references` fields for RFC-2822 thread chaining — fetch the thread
+first, pin the headers.
 
-### Destructive tools (require explicit user confirmation)
+### Destructive capabilities (require explicit user confirmation)
 
-Per the registry's `gmail.backendConnectors.gemini.destructiveTools`:
+Per the registry's `gmail.backendConnectors.gemini.destructiveTools`,
+the following capability classes are destructive in native:gemini mode:
 
-- `send` — compose-and-send in one call (irreversible).
-- `sendDraft` — dispatch a previously composed draft (irreversible).
-- `modify` — apply / remove labels including the system `TRASH` label
+- **Send** — compose-and-send in one call (irreversible).
+- **Send draft** — dispatch a previously composed draft (irreversible).
+- **Modify** — apply / remove labels including the system `TRASH` label
   (covers delete-by-trash; archive likewise via `INBOX` label removal).
-- `modifyThread` — same as `modify`, thread-scope.
-- `createLabel` — taxonomy edit.
-- `batchModify` — mass label mutation.
-
-The google-workspace extension exposes **no** dedicated `delete` or
-`forward` tool — those compose from primitives (`delete` = `modify` +
-add `TRASH`; `forward` = `send` with re-quoted body). The registry's
-`gemini.optionalCapabilities` reflect this honestly; do not infer parity
-the connector does not have. If the user asks to forward a message,
-fetch it, compose the body, and call `send` after the destructive
-confirmation.
+- **Modify thread** — same as modify, thread-scope.
+- **Create label** — taxonomy edit.
+- **Batch modify** — mass label mutation.
+
+Some Gemini-side connectors (notably the `google-workspace` extension)
+expose **no** dedicated delete or forward tool — those compose from
+primitives (delete = modify + add `TRASH`; forward = send with re-quoted
+body). The registry's `gemini.optionalCapabilities` reflects this
+honestly; do not infer parity the connector does not have. If the user
+asks to forward a message, fetch it, compose the body, and call send
+after the destructive confirmation.
 
 Apply the destructive-confirm contract:
 
 1. Summarise the plan in one line.
 2. Surface verbatim and wait for explicit user OK.
-3. On OK, issue the call once. The starter `deniedTools` list (typically
-   includes `send`) is enforced before the call lands; honour it.
+3. On OK, issue the call once. The starter `deniedTools` list
+   (typically includes the send capability) is enforced before the
+   call lands; honour it.
 
 The absolute-block layer (`docs/design/09-safety-cost.md` §6) continues
 to fire regardless of mode — recursive deletes, secret-file reads, and
@@ -105,7 +108,7 @@ resolves to a Gmail account. Routing:
 
 | Selected account `kind` | Path |
 |---|---|
-| `gmail` | native MCP tools above |
+| `gmail` | in-session Gmail connector (as above) |
 | `outlook` / `icloud` / `yahoo` / `imap` | direct: `/api/mail/<acct>/*` (see base body) |
 
 The base body's account-resolution rules (§1), send-vs-draft contract,
@@ -117,27 +120,28 @@ for non-Gmail accounts.
 POST each materialised Gmail message fetched in a routine to
 `/api/observations`. The daemon computes `contentHash` server-side via
 the shared util in `@personal-agent/shared/observations-hash.ts`; pass
-`payload` verbatim:
+`payload` verbatim.
+
+**Batch when you have more than one message.** Use
+`POST /api/observations/batch` with up to 200 items in one
+`observations[]` array (see the `observations` skill for the envelope).
+The single-item form below is for the rare "one new message surfaced"
+case.
 
 ```bash
 curl -s -X POST http://localhost:8321/api/observations \
   -H 'Content-Type: application/json' \
   -d '{
-    "source": "gmail",
-    "type": "mail:lifecycle",
+    "source": "gmail:<accountId>",
     "ref": "<threadId-or-messageId>",
-    "actor": "user",
-    "receivedAt": "<ISO-8601 UTC>",
-    "summary_text": "<one-line subject + sender + snippet>",
-    "refs": {
-      "threadId": "<id>",
-      "subject": "<subject>",
-      "from": "<from-address>"
-    },
-    "payload": <verbatim MCP response object>
+    "changeType": "created",
+    "actor": "agent",
+    "payload": <verbatim connector response object>
   }'
 ```
 
+`actor` MUST be `"agent"` or `"system"` — the server rejects `"user"`.
+
 `/api/observations` is never gated. On HTTP 409 the integration has
 flipped during the lock window (§11.3.1) — stop and re-read
 `<integration_modes>`.
@@ -146,20 +150,21 @@ flipped during the lock window (§11.3.1) — stop and re-read
 
 - **Hourly check is read-only** — inherits the constraint from
   `routine.hourly_check.native.gemini.md`.
-- **Prefer drafts over send.** `createDraft` is autonomous; `send` /
-  `sendDraft` need explicit user OK.
+- **Prefer drafts over send.** The create-draft capability is
+  autonomous; send / send-draft need explicit user OK.
 - **Replies preserve the RFC-2822 chain.** Pin `inReplyTo` /
   `references` on the draft.
-- **Bulk operations: ask first.** `batchModify` and `modifyThread`
-  calls touching more than ~3 messages need an explicit confirmation.
-- **The reply account is implicit** — the extension signs from the
+- **Bulk operations: ask first.** Batch-modify and modify-thread calls
+  touching more than ~3 messages need an explicit confirmation.
+- **The reply account is implicit** — the connector signs from the
   user's authenticated Google account.
 - **No `bcc` unless the user explicitly asks for it.**
-- **Gemini-specific quirk** (`maxResults` ignored on `search`): the
-  google-workspace extension silently ignores `maxResults`; the result
-  set is bounded only by the query window and Google's default. When
-  the call returns more than expected, paginate via narrower `q=`
-  windows rather than retrying with a smaller `maxResults`.
+- **Gemini-specific quirk** (`maxResults` ignored on search): some
+  Gemini-side Gmail connectors silently ignore `maxResults`; the
+  result set is bounded only by the query window and the connector's
+  default. When the call returns more than expected, paginate via
+  narrower `q=` windows rather than retrying with a smaller
+  `maxResults`.
 
 ## Cost / audit