ask-marcel-office-cli 1.0.0 → 1.5.0

package/docs/commands.json

@@ -1,11 +1,162 @@
 {
   "package": "ask-marcel-office-cli",
-  "version": "1.0.0",
-  "generatedAt": "2026-05-19T10:57:25.983Z",
+  "version": "1.5.0",
+  "generatedAt": "2026-06-16T16:14:42.738Z",
   "commands": [
+    {
+      "name": "convert-calendar-event-attachment-to-markdown",
+      "summary": "Convert an attachment on an Outlook calendar event to markdown. Polymorphic on the attachment’s `@odata.type` (shares the mail-attachment pipeline): fileAttachment decodes the inline bytes and runs them through the local conversion pipeline (docx via mammoth, xlsx via sheetjs, csv as markdown table, odt/ods/odp via content.xml, plus plain-text passthrough); referenceAttachment resolves via /shares/{token}/driveItem and routes through the same dispatcher; itemAttachment (embedded mail / event / contact) is rendered locally. For pptx decks attached to a meeting, `convert-calendar-event-attachment-to-pdf` preserves slide layout (a pptx here yields only its speaker notes / titles / comments via `## PPTX metadata` with `--include-metadata true`). For pdf/rtf/etc. also use the PDF sibling.",
+      "category": "calendar",
+      "graphMethod": "GET",
+      "graphPathTemplate": "/me/events/{event-id}/attachments/{attachment-id}",
+      "graphDocsUrl": "https://learn.microsoft.com/en-us/graph/api/attachment-get",
+      "options": [
+        {
+          "name": "event-id",
+          "key": "eventId",
+          "required": true,
+          "description": "Outlook calendar event ID. Returned by `list-calendar-events` or `get-calendar-event`."
+        },
+        {
+          "name": "attachment-id",
+          "key": "attachmentId",
+          "required": true,
+          "description": "Attachment ID inside that event. Returned by `list-calendar-event-attachments`."
+        },
+        {
+          "name": "include-metadata",
+          "key": "includeMetadata",
+          "required": false,
+          "description": "Pass `--include-metadata true` to surface side-channel content for docx, xlsx, pptx, and OpenDocument attachments. docx → `## DOCX metadata`; xlsx → `## Workbook metadata`; pptx → `## PPTX metadata` (standalone, since pptx has no convertible body); odt/ods/odp → `## OpenDocument metadata`, appended after the converted body. No-op on other attachment types and on itemAttachment renderers.",
+          "argumentHint": {
+            "kind": "magicValue",
+            "values": [
+              "true",
+              "false"
+            ]
+          }
+        }
+      ],
+      "example": "ask-marcel convert-calendar-event-attachment-to-markdown --event-id 'AAMkAD...' --attachment-id 'AAMkAD...attach1'",
+      "responseShape": "`{ contentType: \"text/markdown\", size, text }` on success (file/reference attachments converted via Graph + turndown; itemAttachment rendered locally). Plain-text source extensions return the raw-bytes envelope; unsupported types return an api_error with status 400.",
+      "producesBytes": true
+    },
+    {
+      "name": "convert-calendar-event-attachment-to-pdf",
+      "summary": "Convert an attachment on an Outlook calendar event to PDF on the fly (shares the mail-attachment pipeline). fileAttachment uploads the bytes to a temp folder under /me/drive, runs Graph `?format=pdf`, then deletes the temp item; referenceAttachment resolves via /shares/{token}/driveItem and converts in place; plain-text and `pdf` sources short-circuit to a raw-bytes envelope (Graph’s `?format=pdf` does not accept `pdf` as an input). image attachments are rejected (Graph rejects image inputs); itemAttachment (embedded mail/event/contact) is unsupported — use convert-calendar-event-attachment-to-markdown. Best for the deck attached to a meeting, where PDF preserves slide layout for a vision-capable LLM.",
+      "category": "calendar",
+      "graphMethod": "GET",
+      "graphPathTemplate": "/me/events/{event-id}/attachments/{attachment-id}",
+      "graphDocsUrl": "https://learn.microsoft.com/en-us/graph/api/attachment-get",
+      "options": [
+        {
+          "name": "event-id",
+          "key": "eventId",
+          "required": true,
+          "description": "Outlook calendar event ID. Returned by `list-calendar-events` or `get-calendar-event`."
+        },
+        {
+          "name": "attachment-id",
+          "key": "attachmentId",
+          "required": true,
+          "description": "Attachment ID inside that event. Returned by `list-calendar-event-attachments`."
+        }
+      ],
+      "example": "ask-marcel convert-calendar-event-attachment-to-pdf --event-id 'AAMkAD...' --attachment-id 'AAMkAD...attach1' --output-path ./deck.pdf",
+      "responseShape": "`{ contentType: \"application/pdf\", size, base64 }` — the PDF bytes, inlined. Plain-text and pdf sources short-circuit to `{ contentType, size, base64, note }`; image attachments return api_error 415; itemAttachment returns api_error 400. Pair with the global `--output-path` to land the bytes on disk and replace `base64` with `savedTo`.",
+      "producesBytes": true
+    },
+    {
+      "name": "convert-drive-item-zip",
+      "summary": "Unzip a `.zip` from a OneDrive / SharePoint item and convert every contained file in one call — so \"read the handover archive\" doesn't need a separate unzip + per-file conversion. Office files (docx/xlsx/pptx/odt/ods/odp and their macro-enabled / template variants) are converted to markdown via the local pipelines; plain-text entries (txt/md/csv/json/yaml/…) are decoded inline; legacy OLE .xls (sheetjs) and .doc (word-extractor, text only) are extracted; an Outlook .msg entry is rendered to markdown (headers + body, with its own attachments converted recursively); PDFs have their text layer extracted (text/plain); images, binaries, nested archives, legacy .ppt, and scanned/image-only PDFs (no text layer) are listed with a note (not unpacked) so one unsupported entry never fails the whole archive. Pass `--include-metadata true` to append each Office file's side-channel metadata block. Capped at 100 entries (the archive is buffered in memory); beyond that the response is flagged `truncated`.",
+      "category": "drive",
+      "graphMethod": "GET",
+      "graphPathTemplate": "/drives/{drive-id}/items/{item-id}/content",
+      "graphDocsUrl": "https://learn.microsoft.com/en-us/graph/api/driveitem-get-content",
+      "options": [
+        {
+          "name": "drive-id",
+          "key": "driveId",
+          "required": true,
+          "description": "Microsoft Graph drive ID. Use `ask-marcel list-drives` for the personal OneDrive, or `ask-marcel list-sharepoint-site-drives --site-id <id>` for a SharePoint document library."
+        },
+        {
+          "name": "item-id",
+          "key": "itemId",
+          "required": true,
+          "description": "driveItem ID of the .zip file. Returned by `list-folder-files` or `search-onedrive-files`."
+        },
+        {
+          "name": "include-metadata",
+          "key": "includeMetadata",
+          "required": false,
+          "description": "Pass `--include-metadata true` to append each converted Office file’s side-channel metadata block (`## DOCX metadata` / `## Workbook metadata` / `## PPTX metadata` / `## OpenDocument metadata`, etc.) after its body.",
+          "argumentHint": {
+            "kind": "magicValue",
+            "values": [
+              "true",
+              "false"
+            ]
+          }
+        }
+      ],
+      "example": "ask-marcel convert-drive-item-zip --drive-id 'b!1234' --item-id '01ABC'",
+      "responseShape": "`{ count, files: [{ path, contentType, size, text }] }` — one entry per file in the archive (sorted by path). Convertible files carry `{ contentType, size, text }` (the markdown); unsupported / failed entries carry `{ path, note }` instead. When the archive has more than 100 entries the response adds `truncated: true` + `totalEntries` and only the first 100 are converted."
+    },
+    {
+      "name": "convert-local-file",
+      "summary": "Convert a file ON DISK to markdown — the only command that never calls Microsoft Graph (works offline, no login). Runs the same local pipelines as `download-drive-item-as-markdown`: docx (mammoth → turndown), xlsx (sheetjs tables, `--max-cells` OOM cap), pptx (per-slide text), odt/ods/odp, csv, pdf (text layer via unpdf), legacy OLE .xls / .doc, Outlook .msg (headers + body, attachments converted recursively), plain-text passthrough — and a `.zip` is unpacked with every contained file converted in one call (legacy GBK / CP437 entry names decoded, not mojibaked). What it canNOT do locally: convert TO pdf, and Loop/Fluid/Whiteboard sources — both need a Graph server round-trip (upload to OneDrive and use the drive-item siblings). Pass `--include-metadata true` for the Office side-channel metadata blocks; `--inline-images true` to embed docx images as base64 data URIs.",
+      "category": "meta",
+      "graphMethod": "GET",
+      "graphPathTemplate": "(local) reads {path} from the local filesystem; not a Graph endpoint",
+      "graphDocsUrl": "https://learn.microsoft.com/en-us/graph/",
+      "options": [
+        {
+          "name": "path",
+          "key": "path",
+          "required": true,
+          "description": "Filesystem path of the file to convert (absolute, or relative to the current working directory). E.g. `./report.docx`, `/tmp/handover.zip`."
+        },
+        {
+          "name": "include-metadata",
+          "key": "includeMetadata",
+          "required": false,
+          "description": "Pass `--include-metadata true` to append the converted Office file’s side-channel metadata block (`## DOCX metadata` / `## Workbook metadata` / `## PPTX metadata` / `## OpenDocument metadata`, etc.) after its body. Applies inside a `.zip` too.",
+          "argumentHint": {
+            "kind": "magicValue",
+            "values": [
+              "true",
+              "false"
+            ]
+          }
+        },
+        {
+          "name": "inline-images",
+          "key": "inlineImages",
+          "required": false,
+          "description": "Pass `--inline-images true` to embed a docx's images as base64 `data:` URIs. Default `false` — each image becomes an `[image: <alt>]` placeholder. No-op on non-docx sources.",
+          "argumentHint": {
+            "kind": "magicValue",
+            "values": [
+              "true",
+              "false"
+            ]
+          }
+        },
+        {
+          "name": "max-cells",
+          "key": "maxCells",
+          "required": false,
+          "description": "Per-sheet cell cap (positive integer; default 50 000) for xlsx/csv sources. A sheet whose used range exceeds the cap renders as a truncation hint instead of a multi-hundred-MB table. No-op on other sources."
+        }
+      ],
+      "example": "ask-marcel convert-local-file --path ./report.docx",
+      "responseShape": "`{ contentType: \"text/markdown\" | \"text/plain\", size, text }` for a single file; `{ count, files: [{ path, contentType, size, text } | { path, note }] }` for a `.zip` (one entry per contained file, unsupported entries noted). A missing file returns api_error 404 with the path. Pair with the global `--output-path` to land the markdown on disk.",
+      "producesBytes": true
+    },
     {
       "name": "convert-mail-attachment-to-markdown",
-      "summary": "Convert an Outlook mail attachment to markdown. Polymorphic on the attachment’s `@odata.type`: fileAttachment decodes the inline bytes and runs them through the local conversion pipeline (docx via mammoth, xlsx via sheetjs, csv as markdown table, plus plain-text passthrough); referenceAttachment resolves via /shares/{token}/driveItem and routes through the same dispatcher; itemAttachment (embedded mail / event / contact) is rendered locally via dedicated renderers. For pptx attachments, `convert-mail-attachment-to-pdf` is recommended (Graph PDF preserves slide layout). For pdf/rtf/odt/etc. also use the PDF sibling. Loop/Fluid/Whiteboard reference-attachments use Graph `?format=html` (the four inputs Microsoft documents).",
+      "summary": "Convert an Outlook mail attachment to markdown. Polymorphic on the attachment’s `@odata.type`: fileAttachment decodes the inline bytes and runs them through the local conversion pipeline (docx via mammoth, xlsx via sheetjs, csv as markdown table, odt/ods/odp via content.xml, pptx as per-slide text (titles + bullets + speaker notes inline), pdf via text-layer extraction (unpdf → text/plain), legacy .xls via sheetjs and legacy .doc via word-extractor (text only), an Outlook .msg attachment rendered to markdown — headers + body with its own attachments converted recursively — plus plain-text passthrough); referenceAttachment resolves via /shares/{token}/driveItem and routes through the same dispatcher; itemAttachment (embedded mail / event / contact) is rendered locally via dedicated renderers. For pptx layout / images, `convert-mail-attachment-to-pdf` + a vision model reads the rendered deck better. A scanned / image-only PDF (no text layer), legacy .ppt, and rtf/etc. point to the PDF sibling. Loop/Fluid/Whiteboard reference-attachments use Graph `?format=html` (the four inputs Microsoft documents).",
       "category": "mail",
       "graphMethod": "GET",
       "graphPathTemplate": "/me/messages/{message-id}/attachments/{attachment-id}",
@@ -22,10 +173,24 @@
           "key": "attachmentId",
           "required": true,
           "description": "Attachment ID inside that message. Returned by `list-mail-attachments`."
+        },
+        {
+          "name": "include-metadata",
+          "key": "includeMetadata",
+          "required": false,
+          "description": "Pass `--include-metadata true` to surface side-channel content for docx, xlsx, pptx, and OpenDocument attachments (file + reference). docx → `## DOCX metadata` (properties, people, hyperlinks, comments, tracked changes, hidden text, fields, bookmarks); xlsx → `## Workbook metadata` (properties, external relationships, defined names, hidden / very-hidden sheets, cell + threaded comments, persons); pptx → `## PPTX metadata` (properties, external relationships, slide tags, comment authors + comments, per-slide title / speaker notes / hidden flag) as a standalone document, since pptx has no convertible body; odt/ods/odp → `## OpenDocument metadata` (Dublin Core + ODF properties, keywords, user-defined fields), appended after the converted body. Each OOXML family also covers its macro-enabled and template variants, with a `### Macros (VBA)` section flagging an embedded `vbaProject.bin`. No-op on other attachment types and on itemAttachment renderers.",
+          "argumentHint": {
+            "kind": "magicValue",
+            "values": [
+              "true",
+              "false"
+            ]
+          }
         }
       ],
       "example": "ask-marcel convert-mail-attachment-to-markdown --message-id 'AAMkAD...' --attachment-id 'AAMkAD...attach1'",
-      "responseShape": "`{ contentType: \"text/markdown\", size, text }` on success (file/reference attachments converted via Graph + turndown; itemAttachment rendered locally). Plain-text source extensions return the raw-bytes envelope; unsupported types return an api_error with status 400."
+      "responseShape": "`{ contentType: \"text/markdown\", size, text }` on success (file/reference attachments converted via Graph + turndown; itemAttachment rendered locally). Plain-text source extensions return the raw-bytes envelope; unsupported types return an api_error with status 400.",
+      "producesBytes": true
     },
     {
       "name": "convert-mail-attachment-to-pdf",
@@ -49,11 +214,49 @@
         }
       ],
       "example": "ask-marcel convert-mail-attachment-to-pdf --message-id 'AAMkAD...' --attachment-id 'AAMkAD...attach1'",
-      "responseShape": "`{ contentType: \"application/pdf\", size, base64 }` — the PDF bytes, inlined. The CLI follows the SharePoint media-transform redirect internally so the LLM never has to fetch an external URL. Plain-text source extensions and pdf sources short-circuit to `{ contentType, size, base64, note }` with their native bytes; itemAttachment returns api_error 400. Pair with the global `--output-path` to land the bytes on disk and replace `base64` with `savedTo` for multi-MB PDFs."
+      "responseShape": "`{ contentType: \"application/pdf\", size, base64 }` — the PDF bytes, inlined. The CLI follows the SharePoint media-transform redirect internally so the LLM never has to fetch an external URL. Plain-text source extensions and pdf sources short-circuit to `{ contentType, size, base64, note }` with their native bytes; itemAttachment returns api_error 400. Pair with the global `--output-path` to land the bytes on disk and replace `base64` with `savedTo` for multi-MB PDFs.",
+      "producesBytes": true
+    },
+    {
+      "name": "convert-mail-attachment-zip",
+      "summary": "Unzip a `.zip` Outlook mail attachment and convert every contained file in one call — the mail-side mirror of `convert-drive-item-zip`, so reading a zipped vendor deck doesn't need `get-mail-attachment` + manual `unzip` + per-file conversion. Pulls the fileAttachment bytes, unzips them (legacy GBK / CP437 entry names — Chinese vendor archives written by WinRAR / Windows Explorer — are decoded correctly, not mojibaked), and runs each file through the local pipelines: Office files (docx/xlsx/pptx/odt/ods/odp and macro-enabled / template variants) → markdown; plain-text entries decoded inline; legacy OLE .xls (sheetjs) and .doc (word-extractor, text only) extracted; an inner Outlook .msg rendered; PDFs have their text layer extracted; images, binaries, nested archives, legacy .ppt, and scanned/image-only PDFs are listed with a note (not unpacked) so one unsupported entry never fails the whole archive. Pass `--include-metadata true` to append each Office file's side-channel metadata block. Capped at 100 entries; beyond that the response is flagged `truncated`. itemAttachment / referenceAttachment are rejected (no inline zip payload).",
+      "category": "mail",
+      "graphMethod": "GET",
+      "graphPathTemplate": "/me/messages/{message-id}/attachments/{attachment-id}",
+      "graphDocsUrl": "https://learn.microsoft.com/en-us/graph/api/attachment-get",
+      "options": [
+        {
+          "name": "message-id",
+          "key": "messageId",
+          "required": true,
+          "description": "Outlook message ID. Returned by `list-mail-messages` or `list-mail-folder-messages`."
+        },
+        {
+          "name": "attachment-id",
+          "key": "attachmentId",
+          "required": true,
+          "description": "Attachment ID of the .zip fileAttachment. Returned by `list-mail-attachments`."
+        },
+        {
+          "name": "include-metadata",
+          "key": "includeMetadata",
+          "required": false,
+          "description": "Pass `--include-metadata true` to append each converted Office file’s side-channel metadata block (`## DOCX metadata` / `## Workbook metadata` / `## PPTX metadata` / `## OpenDocument metadata`, etc.) after its body.",
+          "argumentHint": {
+            "kind": "magicValue",
+            "values": [
+              "true",
+              "false"
+            ]
+          }
+        }
+      ],
+      "example": "ask-marcel convert-mail-attachment-zip --message-id 'AAMkAD...' --attachment-id 'AAMkAD...attach1'",
+      "responseShape": "`{ count, files: [{ path, contentType, size, text }] }` — one entry per file in the archive (sorted by path; non-mojibake names). Convertible files carry `{ contentType, size, text }` (the markdown); unsupported / failed entries carry `{ path, note }`. When the archive has more than 100 entries the response adds `truncated: true` + `totalEntries` and only the first 100 are converted. A non-fileAttachment (itemAttachment / referenceAttachment) or a non-zip payload returns an api_error."
     },
     {
       "name": "convert-mail-to-markdown",
-      "summary": "Render a single Outlook email as markdown — headers (`**Subject:**`, `**From:**`, `**To:**`, `**Cc:**` only when present, `**Date:**`), followed by the body run through turndown. Inline images attached with `isInline:true` and an `image/*` content-type (size ≤ 2 MB) are embedded as base64 `data:` URIs so the output is self-contained (Hardening #1: non-image inline attachments are NOT embedded; oversize inline images are replaced with a placeholder note). File attachments are listed below the body by name + size + id; their bytes are NOT fetched here — call `convert-mail-attachment-to-pdf` or `get-mail-attachment` with the id when you actually need them. Staged-fetch design (audit v1.0.0): one call for the body, one for the attachments-metadata list (only if `hasAttachments:true`), and one per small inline image — replaces the old `?$expand=attachments` which timed out / truncated on messages with multi-MB attachments.",
+      "summary": "Render a single Outlook email as markdown — headers (`**Subject:**`, `**From:**`, `**To:**`, `**Cc:**` only when present, `**Date:**`), followed by the body run through turndown. By default, inline images (`isInline:true` + `image/*` content-type, size ≤ 2 MB) are embedded as base64 `data:` URIs so the output is self-contained (non-image inline attachments are NOT embedded; oversize inline images are replaced with a placeholder note). For LLM callers that only want the text body, pass `--inline-images false` to skip the per-image bytes fetch entirely — the body keeps raw `cid:<contentId>` references and the inline images surface in the file-attachments list so you can decide whether to fetch them separately via `get-mail-attachment`. File attachments are always listed below the body by name + size + id; their bytes are NOT fetched here — call `convert-mail-attachment-to-pdf` or `get-mail-attachment` with the id when you actually need them. Staged-fetch design (audit v1.0.0): one call for the body, one for the attachments-metadata list (only if `hasAttachments:true`), and one per small inline image — replaces the old `?$expand=attachments` which timed out / truncated on messages with multi-MB attachments.",
       "category": "mail",
       "graphMethod": "GET",
       "graphPathTemplate": "/me/messages/{message-id}",
@@ -63,15 +266,121 @@
           "name": "message-id",
           "key": "messageId",
           "required": true,
-          "description": "Outlook message ID. Returned by `list-mail-messages` or `list-mail-folder-messages`."
+          "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            }
+          ],
+          "description": "Outlook message ID. Returned by `list-mail-messages` or `list-mail-folder-messages`. Accepts `--id` as an alias."
+        },
+        {
+          "name": "inline-images",
+          "key": "inlineImages",
+          "required": false,
+          "description": "Pass `--inline-images false` to skip the per-image bytes fetch + base64 embedding. Default is `true` (embed). Disabling cuts the response size dramatically on emails with several inline images (a 6 KB body with 6 inline images shipped at ~36 KB by default; with `--inline-images false` it stays close to 6 KB). The body keeps raw `cid:<contentId>` references and the inline images surface in the file-attachments list instead, so the LLM caller can still see what is there and fetch any specific image via `get-mail-attachment` on demand."
+        },
+        {
+          "name": "keep-quoted",
+          "key": "keepQuoted",
+          "required": false,
+          "description": "Quoted reply chains and forwarded-message blocks are stripped by default (they duplicate content already present in earlier messages and inflate the context budget). The stripped tail is replaced with a single visible marker naming this flag, so nothing is removed silently. Pass `--keep-quoted true` to preserve the full body. Only well-known structural markers are cut: in HTML bodies Outlook `divRplyFwdMsg` / `appendonsend` / `stopSpelling` and Gmail `gmail_quote`; in plain-text bodies the `Original Message` banner, the `On … wrote:` attribution line, and leading `>` quote lines.",
+          "argumentHint": {
+            "kind": "magicValue",
+            "values": [
+              "true",
+              "false"
+            ]
+          }
         }
       ],
       "example": "ask-marcel convert-mail-to-markdown --message-id 'AAMkAD...'",
-      "responseShape": "`{ contentType: \"text/markdown\", size, text, note? }` — headers + turndown-rendered body + (when present) a file-attachments list. The optional `note` carries a partial-success hint when the attachments-metadata fetch fails after the body succeeded."
+      "responseShape": "`{ contentType: \"text/markdown\", size, text, note? }` — headers + turndown-rendered body + (when present) a file-attachments list. The optional `note` carries a partial-success hint when the attachments-metadata fetch fails after the body succeeded, and/or a flag that a quoted reply chain was stripped (use `--keep-quoted true` to include it).",
+      "producesBytes": true
+    },
+    {
+      "name": "create-mail-draft",
+      "summary": "Create a new mail draft. POST /me/messages (or /me/mailFolders/{id}/messages when --mail-folder-id is set). The draft is saved in the Drafts folder (or the specified folder) and can be sent later via the Outlook client or Graph sendMail. Recipients are comma-separated email addresses. Returns the created message object with its id — use this id with update-mail-draft to modify the draft before sending.",
+      "category": "mail",
+      "graphMethod": "POST",
+      "graphPathTemplate": "/me/messages (or /me/mailFolders/{mail-folder-id}/messages)",
+      "graphDocsUrl": "https://learn.microsoft.com/en-us/graph/api/user-post-messages",
+      "options": [
+        {
+          "name": "subject",
+          "key": "subject",
+          "required": true,
+          "description": "Email subject line."
+        },
+        {
+          "name": "body-content",
+          "key": "bodyContent",
+          "required": true,
+          "description": "Email body content. Plain text by default; pass --body-content-type HTML for rich text."
+        },
+        {
+          "name": "body-content-type",
+          "key": "bodyContentType",
+          "required": false,
+          "description": "Body format: Text (default) or HTML.",
+          "argumentHint": {
+            "kind": "magicValue",
+            "values": [
+              "Text",
+              "HTML"
+            ]
+          }
+        },
+        {
+          "name": "to-recipients",
+          "key": "toRecipients",
+          "required": true,
+          "description": "Comma-separated list of recipient email addresses (e.g. \"alice@example.com,bob@example.com\")."
+        },
+        {
+          "name": "cc-recipients",
+          "key": "ccRecipients",
+          "required": false,
+          "description": "Comma-separated list of CC recipient email addresses."
+        },
+        {
+          "name": "bcc-recipients",
+          "key": "bccRecipients",
+          "required": false,
+          "description": "Comma-separated list of BCC recipient email addresses."
+        },
+        {
+          "name": "importance",
+          "key": "importance",
+          "required": false,
+          "description": "Email importance: Low, Normal (default), or High.",
+          "argumentHint": {
+            "kind": "magicValue",
+            "values": [
+              "Low",
+              "Normal",
+              "High"
+            ]
+          }
+        },
+        {
+          "name": "mail-folder-id",
+          "key": "mailFolderId",
+          "required": false,
+          "description": "Target folder ID to create the draft in. Defaults to the Drafts folder. Source from list-mail-folders.",
+          "argumentHint": {
+            "kind": "idOrName"
+          }
+        }
+      ],
+      "example": "ask-marcel create-mail-draft --subject \"Q3 Report\" --body-content \"Please review the attached report.\" --to-recipients \"alice@example.com,bob@example.com\" --importance High",
+      "responseShape": "The created Microsoft Graph message object: `{ id, subject, body, from, toRecipients, ccRecipients, bccRecipients, receivedDateTime, isDraft, … }`. The `id` field is the draft message ID — use it with `update-mail-draft` to modify before sending.",
+      "bodyTemplate": "{ subject: '{subject}', body: { contentType: '{body-content-type}', content: '{body-content}' }, toRecipients: '{to-recipients}', ccRecipients: '{cc-recipients}', bccRecipients: '{bcc-recipients}', importance: '{importance}' }",
+      "mutates": true
     },
     {
       "name": "download-drive-item-as-markdown",
-      "summary": "Download a OneDrive / SharePoint file converted to markdown via local conversion pipelines. Supported: docx (mammoth → turndown, with inline images as data: URIs and tables as GFM pipe tables), xlsx (one markdown table per sheet via sheetjs), csv (rendered as a markdown table), plus plain-text passthrough (txt/md/html/json/yaml/log/xml/etc.) — the bytes are followed through any CDN redirect and returned inline as `{ contentType: \"text/plain\", size, text }` so the LLM never needs a separate fetch step. Loop/Fluid/Whiteboard files use Graph `?format=html` (the four inputs Microsoft documents — https://learn.microsoft.com/en-us/graph/api/driveitem-get-content-format). For pptx use `download-drive-item-as-pdf` — Graph PDF preserves slide layout, and a vision-capable LLM reads it more reliably than flattened bullets. For pdf/rtf/odt/etc. also use `download-drive-item-as-pdf` — Graph `?format=pdf` accepts 38 input extensions.",
+      "summary": "Download a OneDrive / SharePoint file converted to markdown via local conversion pipelines. Supported: docx (mammoth → turndown; embedded images are replaced with `[image]` placeholders by default — pass `--inline-images true` to embed them as base64 `data:` URIs, or pull the full-resolution originals with `extract-drive-item-images`; tables become GFM pipe tables), xlsx (one markdown table per sheet via sheetjs; any sheet whose used range exceeds the `--max-cells` cap, default 50 000, is summarised with a band-by-band read hint instead of a multi-hundred-MB table), csv (rendered as a markdown table), odt/ods/odp (OpenDocument body walked from content.xml — headings, lists, tables, named sheets, per-slide text, including style-hidden content), plus plain-text passthrough (txt/md/html/json/yaml/log/xml/etc.) — the bytes are followed through any CDN redirect and returned inline as `{ contentType: \"text/plain\", size, text }` so the LLM never needs a separate fetch step. Loop/Fluid/Whiteboard files use Graph `?format=html` (the four inputs Microsoft documents — https://learn.microsoft.com/en-us/graph/api/driveitem-get-content-format). pptx is flattened to per-slide text (titles, bullets, text-box / table text, with speaker notes inline) as `## Slide N` sections — document order, not guaranteed visual order; for layout / images / charts, `download-drive-item-as-pdf` + a vision-capable LLM reads the rendered deck better. pdf has its text layer extracted locally (via unpdf) and returned as `{ contentType: \"text/plain\", size, text }`; a scanned / image-only PDF with no text layer points you at `download-drive-item-as-pdf` + a vision model. Legacy OLE Office: .xls (Excel 97-2003) is read by sheetjs (same markdown-table path as .xlsx); .doc (Word 97-2003) is extracted by word-extractor as plain text (body only, no structure); .ppt (PowerPoint 97-2003) has no pure-JS path — use `download-drive-item-as-pdf` first, then a vision model. Outlook .msg (a saved email, also an OLE container) is rendered to markdown — an H1 subject, a From/To/Cc/Date header block, the message body, then an `## Attachments` section where each attachment is converted recursively through this same pipeline (the same way a .zip is unpacked); inline / image attachments are listed with a note. For rtf/etc. use `download-drive-item-as-pdf` — Graph `?format=pdf` accepts 38 input extensions.",
       "category": "drive",
       "graphMethod": "GET",
       "graphPathTemplate": "/drives/{drive-id}/items/{item-id}/content?format=html",
@@ -88,14 +397,47 @@
           "key": "itemId",
           "required": true,
           "description": "driveItem ID of the file to convert. Returned by `list-folder-files` or `search-onedrive-files`."
+        },
+        {
+          "name": "include-metadata",
+          "key": "includeMetadata",
+          "required": false,
+          "description": "Pass `--include-metadata true` to surface the side-channel content the rendered body hides. For docx (`## DOCX metadata`): core/app/custom document properties, people registry, external hyperlinks, comments, tracked changes (insertions + deletions), hidden-formatted text (w:vanish), field instructions (MERGEFIELD / HYPERLINK / DOCVARIABLE), bookmarks. For xlsx (`## Workbook metadata`): core/app/custom properties, external relationships, defined names, hidden / very-hidden sheets, legacy cell comments, threaded comments, persons. For pptx (`## PPTX metadata`): properties, external relationships, slide tags, comment authors + comments (legacy + modern), and per-slide title / speaker notes / hidden flag — returned as a standalone document since pptx has no convertible body (use `download-drive-item-as-pdf` for slide visuals). For OpenDocument (`.odt`/`.ods`/`.odp`, `## OpenDocument metadata`): Dublin Core + ODF properties, keywords, user-defined custom fields — appended after the converted body. Each OOXML family also covers its macro-enabled (`.docm` / `.xlsm` / `.pptm`) and template (`.dotx` / `.xltx` / `.potx`, etc.) variants, with a `### Macros (VBA)` section flagging an embedded `vbaProject.bin`. No-op on other sources.",
+          "argumentHint": {
+            "kind": "magicValue",
+            "values": [
+              "true",
+              "false"
+            ]
+          }
+        },
+        {
+          "name": "inline-images",
+          "key": "inlineImages",
+          "required": false,
+          "description": "Pass `--inline-images true` to embed a docx's images as base64 `data:` URIs (self-contained markdown). Default is `false` — each image becomes an `[image: <alt>]` placeholder that keeps its position in the text without the base64 bloat (a single embedded photo can dwarf the prose). To get the actual pictures, run `extract-drive-item-images` on the same drive/item — it returns the full-resolution, un-cropped originals as files (via `--output-dir`). No-op on non-docx sources (xlsx/csv/odf have no inline images).",
+          "argumentHint": {
+            "kind": "magicValue",
+            "values": [
+              "true",
+              "false"
+            ]
+          }
+        },
+        {
+          "name": "max-cells",
+          "key": "maxCells",
+          "required": false,
+          "description": "Per-sheet cell cap (positive integer; default 50 000) for xlsx sources. A worksheet whose used range (rows × cols) exceeds the cap is rendered as its `## SheetName` header plus a one-line hint pointing at `get-excel-used-range` / `get-excel-range` for band-by-band reads, instead of a full markdown table — a genuinely dense 49 MB workbook otherwise builds a multi-hundred-MB string and OOMs the process. Raise it to force a larger render. No-op on non-xlsx sources."
         }
       ],
       "example": "ask-marcel download-drive-item-as-markdown --drive-id 'b!1234' --item-id '01ABC'",
-      "responseShape": "`{ contentType: \"text/markdown\", size: <chars>, text: \"...\" }` for the locally-converted case (docx/xlsx/csv); `{ contentType: \"text/plain\", size, text }` for plain-text passthrough sources (txt/md/html/etc.) — bytes are inlined whether Graph returns them directly or via a CDN redirect that the CLI follows internally."
+      "responseShape": "`{ contentType: \"text/markdown\", size: <chars>, text: \"...\" }` for the locally-converted case (docx/xlsx/csv/.msg); `{ contentType: \"text/plain\", size, text }` for plain-text passthrough sources (txt/md/html/etc.) — bytes are inlined whether Graph returns them directly or via a CDN redirect that the CLI follows internally.",
+      "producesBytes": true
     },
     {
       "name": "download-drive-item-as-pdf",
-      "summary": "Download a OneDrive / SharePoint file converted to PDF on the fly by Graph (`?format=pdf`). Source must be one of the Office formats Graph supports — doc, docx, ppt, pptx, xls, xlsx, rtf, csv, odp, ods, odt, etc. The command pre-fetches the filename and short-circuits to a raw download in two cases: plain-text source extensions (txt, md, html, json, …) where conversion is meaningless, and `pdf` sources where the source IS already a PDF (Graph’s `?format=pdf` does not list `pdf` in its supported input set — the CDN responds 406 InputFormatNotSupported on `pdf → pdf`). Worst-case wall-clock is two 60s round-trips back-to-back.",
+      "summary": "Download a OneDrive / SharePoint file converted to PDF on the fly by Graph (`?format=pdf`). Source must be one of the Office formats Graph supports — doc, docx, ppt, pptx, xls, xlsx, rtf, csv, odp, ods, odt, etc. The command pre-fetches the filename and short-circuits to a raw download in two cases: plain-text source extensions (txt, md, html, json, …) where conversion is meaningless, and `pdf` sources where the source IS already a PDF (Graph’s `?format=pdf` does not list `pdf` in its supported input set — the CDN responds 406 InputFormatNotSupported on `pdf → pdf`). Worst-case wall-clock is two back-to-back Graph round-trips; the `?format=pdf` transform can run up to the 5-minute request timeout on large or complex sources.",
       "category": "drive",
       "graphMethod": "GET",
       "graphPathTemplate": "/drives/{drive-id}/items/{item-id}/content?format=pdf",
@@ -115,15 +457,19 @@
         }
       ],
       "example": "ask-marcel download-drive-item-as-pdf --drive-id 'b!1234' --item-id '01ABC'",
-      "responseShape": "`{ contentType: \"application/pdf\", size, base64 }` — the PDF bytes, inlined. The CLI follows the SharePoint media-transform redirect internally so the LLM never has to fetch an external URL. Plain-text and pdf sources skip the format=pdf round-trip and return the raw file bytes under the same envelope shape (with their native contentType) plus `passthrough: true` and a `note` explaining why conversion was skipped — the LLM can branch on the flag if it cares whether Graph actually converted. Pair with the global `--output-path` to land the bytes on disk and replace `base64` with `savedTo` for multi-MB PDFs."
+      "responseShape": "`{ contentType: \"application/pdf\", size, base64 }` — the PDF bytes, inlined. The CLI follows the SharePoint media-transform redirect internally so the LLM never has to fetch an external URL. Plain-text and pdf sources skip the format=pdf round-trip and return the raw file bytes under the same envelope shape (with their native contentType) plus `passthrough: true` and a `note` explaining why conversion was skipped — the LLM can branch on the flag if it cares whether Graph actually converted. Pair with the global `--output-path` to land the bytes on disk and replace `base64` with `savedTo` for multi-MB PDFs.",
+      "producesBytes": true
     },
     {
-      "name": "download-drive-item-version-as-markdown",
-      "summary": "Download a *historical version* of a OneDrive / SharePoint file converted to markdown. Same local conversion pipeline as `download-drive-item-as-markdown`: docx via mammoth, xlsx via sheetjs (markdown tables per sheet), csv as a markdown table, plus plain-text passthrough. Uses an elevated Graph token (captured at login from m365.cloud.microsoft / M365ChatClient) for the bytes-fetch, since the Teams web client token cannot fetch historical-version stream content (returns 403 logicalPermissionAccessDenied). For pptx use `download-drive-item-version-as-pdf`. Loop/Fluid/Whiteboard use Graph `?format=html` (the four inputs Microsoft documents).",
+      "name": "download-drive-item-content",
+      "summary": "Download the binary content of a file stored in OneDrive / SharePoint, with the bytes inlined. The CLI follows the Graph 302 → SharePoint media-transform redirect internally so the LLM never has to fetch an external URL. The bytes are CONTENT-SNIFFED, not judged by extension: if they decode as valid UTF-8 they come back as `{contentType: \"text/plain\", size, text}` (avoids ~33% base64 bloat, works for any text file regardless of name); otherwise as `{contentType, size, base64}`. A binary file that happens to be named `.txt` is returned faithfully as base64 — never silently corrupted into `�` by a forced text decode.",
       "category": "drive",
+      "commandAliases": [
+        "download-onedrive-file-content"
+      ],
       "graphMethod": "GET",
-      "graphPathTemplate": "/drives/{drive-id}/items/{item-id}/versions/{version-id}/content?format=html",
-      "graphDocsUrl": "https://learn.microsoft.com/en-us/graph/api/driveitemversion-get-content",
+      "graphPathTemplate": "/drives/{drive-id}/items/{item-id}/content",
+      "graphDocsUrl": "https://learn.microsoft.com/en-us/graph/api/driveitem-get-content",
       "options": [
         {
           "name": "drive-id",
@@ -135,24 +481,19 @@
           "name": "item-id",
           "key": "itemId",
           "required": true,
-          "description": "driveItem ID of the file. Returned by `list-folder-files` or `search-onedrive-files`."
-        },
-        {
-          "name": "version-id",
-          "key": "versionId",
-          "required": true,
-          "description": "driveItemVersion ID. Returned by `ask-marcel list-drive-item-versions`. Pick a non-current version (the first entry is the live file and Graph rejects this endpoint for it)."
+          "description": "driveItem ID of the file to download. Returned by `ask-marcel list-folder-files` (works on SharePoint library drives too) or `search-onedrive-files`."
         }
       ],
-      "example": "ask-marcel download-drive-item-version-as-markdown --drive-id 'b!1234' --item-id '01ABC' --version-id '4.0'",
-      "responseShape": "`{ contentType: \"text/markdown\", size: <chars>, text: \"...\" }` for the converted case; raw-bytes envelope for plain-text source extensions."
+      "example": "ask-marcel download-drive-item-content --drive-id 'b!1234' --item-id '01ABC'",
+      "responseShape": "`{ contentType: \"text/plain\", size, text }` when the bytes decode as valid UTF-8; `{ contentType, size, base64 }` otherwise (binary, or non-UTF-8-encoded text). Pair with the global `--output-path <path>` flag to land the bytes on disk and replace the inline field with `savedTo` for multi-MB files.",
+      "producesBytes": true
     },
     {
-      "name": "download-drive-item-version-as-pdf",
-      "summary": "Convert a *historical version* of a OneDrive / SharePoint file to PDF and return the bytes inline. Same shape as `download-drive-item-as-pdf` plus a `--version-id`. The CLI uses an ODSP-elevated token (M365ChatClient identity captured at login) for both the Graph call and the CDN-redirect follow, so the LLM never has to fetch an external URL. Plain-text source extensions and `pdf` sources short-circuit to a raw-bytes return. Note: Graph's `?format=pdf` sometimes serves the *current* version through this endpoint, but not reliably — audit v1.0.0 §D4 saw it fall back to raw source bytes (`passthrough: true`) even for the current version on the test tenant. For the current version always use `download-drive-item-as-pdf` so you don't depend on this quirk. When the response carries `passthrough: true`, the bytes are the source file (not a PDF); save them with the source extension, not `.pdf` — the global output-path flag refuses the mismatch (audit §B4).",
+      "name": "download-drive-item-version",
+      "summary": "Download a *non-current* historical version of a OneDrive / SharePoint file. `--format original` (default) returns the raw bytes — Graph refuses to serve the current version through this endpoint with \"You cannot get the content of the current version\"; for the current version use `download-drive-item-content`. `--format pdf` runs Graph `?format=pdf` for Office docs; plain-text and `pdf` sources short-circuit to raw bytes with `passthrough: true` + a note (Graph rejects `pdf → pdf` with InputFormatNotSupported). `--format markdown` runs the local conversion pipeline (mammoth for docx, sheetjs for xlsx, csv → table, odt/ods/odp via content.xml, plain-text passthrough). All three formats use an M365ChatClient-elevated Graph token (captured at login from m365.cloud.microsoft) — the Teams web client token returns 403 logicalPermissionAccessDenied on historical-version stream content. The CLI follows the SharePoint streamContent redirect internally so the LLM never has to fetch an external URL. Audit v1.0.0 §D4 caveat for `--format pdf`: Graph sometimes silently falls back to raw source bytes for the current version (which Graph occasionally serves through this endpoint) — when the response carries `passthrough: true`, save with the source extension, not `.pdf` (the global output-path flag refuses the mismatch).",
       "category": "drive",
       "graphMethod": "GET",
-      "graphPathTemplate": "/drives/{drive-id}/items/{item-id}/versions/{version-id}/content?format=pdf",
+      "graphPathTemplate": "/drives/{drive-id}/items/{item-id}/versions/{version-id}/content",
       "graphDocsUrl": "https://learn.microsoft.com/en-us/graph/api/driveitemversion-get-content",
       "options": [
         {
@@ -171,19 +512,48 @@
           "name": "version-id",
           "key": "versionId",
           "required": true,
-          "description": "driveItemVersion ID. Returned by `ask-marcel list-drive-item-versions`. Pick a non-current version — the first entry (e.g. `12.0`) is the live file and Graph rejects this endpoint for it; use `value[1]` or older."
+          "description": "driveItemVersion ID. Returned by `ask-marcel list-drive-item-versions`. Use the `id` field of an entry under `value[]`. Pick a non-current version — the first entry (e.g. `12.0`) is the live file and Graph rejects this endpoint for it; use `value[1]` or older."
+        },
+        {
+          "name": "format",
+          "key": "format",
+          "required": false,
+          "description": "Output format. `original` (default) returns the raw historical-version bytes. `pdf` runs Graph `?format=pdf` for Office sources (docx/pptx/xlsx) — plain-text and pdf sources short-circuit to raw bytes with `passthrough: true`. `markdown` runs the local conversion pipeline (mammoth/sheetjs/csv/odf/plain-text). All formats inline the bytes; pair with the global `--output-path` to land them on disk.",
+          "argumentHint": {
+            "kind": "magicValue",
+            "values": [
+              "original",
+              "pdf",
+              "markdown"
+            ]
+          }
+        },
+        {
+          "name": "include-metadata",
+          "key": "includeMetadata",
+          "required": false,
+          "description": "Pass `--include-metadata true` to surface side-channel content (only meaningful with `--format markdown` AND a docx / xlsx / pptx / odt / ods / odp source — silently ignored otherwise). docx → `## DOCX metadata` (properties, people, hyperlinks, comments, tracked changes, hidden text, fields, bookmarks); xlsx → `## Workbook metadata` (properties, external relationships, defined names, hidden / very-hidden sheets, cell + threaded comments, persons); pptx → `## PPTX metadata` (properties, external relationships, slide tags, comment authors + comments, per-slide title / speaker notes / hidden flag); odt/ods/odp → `## OpenDocument metadata` (Dublin Core + ODF properties, keywords, user-defined fields). Each OOXML family covers its macro-enabled and template variants too, with a `### Macros (VBA)` section flagging an embedded `vbaProject.bin`.",
+          "argumentHint": {
+            "kind": "magicValue",
+            "values": [
+              "true",
+              "false"
+            ]
+          }
         }
       ],
-      "example": "ask-marcel download-drive-item-version-as-pdf --drive-id 'b!1234' --item-id '01ABC' --version-id '4.0'",
-      "responseShape": "`{ contentType: \"application/pdf\", size, base64 }` — the historical-version PDF bytes, inlined. Plain-text and pdf sources skip the format=pdf round-trip and return the raw file bytes under the same envelope shape with `passthrough: true` + a `note` so the caller can tell conversion was deliberately skipped. **If Graph silently falls back to raw bytes** (some historical versions of pptx/docx — verified live), the response also carries `passthrough: true` + a sharp note saying the bytes are the source, NOT a PDF — save them with the source extension, not `.pdf`. Pair with the global `--output-path` to land the bytes on disk and replace `base64` with `savedTo`."
+      "example": "ask-marcel download-drive-item-version --drive-id 'b!1234' --item-id '01ABC' --version-id '4.0' --format pdf",
+      "responseShape": "`--format original` & `--format pdf`: `{ contentType, size, base64 }` — the bytes, inlined. `--format pdf` adds `passthrough: true` + `note` when Graph short-circuits (plain-text or pdf source) OR silently falls back to raw source bytes — in that case save with the source extension, NOT `.pdf` (the global output-path flag refuses the mismatch). `--format markdown`: `{ contentType: \"text/markdown\", size: <chars>, text: \"...\" }` for the converted case; raw-bytes envelope for plain-text source extensions. Pair with the global `--output-path` to land bytes on disk and replace `base64`/`text` with `savedTo` for multi-MB versions.",
+      "producesBytes": true,
+      "needsElevatedToken": true
     },
     {
-      "name": "download-drive-item-version-content",
-      "summary": "Download the bytes of a *non-current* historical version of a OneDrive / SharePoint file, inlined. Graph refuses to serve the current version through this endpoint with \"You cannot get the content of the current version\" — for the current version use `download-onedrive-file-content`. The CLI follows the SharePoint streamContent redirect internally using an M365ChatClient-elevated token (captured at login) so the LLM never has to fetch an external URL.",
+      "name": "extract-drive-item-images",
+      "summary": "Extract the embedded images from a OneDrive / SharePoint document. For docx / xlsx / pptx (and their macro-enabled / template variants) it reads the OOXML media parts directly (png/jpg/gif/bmp/tiff/webp/svg) — including original full-resolution / un-cropped originals and images on hidden slides the rendered view never shows. For a pdf it walks every page via unpdf and re-encodes each painted image as PNG (note: page-oriented — it captures images as painted on each page, but NOT layer-hidden/unpainted XObjects or the full uncropped original behind a clipped image). Pair with the global output-dir flag to write every image to a folder; otherwise the bytes ride back base64-encoded in the response. svg rides back as its XML source (which carries the diagram text labels); legacy vector (emf/wmf) and audio/video are skipped. For any other format the command returns a 415 pointing at `download-drive-item-content`.",
       "category": "drive",
       "graphMethod": "GET",
-      "graphPathTemplate": "/drives/{drive-id}/items/{item-id}/versions/{version-id}/content",
-      "graphDocsUrl": "https://learn.microsoft.com/en-us/graph/api/driveitemversion-get-content",
+      "graphPathTemplate": "/drives/{drive-id}/items/{item-id}/content",
+      "graphDocsUrl": "https://learn.microsoft.com/en-us/graph/api/driveitem-get-content",
       "options": [
         {
           "name": "drive-id",
@@ -195,21 +565,60 @@
           "name": "item-id",
           "key": "itemId",
           "required": true,
-          "description": "driveItem ID of the file. Returned by `list-folder-files` or `search-onedrive-files`."
+          "description": "driveItem ID of the pdf / docx / xlsx / pptx file. Returned by `list-folder-files` or `search-onedrive-files`."
+        }
+      ],
+      "example": "ask-marcel extract-drive-item-images --drive-id 'b!1234' --item-id '01ABC' --output-dir ./deck-images",
+      "responseShape": "`{ count, media: [{ path, contentType, sizeBytes, base64 }] }`. `path` is the source part path — `ppt/media/image3.png` for OOXML, `pdf/page2/<key>.png` for PDF (every PDF image is re-encoded as PNG). Pair with the global `--output-dir <dir>` to write each image to that folder — the response then replaces each `base64` with `savedTo: <dir>/<filename>` (the part path is flattened, e.g. `pdf_page2_Im0.png`). `count: 0` with an empty `media` array means the document embeds no extractable images (after the emf/wmf/audio/video filter).",
+      "producesMedia": true
+    },
+    {
+      "name": "extract-local-file-images",
+      "summary": "Extract the embedded images from a file ON DISK — the local sibling of `extract-drive-item-images`, and like `convert-local-file` it never calls Microsoft Graph (works offline, no login). Same per-extension dispatch: docx / xlsx / pptx (and their macro-enabled / template variants) have their OOXML media parts read directly (png/jpg/gif/bmp/tiff/webp/svg — full-resolution originals, including images on hidden slides); a pdf is walked page by page via unpdf with each painted image re-encoded as PNG. Two flows only this command completes: a Graph-rendered PDF saved locally (legacy `.ppt` → `download-drive-item-as-pdf` with the global output-path flag → this command pulls the slide images for OCR), and Office files unpacked from a local archive. Pair with the global output-dir flag to write every image to a folder; otherwise the bytes ride back base64-encoded. Any other extension returns a 415 naming the local ways out.",
+      "category": "meta",
+      "graphMethod": "GET",
+      "graphPathTemplate": "(local) reads {path} from the local filesystem; not a Graph endpoint",
+      "graphDocsUrl": "https://learn.microsoft.com/en-us/graph/",
+      "options": [
+        {
+          "name": "path",
+          "key": "path",
+          "required": true,
+          "description": "Filesystem path of the pdf / docx / xlsx / pptx file to extract from (absolute, or relative to the current working directory). E.g. `/tmp/deck.pdf`, `./report.docx`."
+        }
+      ],
+      "example": "ask-marcel extract-local-file-images --path /tmp/deck.pdf --output-dir ./deck-images",
+      "responseShape": "`{ count, media: [{ path, contentType, sizeBytes, base64 }] }`. `path` is the source part path — `ppt/media/image3.png` for OOXML, `pdf/page2/<key>.png` for PDF (every PDF image is re-encoded as PNG). Pair with the global `--output-dir <dir>` to write each image to that folder — the response then replaces each `base64` with `savedTo: <dir>/<filename>` (the part path is flattened, e.g. `pdf_page2_Im0.png`). `count: 0` with an empty `media` array means the document embeds no extractable images (after the emf/wmf/audio/video filter). A missing file returns api_error 404 with the path.",
+      "producesMedia": true
+    },
+    {
+      "name": "extract-mail-attachment-images",
+      "summary": "Extract the embedded images from an Outlook mail attachment that is a pdf or a docx / xlsx / pptx (and their macro-enabled / template variants). OOXML reads the media parts directly (png/jpg/gif/bmp/tiff/webp/svg), including full-resolution / un-cropped originals and images on hidden slides; pdf walks every page via unpdf and re-encodes each painted image as PNG (page-oriented — not layer-hidden/unpainted/uncropped originals). fileAttachment decodes the inline bytes; referenceAttachment resolves via /shares/{token}/driveItem and fetches the content. Pair with the global output-dir flag to write every image to a folder; otherwise the bytes ride back base64-encoded. svg rides back as its XML source (which carries the diagram text labels); legacy vector (emf/wmf) and audio/video are skipped. itemAttachment and unsupported formats return a 415.",
+      "category": "mail",
+      "graphMethod": "GET",
+      "graphPathTemplate": "/me/messages/{message-id}/attachments/{attachment-id}",
+      "graphDocsUrl": "https://learn.microsoft.com/en-us/graph/api/attachment-get",
+      "options": [
+        {
+          "name": "message-id",
+          "key": "messageId",
+          "required": true,
+          "description": "Outlook message ID. Returned by `list-mail-messages` or `list-mail-folder-messages`."
         },
         {
-          "name": "version-id",
-          "key": "versionId",
+          "name": "attachment-id",
+          "key": "attachmentId",
           "required": true,
-          "description": "driveItemVersion ID. Returned by `ask-marcel list-drive-item-versions`. Use the `id` field of an entry under `value[]`. Pick a non-current version — the first entry (e.g. `12.0`) is the live file and Graph rejects this endpoint for it; use `value[1]` or older."
+          "description": "Attachment ID inside that message. Returned by `list-mail-attachments`."
         }
       ],
-      "example": "ask-marcel download-drive-item-version-content --drive-id 'b!1234' --item-id '01ABC' --version-id '4.0'",
-      "responseShape": "`{ contentType, size, base64 }` — the historical-version bytes, inlined. Pair with the global `--output-path <path>` flag to land the bytes on disk and replace `base64` with `savedTo` for multi-MB versions."
+      "example": "ask-marcel extract-mail-attachment-images --message-id 'AAMkAD...' --attachment-id 'AAMkAD...attach1' --output-dir ./att-images",
+      "responseShape": "`{ count, media: [{ path, contentType, sizeBytes, base64 }] }`. `path` is the in-package part path (e.g. `ppt/media/image3.png`). Pair with the global `--output-dir <dir>` to write each image to that folder — the response then replaces each `base64` with `savedTo` (the part path is flattened, e.g. `pdf_page2_Im0.png`). `count: 0` means the attachment embeds no extractable images (after the emf/wmf/audio/video filter).",
+      "producesMedia": true
     },
     {
-      "name": "download-onedrive-file-content",
-      "summary": "Download the binary content of a file stored in OneDrive / SharePoint, with the bytes inlined. The CLI follows the Graph 302 → SharePoint media-transform redirect internally so the LLM never has to fetch an external URL. Pre-checks the filename: if it matches the plain-text set (txt/md/html/json/yaml/log/xml/etc.), decodes the bytes as UTF-8 and returns `{contentType: \"text/plain\", size, text}` instead of base64 — avoids ~33% bloat on text payloads.",
+      "name": "extract-sharepoint-links-in-documents",
+      "summary": "Find every `*.sharepoint.com` URL embedded in a Word / Excel / PowerPoint or OpenDocument file on OneDrive or SharePoint and resolve each one to its driveItem (driveId, itemId, name, webUrl) so the agent can feed those into `download-drive-item-as-pdf` / `-as-markdown` etc. The document sibling of `extract-sharepoint-links-in-mail`. For OOXML (.docx/.xlsx/.pptx) it reads external hyperlinks from the package’s relationship parts (`_rels/*.rels`, `TargetMode=\"External\"`); for OpenDocument (.odt/.ods/.odp) it reads the inline `xlink:href` links in content.xml / styles.xml — either way it catches links wherever they live (body text, headers/footers, cell formulas, slide shapes). Read-only — no conversion happens here. Capped at 25 unique URLs per call (returns `truncated: true` and `skippedCount` when there are more); duplicates are deduplicated; per-link errors are captured inside each entry instead of failing the whole call. Non-zip inputs (pdf/images) return an api_error.",
       "category": "drive",
       "graphMethod": "GET",
       "graphPathTemplate": "/drives/{drive-id}/items/{item-id}/content",
@@ -219,17 +628,17 @@
           "name": "drive-id",
           "key": "driveId",
           "required": true,
-          "description": "Microsoft Graph drive ID. Returned by `ask-marcel list-drives`."
+          "description": "Microsoft Graph drive ID. Use `ask-marcel list-drives` for the personal OneDrive, or `ask-marcel list-sharepoint-site-drives --site-id <id>` for a SharePoint document library."
         },
         {
           "name": "item-id",
           "key": "itemId",
           "required": true,
-          "description": "driveItem ID of the file to download. Returned by `ask-marcel list-folder-files` or `search-onedrive-files`."
+          "description": "driveItem ID of the .docx/.xlsx/.pptx or .odt/.ods/.odp file. Returned by `list-folder-files` or `search-onedrive-files`."
         }
       ],
-      "example": "ask-marcel download-onedrive-file-content --drive-id 'b!1234' --item-id '01ABC'",
-      "responseShape": "`{ contentType: \"text/plain\", size, text }` for plain-text source extensions; `{ contentType, size, base64 }` for everything else. Pair with the global `--output-path <path>` flag to land the bytes on disk and replace the inline field with `savedTo` for multi-MB files."
+      "example": "ask-marcel extract-sharepoint-links-in-documents --drive-id 'b!1234' --item-id '01ABC'",
+      "responseShape": "`{ driveId, itemId, links: [{ url, driveId, itemId, name, webUrl } | { url, error }], truncated, skippedCount }` — one entry per unique SharePoint URL found in the document’s external relationships."
     },
     {
       "name": "extract-sharepoint-links-in-mail",
@@ -243,12 +652,50 @@
           "name": "message-id",
           "key": "messageId",
           "required": true,
-          "description": "Outlook message ID. Returned by `list-mail-messages` or `list-mail-folder-messages`."
+          "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            }
+          ],
+          "description": "Outlook message ID. Returned by `list-mail-messages` or `list-mail-folder-messages`. Accepts `--id` as an alias."
         }
       ],
       "example": "ask-marcel extract-sharepoint-links-in-mail --message-id 'AAMkADk0...'",
       "responseShape": "`{ messageId, subject, links: [{ url, driveId, itemId, name, webUrl } | { url, error }], truncated, skippedCount }` — one entry per unique SharePoint URL found in the body, ordered by first occurrence."
     },
+    {
+      "name": "find-chats-with-user",
+      "summary": "Find every Microsoft Teams chat that includes a member matching `--name` (substring search across display-name, email, given-name, surname, MRI, and object-id). Both sides are Unicode-folded (NFD + combining-mark strip) and lowercased before comparison, so `--name Jane` matches `Jane DOE` AND `jane.doe@example.com` AND `JANE` — important because a dual-identity user often carries the accented display-name on one identity and the un-accented email on the other. Walks the paginated chat-list substrate up to `--max-pages` and returns matching chats with their `matchedMembers[]`. Collapses the canonical \"all conversations with person X\" workflow into a single call AND surfaces dual-identity people (e.g. someone with both an org MRI and a guest-tenant MRI). **Best-effort, may break on Microsoft client updates** — the chat substrate is not in the public Microsoft Graph API.",
+      "category": "chats",
+      "graphMethod": "GET",
+      "graphPathTemplate": "https://teams.microsoft.com/api/csa/{region}/api/v3/teams/users/me/chats",
+      "graphDocsUrl": "https://learn.microsoft.com/en-us/graph/api/chat-list",
+      "options": [
+        {
+          "name": "name",
+          "key": "name",
+          "required": true,
+          "description": "Substring to search across each chat member's `displayName`, `email`, `userPrincipalName`, `givenName`, `surname`, `mri`, `objectId`, and `jobTitle`. Both the query and each field are NFD-normalized + diacritics-stripped + lowercased before comparison, so `Jane` ↔ `Jane` ↔ `JANE` are equivalent and a query for the accented name still matches a member whose displayName is the un-accented email. Use the full name or an unambiguous fragment. Quoted multi-word values match on the joined substring, not per-token."
+        },
+        {
+          "name": "max-pages",
+          "key": "maxPages",
+          "required": false,
+          "description": "Safety cap on the chat-list walk (positive integer; default 10). Each page returns up to `--page-size` chats. Raise carefully on busy accounts — every page is one HTTP round-trip."
+        },
+        {
+          "name": "page-size",
+          "key": "pageSize",
+          "required": false,
+          "description": "Chats per page (positive integer; default 100, same value Teams web uses). Server may silently cap."
+        }
+      ],
+      "example": "ask-marcel find-chats-with-user --name 'Jane DOE'",
+      "responseShape": "`{ name, matches: [{ chatId, title, chatType, threadType, memberCount, lastMessageAt?, matchedMembers: [{ mri, displayName, email, userSubType }] }], matchCount, pagesFetched, chatsScanned, hasMore, nextContinuationToken? }`. `matchedMembers` always carries the matching entries' identifying fields — pass `chatId` into `list-teams-chat-history` to read message bodies. `hasMore: true` means `--max-pages` was hit before exhausting the chat list; chain with the existing `--continuation-token` flag on `list-teams-chats-with-messages` if you need to scan further (this command does not advertise a `--continuation-token` because resuming a partial search is rare; users either widen `--max-pages` or refine `--name`).",
+      "needsSubstrateToken": true,
+      "stability": "experimental"
+    },
     {
       "name": "get-calendar-event",
       "summary": "Fetch a single calendar event by ID from the signed-in user’s default calendar. Pass `--select` to project only the fields you need (the full event body can be large with HTML body and attendee lists).",
@@ -261,6 +708,12 @@
           "name": "event-id",
           "key": "eventId",
           "required": true,
+          "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            }
+          ],
           "description": "Microsoft Graph event ID. Returned by `ask-marcel list-calendar-events` in the `id` field of each event."
         },
         {
@@ -281,7 +734,7 @@
     },
     {
       "name": "get-channel-files-folder",
-      "summary": "Return the SharePoint folder that backs a Teams channel's Files tab. Returned `driveItem` includes `parentReference.driveId` and `id` so you can pivot into `list-folder-files`, `download-onedrive-file-content`, etc., and treat the channel like any other OneDrive folder. Requires that the signed-in user is a member of the channel — restricted channels return `AccessDenied`.",
+      "summary": "Return the SharePoint folder that backs a Teams channel's Files tab. Returned `driveItem` includes `parentReference.driveId` and `id` so you can pivot into `list-folder-files`, `download-drive-item-content`, etc., and treat the channel like any other OneDrive folder. Requires that the signed-in user is a member of the channel — restricted channels return `AccessDenied`.",
       "category": "teams",
       "graphMethod": "GET",
       "graphPathTemplate": "/teams/{team-id}/channels/{channel-id}/filesFolder",
@@ -317,7 +770,7 @@
     },
     {
       "name": "get-chat",
-      "summary": "Return metadata for a single Microsoft Teams chat (1:1, group, or meeting). Returns `id`, `topic`, `chatType`, `lastUpdatedDateTime`, etc. — not the messages (which need `Chat.Read*`). Requires the M365ChatClient elevated token captured at login (the basic Teams web client token lacks `Chat.ReadBasic`).",
+      "summary": "Return metadata for a single Microsoft Teams chat (1:1, group, or meeting). The CLI ships a slim default `--select=id,topic,chatType,createdDateTime,lastUpdatedDateTime`; pass `--select id,topic,webUrl,onlineMeetingInfo` (or any other comma-separated field list) to widen. Pass `--expand members` to inline membership. Returns metadata only — not the messages (which need `Chat.Read*`). Requires the M365ChatClient elevated token captured at login (the basic Teams web client token lacks `Chat.ReadBasic`).",
       "category": "chats",
       "graphMethod": "GET",
       "graphPathTemplate": "/chats/{chat-id}",
@@ -327,15 +780,34 @@
           "name": "chat-id",
           "key": "chatId",
           "required": true,
+          "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            }
+          ],
           "description": "Microsoft Teams chat ID, e.g. `19:abc...@thread.v2`. Returned by `list-chats`."
+        },
+        {
+          "name": "select",
+          "key": "select",
+          "required": false,
+          "description": "OData $select: comma-separated list of fields to include in each item (e.g. `id,subject,from`). May shrink payloads dramatically — Graph honors $select on most endpoints, but some collections (notably `/me/mailboxSettings`, `/me/outlook/masterCategories`, `/me/mailFolders/inbox/messageRules`) silently ignore it and always return the full resource. Bogus field names are silently dropped by Graph — if a field you asked for is missing from the response, double-check the spelling against the documented `responseShape`."
+        },
+        {
+          "name": "expand",
+          "key": "expand",
+          "required": false,
+          "description": "OData $expand: navigation properties to include inline (e.g. `attachments`). Increases response size; use sparingly."
         }
       ],
       "example": "ask-marcel get-chat --chat-id '19:abc...@thread.v2'",
-      "responseShape": "single Microsoft Graph `chat` resource"
+      "responseShape": "single Microsoft Graph `chat` resource projected to the default `--select` set (or, when overridden, to the requested fields). `--expand members` adds an inline `members[]` array.",
+      "needsElevatedToken": true
     },
     {
       "name": "get-current-user",
-      "summary": "Return the signed-in user’s Microsoft Graph profile (id, displayName, mail, jobTitle, etc.). Pass `--select id,displayName,mail` to slim the payload to just the fields you need.",
+      "summary": "Return the signed-in user's Microsoft Graph profile. The CLI ships a slim default `--select=id,displayName,mail,userPrincipalName,jobTitle,officeLocation,mobilePhone` covering the common identity fields. Pass `--select id,displayName,givenName,surname,preferredLanguage,...` to widen, or `--select '*'` for everything Graph returns.",
       "category": "user",
       "graphMethod": "GET",
       "graphPathTemplate": "/me",
@@ -354,8 +826,8 @@
           "description": "OData $expand: navigation properties to include inline (e.g. `attachments`). Increases response size; use sparingly."
         }
       ],
-      "example": "ask-marcel get-current-user --select id,displayName,mail",
-      "responseShape": "single Microsoft Graph `user` resource (or projection of the requested `--select` fields)"
+      "example": "ask-marcel get-current-user",
+      "responseShape": "single Microsoft Graph `user` resource projected to the default `--select` set (or, when overridden, to the requested fields)"
     },
     {
       "name": "get-drive-delta",
@@ -369,7 +841,7 @@
           "name": "drive-id",
           "key": "driveId",
           "required": true,
-          "description": "Microsoft Graph drive ID. Returned by `ask-marcel list-drives`."
+          "description": "Microsoft Graph drive ID. Use `ask-marcel list-drives` for the personal OneDrive, or `ask-marcel list-sharepoint-site-drives --site-id <id>` for a SharePoint document library."
         },
         {
           "name": "item-id",
@@ -430,7 +902,7 @@
           "name": "drive-id",
           "key": "driveId",
           "required": true,
-          "description": "Microsoft Graph drive ID. Returned by `ask-marcel list-drives`."
+          "description": "Microsoft Graph drive ID. Use `ask-marcel list-drives` for the personal OneDrive, or `ask-marcel list-sharepoint-site-drives --site-id <id>` for a SharePoint document library."
         },
         {
           "name": "item-id",
@@ -466,7 +938,7 @@
           "name": "drive-id",
           "key": "driveId",
           "required": true,
-          "description": "OneDrive / SharePoint drive ID."
+          "description": "Microsoft Graph drive ID. Use `ask-marcel list-drives` for the personal OneDrive, or `ask-marcel list-sharepoint-site-drives --site-id <id>` for a SharePoint document library."
         },
         {
           "name": "item-id",
@@ -490,7 +962,7 @@
           "name": "drive-id",
           "key": "driveId",
           "required": true,
-          "description": "OneDrive / SharePoint drive ID."
+          "description": "Microsoft Graph drive ID. Use `ask-marcel list-drives` for the personal OneDrive, or `ask-marcel list-sharepoint-site-drives --site-id <id>` for a SharePoint document library."
         },
         {
           "name": "item-id",
@@ -526,7 +998,7 @@
           "name": "drive-id",
           "key": "driveId",
           "required": true,
-          "description": "OneDrive / SharePoint drive ID."
+          "description": "Microsoft Graph drive ID. Use `ask-marcel list-drives` for the personal OneDrive, or `ask-marcel list-sharepoint-site-drives --site-id <id>` for a SharePoint document library."
         },
         {
           "name": "item-id",
@@ -562,7 +1034,7 @@
           "name": "drive-id",
           "key": "driveId",
           "required": true,
-          "description": "OneDrive / SharePoint drive ID."
+          "description": "Microsoft Graph drive ID. Use `ask-marcel list-drives` for the personal OneDrive, or `ask-marcel list-sharepoint-site-drives --site-id <id>` for a SharePoint document library."
         },
         {
           "name": "item-id",
@@ -641,7 +1113,13 @@
           "name": "drive-id",
           "key": "driveId",
           "required": true,
-          "description": "Microsoft Graph drive ID. Returned by `ask-marcel list-drives` in the `id` field."
+          "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            }
+          ],
+          "description": "Microsoft Graph drive ID. Use `ask-marcel list-drives` for the personal OneDrive, or `ask-marcel list-sharepoint-site-drives --site-id <id>` for a SharePoint document library."
         },
         {
           "name": "select",
@@ -661,7 +1139,7 @@
     },
     {
       "name": "get-drive-special-folder",
-      "summary": "Resolve a OneDrive well-known folder via `--folder-name` (one of `documents`, `photos`, `cameraroll`, `approot`, `music`, `attachments`) without having to navigate from the root. Returns the folder's driveItem (id, name, parentReference, etc.) ready to feed into `list-folder-files` or `download-onedrive-file-content`.",
+      "summary": "Resolve a OneDrive well-known folder via `--folder-name` (one of `documents`, `photos`, `cameraroll`, `approot`, `music`, `attachments`) without having to navigate from the root. Returns the folder's driveItem (id, name, parentReference, etc.) ready to feed into `list-folder-files` or `download-drive-item-content`.",
       "category": "drive",
       "graphMethod": "GET",
       "graphPathTemplate": "/me/drive/special/{folder-name}",
@@ -674,20 +1152,63 @@
           "description": "Well-known folder name. One of: `documents`, `photos`, `cameraroll`, `approot`, `music`, `attachments`. Returns the corresponding driveItem (folder) — use the returned `id` with `list-folder-files` etc."
         },
         {
-          "name": "select",
-          "key": "select",
-          "required": false,
-          "description": "OData $select: comma-separated list of fields to include in each item (e.g. `id,subject,from`). May shrink payloads dramatically — Graph honors $select on most endpoints, but some collections (notably `/me/mailboxSettings`, `/me/outlook/masterCategories`, `/me/mailFolders/inbox/messageRules`) silently ignore it and always return the full resource. Bogus field names are silently dropped by Graph — if a field you asked for is missing from the response, double-check the spelling against the documented `responseShape`."
+          "name": "select",
+          "key": "select",
+          "required": false,
+          "description": "OData $select: comma-separated list of fields to include in each item (e.g. `id,subject,from`). May shrink payloads dramatically — Graph honors $select on most endpoints, but some collections (notably `/me/mailboxSettings`, `/me/outlook/masterCategories`, `/me/mailFolders/inbox/messageRules`) silently ignore it and always return the full resource. Bogus field names are silently dropped by Graph — if a field you asked for is missing from the response, double-check the spelling against the documented `responseShape`."
+        },
+        {
+          "name": "expand",
+          "key": "expand",
+          "required": false,
+          "description": "OData $expand: navigation properties to include inline (e.g. `attachments`). Increases response size; use sparingly."
+        }
+      ],
+      "example": "ask-marcel get-drive-special-folder --folder-name 'documents'",
+      "responseShape": "single Microsoft Graph `driveItem` resource (folder)"
+    },
+    {
+      "name": "get-excel-chart-image",
+      "summary": "Render a chart on an Excel worksheet as a PNG (base64). Calls Graph's chart `Image()` function (natural size, aspect-preserving) so a vision-capable LLM can read the plotted data itself — not just the chart's title / position metadata that `list-excel-worksheet-charts` returns. The chart id or name comes from `list-excel-worksheet-charts`.",
+      "category": "excel",
+      "graphMethod": "GET",
+      "graphPathTemplate": "/drives/{drive-id}/items/{item-id}/workbook/worksheets/{worksheet-id}/charts/{chart-id}/Image(width=0,height=0,fittingMode='Fit')",
+      "graphDocsUrl": "https://learn.microsoft.com/en-us/graph/api/chart-image",
+      "options": [
+        {
+          "name": "drive-id",
+          "key": "driveId",
+          "required": true,
+          "description": "Microsoft Graph drive ID. Use `ask-marcel list-drives` for the personal OneDrive, or `ask-marcel list-sharepoint-site-drives --site-id <id>` for a SharePoint document library."
+        },
+        {
+          "name": "item-id",
+          "key": "itemId",
+          "required": true,
+          "description": "driveItem ID of the .xlsx file."
+        },
+        {
+          "name": "worksheet-id",
+          "key": "worksheetId",
+          "required": true,
+          "description": "Worksheet display name (e.g. `Sheet1`) or the worksheet `id` GUID returned by `list-excel-worksheets`.",
+          "argumentHint": {
+            "kind": "idOrName"
+          }
         },
         {
-          "name": "expand",
-          "key": "expand",
-          "required": false,
-          "description": "OData $expand: navigation properties to include inline (e.g. `attachments`). Increases response size; use sparingly."
+          "name": "chart-id",
+          "key": "chartId",
+          "required": true,
+          "description": "Chart name (e.g. `Chart 1`) or `id`, as returned by `list-excel-worksheet-charts`.",
+          "argumentHint": {
+            "kind": "idOrName"
+          }
         }
       ],
-      "example": "ask-marcel get-drive-special-folder --folder-name 'documents'",
-      "responseShape": "single Microsoft Graph `driveItem` resource (folder)"
+      "example": "ask-marcel get-excel-chart-image --drive-id 'b!1234' --item-id '01ABC' --worksheet-id 'Sheet1' --chart-id 'Chart 1' --output-path ./chart.png",
+      "responseShape": "`{ contentType: \"image/png\", size, base64 }` — the rendered chart PNG, inlined. Pair with the global `--output-path <file>` to write the PNG to disk (the response then replaces `base64` with `savedTo`).",
+      "producesBytes": true
     },
     {
       "name": "get-excel-range",
@@ -701,7 +1222,7 @@
           "name": "drive-id",
           "key": "driveId",
           "required": true,
-          "description": "Microsoft Graph drive ID containing the workbook. Returned by `ask-marcel list-drives`."
+          "description": "Microsoft Graph drive ID containing the workbook. Use `ask-marcel list-drives` for the personal OneDrive, or `ask-marcel list-sharepoint-site-drives --site-id <id>` for a SharePoint document library."
         },
         {
           "name": "item-id",
@@ -743,7 +1264,7 @@
           "name": "drive-id",
           "key": "driveId",
           "required": true,
-          "description": "Microsoft Graph drive ID containing the workbook. Returned by `ask-marcel list-drives`."
+          "description": "Microsoft Graph drive ID containing the workbook. Use `ask-marcel list-drives` for the personal OneDrive, or `ask-marcel list-sharepoint-site-drives --site-id <id>` for a SharePoint document library."
         },
         {
           "name": "item-id",
@@ -763,7 +1284,7 @@
     },
     {
       "name": "get-excel-used-range",
-      "summary": "Return the worksheet's used range — the bounding box of every non-empty cell — as a single Excel range. Avoids fetching the entire 1M × 16K-cell sheet when only a small data island is populated.",
+      "summary": "Return the worksheet's used range — the bounding box of every non-empty cell — as a single Excel range. The CLI ships a slim default that strips the redundant `text` / `numberFormat` / `formulas` 2D arrays Graph returns (mostly `\"General\"` repeated cell-by-cell), keeping `address` / `rowCount` / `columnCount` / `values`. Pass `--full true` to return the raw four-array Graph shape. `--max-cells` (default 50 000) caps the size of the projected `values[]`; oversize ranges drop `values` and surface a hint pointing at `get-excel-range` for band-by-band reads. Avoids fetching the entire 1M × 16K-cell sheet when only a small data island is populated.",
       "category": "excel",
       "graphMethod": "GET",
       "graphPathTemplate": "/drives/{drive-id}/items/{item-id}/workbook/worksheets/{worksheet-id}/usedRange()",
@@ -773,7 +1294,7 @@
           "name": "drive-id",
           "key": "driveId",
           "required": true,
-          "description": "OneDrive / SharePoint drive ID."
+          "description": "Microsoft Graph drive ID. Use `ask-marcel list-drives` for the personal OneDrive, or `ask-marcel list-sharepoint-site-drives --site-id <id>` for a SharePoint document library."
         },
         {
           "name": "item-id",
@@ -789,10 +1310,22 @@
           "argumentHint": {
             "kind": "idOrName"
           }
+        },
+        {
+          "name": "full",
+          "key": "full",
+          "required": false,
+          "description": "Pass `--full true` to return the raw Graph `workbookRange` shape with all four 2D arrays (`values`, `text`, `numberFormat`, `formulas`). Default (`--full false`, or omitted) drops the three redundant arrays and ships only `values`. The raw shape on a 3×148 sheet is ~125 KB (most of it duplicated `\"General\"` numberFormat strings); the slim default is ~5-15 KB."
+        },
+        {
+          "name": "max-cells",
+          "key": "maxCells",
+          "required": false,
+          "description": "Cap (positive integer; default 50 000) on the size of the projected `values[]` in slim mode. When the used-range exceeds the cap, the response keeps `address` / `rowCount` / `columnCount` but drops `values[]` and adds `truncated: true` plus a hint pointing at `get-excel-range` for band-by-band reads. Ignored when `--full true` is set (the caller has opted into the full payload regardless of size)."
         }
       ],
       "example": "ask-marcel get-excel-used-range --drive-id 'b!1234' --item-id '01ABC' --worksheet-id 'Sheet1'",
-      "responseShape": "single Microsoft Graph `workbookRange` resource (`address`, `rowCount`, `columnCount`, `values`, `formulas`, etc.)"
+      "responseShape": "Slim projection (default): `{ address, rowCount, columnCount, values, projection: 'slim' }` — `values[]` is the 2D cell-value array. Oversize variant: `{ address, rowCount, columnCount, projection: 'slim', truncated: true, maxCells, hint }` (no `values`). With `--full true`: the raw Graph `workbookRange` resource (adds `text`, `numberFormat`, `formulas` 2D arrays) plus `projection: 'full'`. Workbook Online (WAC) errors are translated to a clear `item is not an accessible Excel workbook` envelope (see `excel-error.ts`)."
     },
     {
       "name": "get-group",
@@ -806,6 +1339,12 @@
           "name": "group-id",
           "key": "groupId",
           "required": true,
+          "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            }
+          ],
           "description": "Azure AD group object ID. Use `list-groups` to find one."
         },
         {
@@ -826,7 +1365,7 @@
     },
     {
       "name": "get-mail-attachment",
-      "summary": "Get a single attachment on an Outlook message (metadata, plus the base64 `contentBytes` for file attachments). For fileAttachments, the response also carries a `base64` mirror of `contentBytes` so the global output-path flag can land the bytes on disk in one call. Use `--select id,name,contentType,size` to fetch metadata only and skip the multi-MB `contentBytes` payload.",
+      "summary": "Get a single attachment on an Outlook message (metadata, plus the base64 `contentBytes` for file attachments). For fileAttachments, the response also carries a `base64` mirror of `contentBytes` so the global output-path flag can land the bytes on disk in one call — and when an output-path is set the CLI strips BOTH `contentBytes` and `base64` from stdout, leaving a compact metadata envelope with `savedTo` (the file is on disk; no multi-MB base64 in the terminal). When you only want metadata, use `--select id,name,contentType,size` to skip the `contentBytes` payload.",
       "category": "mail",
       "graphMethod": "GET",
       "graphPathTemplate": "/me/messages/{message-id}/attachments/{attachment-id}",
@@ -858,11 +1397,12 @@
         }
       ],
       "example": "ask-marcel get-mail-attachment --message-id 'AAMkAGI2...' --attachment-id 'AAMkABC...'",
-      "responseShape": "single Microsoft Graph `attachment` resource. fileAttachments include `contentBytes` (Graph) AND `base64` (CLI mirror) so `--output-path` works; itemAttachments and referenceAttachments are returned unchanged."
+      "responseShape": "single Microsoft Graph `attachment` resource. fileAttachments include `contentBytes` (Graph) AND `base64` (CLI mirror) so `--output-path` works; with `--output-path` set, both byte fields are stripped from stdout and replaced by `savedTo`. itemAttachments and referenceAttachments are returned unchanged.",
+      "producesBytes": true
     },
     {
       "name": "get-mail-message",
-      "summary": "Get a single Outlook message by ID, including subject, sender, body, and flags. Pass `--select id,subject,from,receivedDateTime` to fetch only the fields the LLM needs (a full message body can be 50+ KB; the audit found this swelling LLM context unnecessarily).",
+      "summary": "Get a single Outlook message by ID. The CLI ships a slim default `--select=id,subject,from,toRecipients,ccRecipients,receivedDateTime,hasAttachments,isRead,importance,bodyPreview` so an LLM caller doesn't pull a 41 KB resource just to read a subject line. Pass `--select id,subject,body` (or any other comma-separated field list) to override; for the raw RFC-822 source use `get-mail-message-mime` instead.",
       "category": "mail",
       "graphMethod": "GET",
       "graphPathTemplate": "/me/messages/{message-id}",
@@ -872,7 +1412,13 @@
           "name": "message-id",
           "key": "messageId",
           "required": true,
-          "description": "Outlook message ID. Returned by `ask-marcel list-mail-messages` or `list-mail-folder-messages`."
+          "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            }
+          ],
+          "description": "Outlook message ID. Returned by `ask-marcel list-mail-messages` or `list-mail-folder-messages`. Accepts `--id` as an alias."
         },
         {
           "name": "select",
@@ -887,8 +1433,8 @@
           "description": "OData $expand: navigation properties to include inline (e.g. `attachments`). Increases response size; use sparingly."
         }
       ],
-      "example": "ask-marcel get-mail-message --message-id 'AAMkAGI2...' --select id,subject,from,receivedDateTime",
-      "responseShape": "single Microsoft Graph `message` resource (or projection of the requested `--select` fields)"
+      "example": "ask-marcel get-mail-message --message-id 'AAMkAGI2...'",
+      "responseShape": "single Microsoft Graph `message` resource projected to the default `--select` set (or, when overridden, to the requested fields). The default omits `body`, `internetMessageHeaders`, and `uniqueBody` — request them explicitly via `--select` when you need the full HTML."
     },
     {
       "name": "get-mail-message-mime",
@@ -902,11 +1448,18 @@
           "name": "message-id",
           "key": "messageId",
           "required": true,
-          "description": "Outlook message ID. Returned by `list-mail-messages` or `search-mail-messages`."
+          "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            }
+          ],
+          "description": "Outlook message ID. Returned by `list-mail-messages` or `search-mail-messages`. Accepts `--id` as an alias."
         }
       ],
       "example": "ask-marcel get-mail-message-mime --message-id 'AAMkAD...'",
-      "responseShape": "`{ contentType: \"text/plain\", size, base64 }` — Graph returns the raw MIME envelope wrapped as `text/plain` (NOT `message/rfc822` as the older docs suggested). Pair with the global `--output-path <path>` flag to land the .eml on disk and replace `base64` with `savedTo` for messages with large attachments."
+      "responseShape": "`{ contentType: \"text/plain\", size, base64 }` — Graph returns the raw MIME envelope wrapped as `text/plain` (NOT `message/rfc822` as the older docs suggested). Pair with the global `--output-path <path>` flag to land the .eml on disk and replace `base64` with `savedTo` for messages with large attachments.",
+      "producesBytes": true
     },
     {
       "name": "get-mail-rule",
@@ -928,6 +1481,10 @@
           "required": true,
           "description": "Message rule ID. Returned by `list-mail-rules`.",
           "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            },
             {
               "name": "rule-id",
               "key": "ruleId"
@@ -1006,11 +1563,12 @@
       "graphDocsUrl": "https://learn.microsoft.com/en-us/graph/api/profilephoto-get",
       "options": [],
       "example": "ask-marcel get-my-profile-photo",
-      "responseShape": "`{ contentType: \"image/jpeg\", size: <bytes>, base64: \"<encoded>\" }` — the photo bytes, inlined. Pair with the global `--output-path <path>` flag to land the image on disk and replace `base64` with `savedTo`."
+      "responseShape": "`{ contentType: \"image/jpeg\", size: <bytes>, base64: \"<encoded>\" }` — the photo bytes, inlined. Pair with the global `--output-path <path>` flag to land the image on disk and replace `base64` with `savedTo`.",
+      "producesBytes": true
     },
     {
       "name": "get-onenote-page-as-markdown",
-      "summary": "Get the body of a single OneNote page as markdown. Graph already returns OneNote pages as HTML, so this command runs that HTML through turndown locally. Inline image references in the page survive as Graph resource URLs (they are NOT base64-embedded — that is future work). For the raw HTML use `get-onenote-page-content`.",
+      "summary": "Get the body of a single OneNote page as markdown. Graph returns OneNote pages as HTML, which this command runs through turndown locally. By default the page’s inline images (its `…/onenote/resources/{id}/$value` references) are fetched and embedded as base64 `data:` URIs so the markdown is self-contained — pass `--inline-images false` to keep the raw Graph resource URLs instead. Image embedding is per-image isolated: any resource that fails to fetch, is oversize (> 2 MB), or is not an image is left as a URL rather than failing the page. Pass `--include-metadata true` to append a `## OneNote metadata` block (title, created / last-modified timestamps, parent section + notebook). For the raw HTML use `get-onenote-page-content`.",
       "category": "notes",
       "graphMethod": "GET",
       "graphPathTemplate": "/me/onenote/pages/{onenote-page-id}/content",
@@ -1022,15 +1580,46 @@
           "required": true,
           "description": "OneNote page ID. Returned by `ask-marcel list-onenote-section-pages`.",
           "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            },
             {
               "name": "page-id",
               "key": "pageId"
             }
           ]
+        },
+        {
+          "name": "inline-images",
+          "key": "inlineImages",
+          "required": false,
+          "description": "Pass `--inline-images false` to skip fetching + embedding the page’s `onenote/resources/{id}/$value` images and keep the raw Graph resource URLs in the markdown. Default is `true` (embed as base64 `data:` URIs so the output is self-contained). Embedding is per-image isolated — a failed / oversize / non-image resource is left as a URL either way.",
+          "argumentHint": {
+            "kind": "magicValue",
+            "values": [
+              "true",
+              "false"
+            ]
+          }
+        },
+        {
+          "name": "include-metadata",
+          "key": "includeMetadata",
+          "required": false,
+          "description": "Pass `--include-metadata true` to append a `## OneNote metadata` block after the body: page title, created / last-modified timestamps, and the parent section + notebook display names (one extra GET, expanded). Default omits it.",
+          "argumentHint": {
+            "kind": "magicValue",
+            "values": [
+              "true",
+              "false"
+            ]
+          }
         }
       ],
       "example": "ask-marcel get-onenote-page-as-markdown --onenote-page-id '1-abc...'",
-      "responseShape": "`{ contentType: \"text/markdown\", size: <chars>, text: \"...\" }` — turndown-rendered markdown of the OneNote page body."
+      "responseShape": "`{ contentType: \"text/markdown\", size, text }` — turndown-rendered page body with inline images embedded as data URIs by default. With `--include-metadata true`, a `## OneNote metadata` block is appended after the body.",
+      "producesBytes": true
     },
     {
       "name": "get-onenote-page-content",
@@ -1046,6 +1635,10 @@
           "required": true,
           "description": "OneNote page ID. Returned by `ask-marcel list-onenote-section-pages`.",
           "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            },
             {
               "name": "page-id",
               "key": "pageId"
@@ -1054,7 +1647,8 @@
         }
       ],
       "example": "ask-marcel get-onenote-page-content --onenote-page-id '1-abc...'",
-      "responseShape": "`{ contentType: \"text/html\", size: <chars>, text: \"<html>...\" }` — the rendered OneNote page body wrapped in a JSON envelope"
+      "responseShape": "`{ contentType: \"text/html\", size: <chars>, text: \"<html>...\" }` — the rendered OneNote page body wrapped in a JSON envelope",
+      "producesBytes": true
     },
     {
       "name": "get-organization",
@@ -1094,6 +1688,10 @@
           "required": true,
           "description": "Planner bucket ID. Returned by `ask-marcel list-plan-buckets`.",
           "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            },
             {
               "name": "bucket-id",
               "key": "bucketId"
@@ -1118,6 +1716,10 @@
           "required": true,
           "description": "Planner plan ID. Returned in the `planId` field of any task from `ask-marcel list-planner-tasks`.",
           "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            },
             {
               "name": "plan-id",
               "key": "planId"
@@ -1142,6 +1744,10 @@
           "required": true,
           "description": "Planner task ID. Returned by `ask-marcel list-planner-tasks` or `list-plan-tasks`. Accepts `--task-id` as a shorter alias (each task command targets exactly one of Planner or To Do, so within this command's flag set there is no ambiguity).",
           "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            },
             {
               "name": "task-id",
               "key": "taskId"
@@ -1166,6 +1772,10 @@
           "required": true,
           "description": "Planner task ID. Returned by `ask-marcel list-planner-tasks` or `list-plan-tasks`. Accepts `--task-id` as a shorter alias (each task command targets exactly one of Planner or To Do, so within this command's flag set there is no ambiguity).",
           "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            },
             {
               "name": "task-id",
               "key": "taskId"
@@ -1269,6 +1879,12 @@
           "name": "site-id",
           "key": "siteId",
           "required": true,
+          "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            }
+          ],
           "description": "SharePoint site ID. Either the composite ID (`hostname,site-collection-id,site-id`) returned by `ask-marcel search-sharepoint-sites-by-name`, or the literal `root` to refer to the tenant root site."
         },
         {
@@ -1465,7 +2081,8 @@
         }
       ],
       "example": "ask-marcel get-sharepoint-site-onenote-page-content --site-id 'contoso.sharepoint.com,...' --onenote-page-id 'p1'",
-      "responseShape": "`{ contentType: \"text/html\", size: <chars>, text: \"<html>...\" }` — the rendered OneNote page body wrapped in a JSON envelope. Pair with the global `--output-path <path>` to write the raw HTML to disk."
+      "responseShape": "`{ contentType: \"text/html\", size: <chars>, text: \"<html>...\" }` — the rendered OneNote page body wrapped in a JSON envelope. Pair with the global `--output-path <path>` to write the raw HTML to disk.",
+      "producesBytes": true
     },
     {
       "name": "get-site-analytics",
@@ -1479,6 +2096,12 @@
           "name": "site-id",
           "key": "siteId",
           "required": true,
+          "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            }
+          ],
           "description": "SharePoint site ID."
         }
       ],
@@ -1533,6 +2156,12 @@
           "name": "team-id",
           "key": "teamId",
           "required": true,
+          "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            }
+          ],
           "description": "Microsoft Teams team ID. Returned by `ask-marcel list-joined-teams`."
         },
         {
@@ -1599,6 +2228,12 @@
           "name": "team-id",
           "key": "teamId",
           "required": true,
+          "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            }
+          ],
           "description": "Microsoft Teams team ID. Returned by `list-joined-teams`."
         },
         {
@@ -1617,9 +2252,35 @@
       "example": "ask-marcel get-team-primary-channel --team-id 'tm1'",
       "responseShape": "single Microsoft Graph `channel` resource"
     },
+    {
+      "name": "get-teams-chat-message",
+      "summary": "Return a single Microsoft Teams chat message by its id via the chat substrate. Uses the chatsvcagg-audience bearer captured at login (same identity as the basic Teams token, different audience). **Best-effort, may break on Microsoft client updates** — the chat substrate is not in the public Microsoft Graph API. Source the chat-id + message-id via `list-teams-chats-with-messages` or `list-teams-chat-messages`.",
+      "category": "chats",
+      "graphMethod": "GET",
+      "graphPathTemplate": "https://teams.microsoft.com/api/csa/{region}/api/v1/chats/{chat-id}/messages/{message-id}",
+      "graphDocsUrl": "https://learn.microsoft.com/en-us/graph/api/chatmessage-get",
+      "options": [
+        {
+          "name": "chat-id",
+          "key": "chatId",
+          "required": true,
+          "description": "Teams chat ID. Source via `list-chats` or `list-teams-chats-with-messages`."
+        },
+        {
+          "name": "message-id",
+          "key": "messageId",
+          "required": true,
+          "description": "Teams chat message ID. Source via `list-teams-chats-with-messages` or `list-teams-chat-messages`."
+        }
+      ],
+      "example": "ask-marcel get-teams-chat-message --chat-id '19:abc...@unq.gbl.spaces' --message-id '1700000000000'",
+      "responseShape": "single Teams chat message — `id`, `from`, `imDisplayName`, `content`, `contentType`, `composeTime`, `originalArrivalTime`, etc. **Microsoft-internal schema — fields may change without notice.**",
+      "needsSubstrateToken": true,
+      "stability": "experimental"
+    },
     {
       "name": "get-todo-task",
-      "summary": "Get a single Microsoft To Do task by its ID and its parent list ID. Use `--select` to slim the response (e.g. `--select id,title,status`) or `--expand checklistItems` / `--expand linkedResources` to inline child collections.",
+      "summary": "Get a single Microsoft To Do task by its ID and its parent list ID. Use `--select` to slim the response (e.g. `--select id,status`) or `--expand checklistItems` / `--expand linkedResources` to inline child collections. Known Graph quirk: any `--select` combo that includes `title` trips `RequestBroker--ParseUri` on this endpoint; the CLI rewrites that opaque error to a hint.",
       "category": "tasks",
       "graphMethod": "GET",
       "graphPathTemplate": "/me/todo/lists/{todo-task-list-id}/tasks/{todo-task-id}",
@@ -1681,6 +2342,12 @@
           "name": "user-id",
           "key": "userId",
           "required": true,
+          "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            }
+          ],
           "description": "Azure AD user ID or UPN — typically the user's email address. Discover via `list-relevant-people` (relevance-ranked colleagues) or `microsoft-search-query --query <name>` (federated person search across the tenant directory)."
         },
         {
@@ -1699,6 +2366,36 @@
       "example": "ask-marcel get-user-manager --user-id 'alice@contoso.com' --select 'id,displayName,mail'",
       "responseShape": "single Microsoft Graph `user` resource on success, OR `{ manager: null, note: <string> }` when the target user has no manager set. Detect the no-manager case via `data.manager === null` (same discriminator as `get-my-manager`)."
     },
+    {
+      "name": "list-accessible-drives",
+      "summary": "Enumerate every drive (document library) the signed-in user can reach — personal OneDrive(s), Teams libraries, SharePoint M365-group sites, drives behind files shared with the user, private/shared Teams channel sites, drives behind recently-used / followed / trending items (activity signals), AND every NON-default document library of each discovered SharePoint site — by unioning `/me/drives`, `/me/joinedTeams`, `/me/memberOf` (Unified groups → `/groups/{id}/drive`), `/me/drive/sharedWithMe`, per-team `/teams/{id}/channels` → `/channels/{ch}/filesFolder` (private/shared channels only — their files live in their own site, not the team default drive), `/me/drive/recent` + `/me/drive/following` + `/me/insights/{trending,used,shared}`, and a path-addressed `/sites/{host}:/sites/{name}:/drives` per discovered site (catches secondary libraries like \"Teams Wiki Data\" the default-drive vectors miss). Unlike `search-sharepoint-sites-by-name` (which relies on the tenant search index and misses direct-link-only sites + OneDrives), these vectors surface drives the search index never returns; the index in turn returns sites you can open but are not a member of, so the *union of both commands* is the practical maximum on a delegated token. Each drive is tagged with the `sources[]` that found it (a drive can have several). Per-resource \"can't reach this one\" failures are dropped silently (404 no drive, 403 access-denied / non-member private channel, 423 admin-locked site, 400 stale/unresolvable id); only actionable failures (auth, throttling, 5xx, network) appear in `partialErrors[]`, so it stays signal-only. Fans out one `/groups/{id}/drive` + one `/teams/{id}/channels` call per joined team + member group, a `filesFolder` call per private/shared channel, five fixed activity calls, and one `/sites/{id}/drives` call per discovered site (all capped by `--max-groups`, default 100; raise carefully — large memberships can hit 429 throttling). `/me/followedSites` is not used — it 403s on this token.",
+      "category": "drive",
+      "graphMethod": "GET",
+      "graphPathTemplate": "/me/drives + /me/joinedTeams + /me/memberOf + /me/drive/sharedWithMe + per-group /groups/<id>/drive + per-team /teams/<id>/channels/<ch>/filesFolder + /me/drive/recent + /me/drive/following + /me/insights/<trending|used|shared> + per-site /sites/<host>:/sites/<name>:/drives",
+      "graphDocsUrl": "https://learn.microsoft.com/en-us/graph/api/drive-list",
+      "options": [
+        {
+          "name": "max-groups",
+          "key": "maxGroups",
+          "required": false,
+          "description": "Safety cap on each fan-out (positive integer; default 100): the per-group `/groups/{id}/drive` calls, the per-team `/teams/{id}/channels` enumeration, the per-private/shared-channel `filesFolder` lookups, the per-site `/sites/{id}/drives` enumeration, and the `/drives/{id}` enrichment for shared-, channel-, and activity-only drives. A user in hundreds of teams/groups/sites would otherwise issue hundreds of parallel requests (429 risk). When any cap is hit the response carries `truncated: true`.",
+          "argumentHint": {
+            "kind": "magicValue",
+            "values": [
+              "100"
+            ]
+          }
+        },
+        {
+          "name": "count-files",
+          "key": "countFiles",
+          "required": false,
+          "description": "Pass `--count-files true` to add `estimatedFileCount` to each drive — the Microsoft Search index's security-trimmed `driveItem` total (files + folders) scoped to that drive's `webUrl` via KQL `path:`. OFF by default because it issues ONE extra Search query per drive (chunked, capped at 200) — a real fan-out with 429-throttling risk on large drive sets. It is an estimate, not an exact count."
+        }
+      ],
+      "example": "ask-marcel list-accessible-drives --output json",
+      "responseShape": "`{ value: [{ id, name, driveType, webUrl, sources: [\"activity\"|\"channel\"|\"joinedTeam\"|\"memberOfGroup\"|\"personal\"|\"sharedWithMe\"|\"siteLibrary\"], groupId?, size?, estimatedFileCount? }], count, fileEstimate?, truncated?: true, partialErrors?: [{ source, error }] }`. `estimatedFileCount` appears only with `--count-files true` — the security-trimmed `driveItem` (files+folders) estimate scoped to each drive, omitted past the 200-drive count cap or when the per-drive query fails. `value[]` is deduped by drive `id` and sorted by id; `sources[]` lists every vector that surfaced the drive (`channel` = a private/shared Teams channel files folder; `activity` = a recently-used / followed / trending item drive; `siteLibrary` = a non-default document library of a discovered site); `groupId` is present only for Teams/group drives. `size` (when present) is the drive's total bytes used (`quota.used`, recursive) — surfaced free from the drive resource, omitted for the rare drive without a quota facet; it is a data-volume signal, not a file count. `fileEstimate` (best-effort, omitted if the extra query fails) is the Microsoft Search index's security-trimmed `driveItem` count — roughly how many files+folders you can access across ALL of SharePoint/OneDrive; it is INDEX-WIDE, not limited to the `value[]` drives above. `truncated: true` means a `--max-groups` cap was hit — raise it to see more. `partialErrors[]` (present only when something actionable failed) names each vector/group/channel/site whose sub-call returned an actionable error (auth, throttling, 5xx, network); benign \"can't reach this one\" results (404/403/423/400) are dropped, not listed."
+    },
     {
       "name": "list-all-onenote-sections",
       "summary": "List every OneNote section the signed-in user can see, across all notebooks.",
@@ -1748,6 +2445,67 @@
       "responseShape": "collection of Microsoft Graph `onenoteSection` resources under `value[]`",
       "pagination": true
     },
+    {
+      "name": "list-calendar-event-attachments",
+      "summary": "List the attachments (file, item, reference) on a single Outlook calendar event. Ships an opinionated default `--select=id,name,contentType,size,isInline` so an LLM doesn't accidentally pull multi-MB `contentBytes` for every attachment. The `@odata.type` discriminator is always returned by Graph regardless of `$select` (and Graph rejects asking for it explicitly). To read one, call `convert-calendar-event-attachment-to-markdown` (or `convert-calendar-event-attachment-to-pdf` for slide / layout fidelity).",
+      "category": "calendar",
+      "graphMethod": "GET",
+      "graphPathTemplate": "/me/events/{event-id}/attachments",
+      "graphDocsUrl": "https://learn.microsoft.com/en-us/graph/api/event-list-attachments",
+      "options": [
+        {
+          "name": "event-id",
+          "key": "eventId",
+          "required": true,
+          "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            }
+          ],
+          "description": "Outlook calendar event ID. Returned by `ask-marcel list-calendar-events` or `get-calendar-event`."
+        },
+        {
+          "name": "top",
+          "key": "top",
+          "required": false,
+          "description": "OData $top: maximum number of items to return on this page (positive integer, ≤ 1000). Graph silently caps at 1000 on every collection endpoint, so the CLI rejects larger values with a clear validation error rather than letting the request silently truncate. Combine with `next-page` to paginate beyond the cap."
+        },
+        {
+          "name": "skip",
+          "key": "skip",
+          "required": false,
+          "description": "OData $skip: skip the first N items before returning results (non-negative integer). Useful with $top for offset paging."
+        },
+        {
+          "name": "select",
+          "key": "select",
+          "required": false,
+          "description": "OData $select: comma-separated list of fields to include in each item (e.g. `id,subject,from`). May shrink payloads dramatically — Graph honors $select on most endpoints, but some collections (notably `/me/mailboxSettings`, `/me/outlook/masterCategories`, `/me/mailFolders/inbox/messageRules`) silently ignore it and always return the full resource. Bogus field names are silently dropped by Graph — if a field you asked for is missing from the response, double-check the spelling against the documented `responseShape`."
+        },
+        {
+          "name": "filter",
+          "key": "filter",
+          "required": false,
+          "description": "OData $filter: predicate to narrow results server-side. Quoting rules: string literals MUST use SINGLE quotes (`subject eq 'invoice'`), NOT double quotes — Graph rejects `subject eq \"invoice\"` with `InvalidFilterClause`. To embed a single quote inside a string, double it (`subject eq 'O''Brien'`). Booleans, numbers, and dates are unquoted (`isRead eq false`, `receivedDateTime ge 2026-01-01T00:00:00Z`). Wrap the whole flag value in shell DOUBLE quotes so the inner single quotes survive (`--filter \"subject eq 'invoice'\"`). Same syntax Graph documents per resource type."
+        },
+        {
+          "name": "orderby",
+          "key": "orderby",
+          "required": false,
+          "description": "OData $orderby: sort expression with optional asc/desc (e.g. `receivedDateTime desc`). Some Graph filter combinations are rejected; remove $orderby if InefficientFilter occurs."
+        },
+        {
+          "name": "expand",
+          "key": "expand",
+          "required": false,
+          "description": "OData $expand: navigation properties to include inline (e.g. `attachments`). Increases response size; use sparingly."
+        }
+      ],
+      "example": "ask-marcel list-calendar-event-attachments --event-id 'AAMkAGI2...'",
+      "responseShape": "collection of Microsoft Graph `attachment` resources under `value[]` (slim metadata by default — see summary). Graph always includes `@odata.type` and `@odata.mediaContentType` on every entry regardless of `--select` — that discriminator is what the attachment-converting commands branch on.",
+      "pagination": true
+    },
     {
       "name": "list-calendar-event-instances",
       "summary": "List the individual occurrences of a recurring calendar event over a date range. Both ISO date-time params are required by Graph. `--calendar-id` is optional and defaults to `primary` (the signed-in user’s default calendar) — most callers know the event-id but not which calendar it lives in. Pass an explicit `--calendar-id` only when targeting a non-default calendar.",
@@ -1773,19 +2531,37 @@
           "name": "event-id",
           "key": "eventId",
           "required": true,
+          "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            }
+          ],
           "description": "Recurring event ID. Returned by `ask-marcel list-specific-calendar-events`."
         },
         {
           "name": "start-date-time",
           "key": "startDateTime",
           "required": true,
-          "description": "ISO 8601 lower bound (UTC). Example: `2026-04-01T00:00:00Z`. Required by Graph; the request fails without it."
+          "aliases": [
+            {
+              "name": "start",
+              "key": "start"
+            }
+          ],
+          "description": "Lower bound. ISO 8601 UTC (e.g. `2026-04-01T00:00:00Z` or `2026-04-01`) OR a relative shape: `7d` / `1w` / `2h` / `30m` (past), `+7d` (future), `today` / `yesterday` / `tomorrow` / `now`, `monday`-`sunday` (most recent), `last-<weekday>` / `next-<weekday>`, `start-of-week|month|year`, `end-of-week|month|year`. Relative forms resolve at request time relative to the CLI process clock (UTC)."
         },
         {
           "name": "end-date-time",
           "key": "endDateTime",
           "required": true,
-          "description": "ISO 8601 upper bound (UTC). Example: `2026-05-01T00:00:00Z`. Required by Graph; the request fails without it."
+          "aliases": [
+            {
+              "name": "end",
+              "key": "end"
+            }
+          ],
+          "description": "Upper bound. ISO 8601 UTC (e.g. `2026-04-01T00:00:00Z` or `2026-04-01`) OR a relative shape: `7d` / `1w` / `2h` / `30m` (past), `+7d` (future), `today` / `yesterday` / `tomorrow` / `now`, `monday`-`sunday` (most recent), `last-<weekday>` / `next-<weekday>`, `start-of-week|month|year`, `end-of-week|month|year`. Relative forms resolve at request time relative to the CLI process clock (UTC)."
         },
         {
           "name": "top",
@@ -1908,6 +2684,12 @@
           "name": "calendar-group-id",
           "key": "calendarGroupId",
           "required": true,
+          "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            }
+          ],
           "description": "Calendar group ID. Returned by `list-calendar-groups`."
         },
         {
@@ -2002,7 +2784,7 @@
     },
     {
       "name": "list-calendar-view",
-      "summary": "List the signed-in user’s default-calendar events with recurrence expanded into individual occurrences in a date range. Both ISO date-time params are required by Graph.",
+      "summary": "List the signed-in user's default-calendar events with recurrence expanded into individual occurrences in a date range. Both date-time params accept strict ISO 8601 (`2026-04-01T00:00:00Z`) AND the CLI's relative shapes (`7d`, `today`, `monday`, `start-of-month`, …) so a question like \"what's on my calendar this week\" no longer requires the LLM to compute timestamps by hand.",
       "category": "calendar",
       "graphMethod": "GET",
       "graphPathTemplate": "/me/calendarView?startDateTime={start-date-time}&endDateTime={end-date-time}",
@@ -2012,13 +2794,25 @@
           "name": "start-date-time",
           "key": "startDateTime",
           "required": true,
-          "description": "ISO 8601 lower bound (UTC). Example: `2026-04-01T00:00:00Z`. Required by Graph; the request fails without it."
+          "aliases": [
+            {
+              "name": "start",
+              "key": "start"
+            }
+          ],
+          "description": "Lower bound. ISO 8601 UTC (e.g. `2026-04-01T00:00:00Z` or `2026-04-01`) OR a relative shape: `7d` / `1w` / `2h` / `30m` (past), `+7d` (future), `today` / `yesterday` / `tomorrow` / `now`, `monday`-`sunday` (most recent), `last-<weekday>` / `next-<weekday>`, `start-of-week|month|year`, `end-of-week|month|year`. Relative forms resolve at request time relative to the CLI process clock (UTC)."
         },
         {
           "name": "end-date-time",
           "key": "endDateTime",
           "required": true,
-          "description": "ISO 8601 upper bound (UTC). Example: `2026-05-01T00:00:00Z`. Required by Graph; the request fails without it."
+          "aliases": [
+            {
+              "name": "end",
+              "key": "end"
+            }
+          ],
+          "description": "Upper bound. ISO 8601 UTC (e.g. `2026-04-01T00:00:00Z` or `2026-04-01`) OR a relative shape: `7d` / `1w` / `2h` / `30m` (past), `+7d` (future), `today` / `yesterday` / `tomorrow` / `now`, `monday`-`sunday` (most recent), `last-<weekday>` / `next-<weekday>`, `start-of-week|month|year`, `end-of-week|month|year`. Relative forms resolve at request time relative to the CLI process clock (UTC)."
         },
         {
           "name": "top",
@@ -2057,7 +2851,7 @@
           "description": "OData $expand: navigation properties to include inline (e.g. `attachments`). Increases response size; use sparingly."
         }
       ],
-      "example": "ask-marcel list-calendar-view --start-date-time '2026-04-01T00:00:00Z' --end-date-time '2026-05-01T00:00:00Z'",
+      "example": "ask-marcel list-calendar-view --start-date-time 'start-of-week' --end-date-time 'end-of-week'",
       "responseShape": "collection of Microsoft Graph `event` resources (single occurrences) under `value[]`"
     },
     {
@@ -2072,13 +2866,25 @@
           "name": "start-date-time",
           "key": "startDateTime",
           "required": true,
-          "description": "ISO 8601 lower bound (UTC). Required on the first call only — the deltaLink token encodes it for resumes."
+          "aliases": [
+            {
+              "name": "start",
+              "key": "start"
+            }
+          ],
+          "description": "Lower bound (required on the first call only — the deltaLink token encodes it for resumes). ISO 8601 UTC (e.g. `2026-04-01T00:00:00Z` or `2026-04-01`) OR a relative shape: `7d` / `1w` / `2h` / `30m` (past), `+7d` (future), `today` / `yesterday` / `tomorrow` / `now`, `monday`-`sunday` (most recent), `last-<weekday>` / `next-<weekday>`, `start-of-week|month|year`, `end-of-week|month|year`. Relative forms resolve at request time relative to the CLI process clock (UTC)."
         },
         {
           "name": "end-date-time",
           "key": "endDateTime",
           "required": true,
-          "description": "ISO 8601 upper bound (UTC). Required on the first call only — the deltaLink token encodes it for resumes."
+          "aliases": [
+            {
+              "name": "end",
+              "key": "end"
+            }
+          ],
+          "description": "Upper bound (required on the first call only — the deltaLink token encodes it for resumes). ISO 8601 UTC (e.g. `2026-04-01T00:00:00Z` or `2026-04-01`) OR a relative shape: `7d` / `1w` / `2h` / `30m` (past), `+7d` (future), `today` / `yesterday` / `tomorrow` / `now`, `monday`-`sunday` (most recent), `last-<weekday>` / `next-<weekday>`, `start-of-week|month|year`, `end-of-week|month|year`. Relative forms resolve at request time relative to the CLI process clock (UTC)."
         },
         {
           "name": "top",
@@ -2152,6 +2958,12 @@
           "name": "chat-id",
           "key": "chatId",
           "required": true,
+          "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            }
+          ],
           "description": "Microsoft Teams chat ID, e.g. `19:abc...@thread.v2`. Source the ID via `ask-marcel list-chats` (returns chat metadata for the signed-in user). Alternative sources outside the CLI: the Teams desktop / web client (Open in browser → URL contains the chat thread ID), Microsoft Graph Explorer, or URL-decode the `19%3ameeting_...%40thread.v2` segment of an `onlineMeeting.joinUrl` from `list-calendar-events`."
         },
         {
@@ -2175,11 +2987,12 @@
       ],
       "example": "ask-marcel list-chat-members --chat-id '19:abc...@thread.v2'",
       "responseShape": "collection of Microsoft Graph `conversationMember` resources under `value[]`",
-      "pagination": true
+      "pagination": true,
+      "needsElevatedToken": true
     },
     {
       "name": "list-chats",
-      "summary": "List the signed-in user's Microsoft Teams chats (1:1, group, and meeting chats). Returns chat metadata only — `id`, `topic`, `chatType`, `lastUpdatedDateTime`, etc. Reading chat *messages* needs `Chat.Read*` which neither token grants. Requires the M365ChatClient elevated token captured at login (the basic Teams web client token lacks `Chat.ReadBasic`). Graph rejects `$orderby` and hangs on `$expand` for this endpoint, so the CLI advertises only the subset Graph honours (`--top`, `--skip`, `--select`, `--filter`).",
+      "summary": "List the signed-in user's Microsoft Teams chats (1:1, group, and meeting chats). The CLI ships a slim default `--select=id,topic,chatType,createdDateTime,lastUpdatedDateTime`; pass `--select id,topic,webUrl,...` to widen. Returns chat metadata only — reading chat *messages* needs `Chat.Read*` which neither token grants. Requires the M365ChatClient elevated token captured at login (the basic Teams web client token lacks `Chat.ReadBasic`). Graph rejects `$orderby` and hangs on `$expand` for this endpoint, so the CLI advertises only the subset Graph honours (`--top`, `--skip`, `--select`, `--filter`).",
       "category": "chats",
       "graphMethod": "GET",
       "graphPathTemplate": "/me/chats",
@@ -2211,8 +3024,9 @@
         }
       ],
       "example": "ask-marcel list-chats",
-      "responseShape": "collection of Microsoft Graph `chat` resources under `value[]`",
-      "pagination": true
+      "responseShape": "collection of Microsoft Graph `chat` resources under `value[]`, each projected to the default `--select` set (or, when overridden, to the requested fields).",
+      "pagination": true,
+      "needsElevatedToken": true
     },
     {
       "name": "list-conversation-messages",
@@ -2226,6 +3040,12 @@
           "name": "conversation-id",
           "key": "conversationId",
           "required": true,
+          "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            }
+          ],
           "description": "Outlook `conversationId` of any message in the thread (returned by every mail-listing command and by `get-mail-message`)."
         },
         {
@@ -2269,7 +3089,7 @@
           "name": "drive-id",
           "key": "driveId",
           "required": true,
-          "description": "Microsoft Graph drive ID. Returned by `ask-marcel list-drives`."
+          "description": "Microsoft Graph drive ID. Use `ask-marcel list-drives` for the personal OneDrive, or `ask-marcel list-sharepoint-site-drives --site-id <id>` for a SharePoint document library."
         },
         {
           "name": "item-id",
@@ -2324,7 +3144,7 @@
           "name": "drive-id",
           "key": "driveId",
           "required": true,
-          "description": "OneDrive / SharePoint drive ID."
+          "description": "Microsoft Graph drive ID. Use `ask-marcel list-drives` for the personal OneDrive, or `ask-marcel list-sharepoint-site-drives --site-id <id>` for a SharePoint document library."
         },
         {
           "name": "item-id",
@@ -2369,7 +3189,7 @@
     },
     {
       "name": "list-drive-item-versions",
-      "summary": "List the historical versions of a OneDrive / SharePoint file (each save creates a new version). Note: each version's `id` is a stringified float like `\"79.0\"` (NOT an integer like `79`) — pass it literally to sibling commands such as `download-drive-item-version-content` / `-as-pdf` / `-as-markdown`; numeric coercion silently fails because Graph rejects `79` against a path templated as `{version-id}`.",
+      "summary": "List the historical versions of a OneDrive / SharePoint file (each save creates a new version). Note: each version's `id` is a stringified float like `\"79.0\"` (NOT an integer like `79`) — pass it literally to the `download-drive-item-version` command (it accepts an `original | pdf | markdown` format selector); numeric coercion silently fails because Graph rejects `79` against a path templated for stringified floats.",
       "category": "drive",
       "graphMethod": "GET",
       "graphPathTemplate": "/drives/{drive-id}/items/{item-id}/versions",
@@ -2483,7 +3303,7 @@
           "name": "drive-id",
           "key": "driveId",
           "required": true,
-          "description": "OneDrive / SharePoint drive ID."
+          "description": "Microsoft Graph drive ID. Use `ask-marcel list-drives` for the personal OneDrive, or `ask-marcel list-sharepoint-site-drives --site-id <id>` for a SharePoint document library."
         },
         {
           "name": "item-id",
@@ -2544,7 +3364,7 @@
           "name": "drive-id",
           "key": "driveId",
           "required": true,
-          "description": "OneDrive / SharePoint drive ID."
+          "description": "Microsoft Graph drive ID. Use `ask-marcel list-drives` for the personal OneDrive, or `ask-marcel list-sharepoint-site-drives --site-id <id>` for a SharePoint document library."
         },
         {
           "name": "item-id",
@@ -2605,7 +3425,7 @@
           "name": "drive-id",
           "key": "driveId",
           "required": true,
-          "description": "Microsoft Graph drive ID containing the workbook. Returned by `ask-marcel list-drives`."
+          "description": "Microsoft Graph drive ID containing the workbook. Use `ask-marcel list-drives` for the personal OneDrive, or `ask-marcel list-sharepoint-site-drives --site-id <id>` for a SharePoint document library."
         },
         {
           "name": "item-id",
@@ -2660,7 +3480,7 @@
           "name": "drive-id",
           "key": "driveId",
           "required": true,
-          "description": "Microsoft Graph drive ID containing the workbook. Returned by `ask-marcel list-drives`."
+          "description": "Microsoft Graph drive ID containing the workbook. Use `ask-marcel list-drives` for the personal OneDrive, or `ask-marcel list-sharepoint-site-drives --site-id <id>` for a SharePoint document library."
         },
         {
           "name": "item-id",
@@ -2709,7 +3529,7 @@
           "name": "drive-id",
           "key": "driveId",
           "required": true,
-          "description": "OneDrive / SharePoint drive ID."
+          "description": "Microsoft Graph drive ID. Use `ask-marcel list-drives` for the personal OneDrive, or `ask-marcel list-sharepoint-site-drives --site-id <id>` for a SharePoint document library."
         },
         {
           "name": "item-id",
@@ -2779,7 +3599,7 @@
           "name": "drive-id",
           "key": "driveId",
           "required": true,
-          "description": "OneDrive / SharePoint drive ID."
+          "description": "Microsoft Graph drive ID. Use `ask-marcel list-drives` for the personal OneDrive, or `ask-marcel list-sharepoint-site-drives --site-id <id>` for a SharePoint document library."
         },
         {
           "name": "item-id",
@@ -2849,7 +3669,7 @@
           "name": "drive-id",
           "key": "driveId",
           "required": true,
-          "description": "Microsoft Graph drive ID containing the workbook. Returned by `ask-marcel list-drives`."
+          "description": "Microsoft Graph drive ID containing the workbook. Use `ask-marcel list-drives` for the personal OneDrive, or `ask-marcel list-sharepoint-site-drives --site-id <id>` for a SharePoint document library."
         },
         {
           "name": "item-id",
@@ -2941,7 +3761,7 @@
           "name": "drive-id",
           "key": "driveId",
           "required": true,
-          "description": "Microsoft Graph drive ID. Returned by `ask-marcel list-drives`."
+          "description": "Microsoft Graph drive ID. Use `ask-marcel list-drives` for the personal OneDrive, or `ask-marcel list-sharepoint-site-drives --site-id <id>` for a SharePoint document library."
         },
         {
           "name": "item-id",
@@ -3045,19 +3865,37 @@
           "name": "group-id",
           "key": "groupId",
           "required": true,
+          "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            }
+          ],
           "description": "Azure AD group object ID for a unified (Microsoft 365) group."
         },
         {
           "name": "start-date-time",
           "key": "startDateTime",
           "required": true,
-          "description": "ISO 8601 start (e.g. `2026-04-01T00:00:00Z`). Recurrences are expanded across the window."
+          "aliases": [
+            {
+              "name": "start",
+              "key": "start"
+            }
+          ],
+          "description": "Start of the window (recurrences are expanded across it). ISO 8601 UTC (e.g. `2026-04-01T00:00:00Z` or `2026-04-01`) OR a relative shape: `7d` / `1w` / `2h` / `30m` (past), `+7d` (future), `today` / `yesterday` / `tomorrow` / `now`, `monday`-`sunday` (most recent), `last-<weekday>` / `next-<weekday>`, `start-of-week|month|year`, `end-of-week|month|year`. Relative forms resolve at request time relative to the CLI process clock (UTC)."
         },
         {
           "name": "end-date-time",
           "key": "endDateTime",
           "required": true,
-          "description": "ISO 8601 end (e.g. `2026-05-01T00:00:00Z`)."
+          "aliases": [
+            {
+              "name": "end",
+              "key": "end"
+            }
+          ],
+          "description": "End of the window. ISO 8601 UTC (e.g. `2026-04-01T00:00:00Z` or `2026-04-01`) OR a relative shape: `7d` / `1w` / `2h` / `30m` (past), `+7d` (future), `today` / `yesterday` / `tomorrow` / `now`, `monday`-`sunday` (most recent), `last-<weekday>` / `next-<weekday>`, `start-of-week|month|year`, `end-of-week|month|year`. Relative forms resolve at request time relative to the CLI process clock (UTC)."
         },
         {
           "name": "top",
@@ -3112,6 +3950,12 @@
           "name": "group-id",
           "key": "groupId",
           "required": true,
+          "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            }
+          ],
           "description": "Azure AD group object ID for a unified (Microsoft 365) group."
         },
         {
@@ -3167,6 +4011,12 @@
           "name": "group-id",
           "key": "groupId",
           "required": true,
+          "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            }
+          ],
           "description": "Azure AD group object ID for a unified (Microsoft 365) group. Use `list-groups` to find one."
         },
         {
@@ -3222,6 +4072,12 @@
           "name": "group-id",
           "key": "groupId",
           "required": true,
+          "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            }
+          ],
           "description": "Azure AD group object ID. Use `list-groups` to find one."
         },
         {
@@ -3277,6 +4133,12 @@
           "name": "group-id",
           "key": "groupId",
           "required": true,
+          "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            }
+          ],
           "description": "Azure AD group object ID. Use `list-groups` to find one."
         },
         {
@@ -3332,6 +4194,12 @@
           "name": "group-id",
           "key": "groupId",
           "required": true,
+          "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            }
+          ],
           "description": "Azure AD group object ID for a unified (Microsoft 365) group."
         },
         {
@@ -3481,6 +4349,10 @@
           "required": true,
           "description": "todoTaskList ID. Returned by `ask-marcel list-todo-task-lists`. The well-known name `tasks` (the default list) is accepted on this incomplete-tasks endpoint specifically — sibling commands like `list-todo-tasks` and `list-todo-tasks-delta` only accept resolved IDs. There is no Graph endpoint that returns incomplete tasks across every list — call this once per list.",
           "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            },
             {
               "name": "task-list-id",
               "key": "taskListId"
@@ -3556,7 +4428,13 @@
           "name": "message-id",
           "key": "messageId",
           "required": true,
-          "description": "Outlook message ID. Returned by `ask-marcel list-mail-messages` or `list-mail-folder-messages`."
+          "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            }
+          ],
+          "description": "Outlook message ID. Returned by `ask-marcel list-mail-messages` or `list-mail-folder-messages`. Accepts `--id` as an alias."
         },
         {
           "name": "top",
@@ -3611,6 +4489,12 @@
           "name": "mail-folder-id",
           "key": "mailFolderId",
           "required": true,
+          "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            }
+          ],
           "description": "mailFolder ID. Returned by `ask-marcel list-mail-folders`. Well-known names also work, e.g. `inbox`, `sentitems`, `drafts`."
         },
         {
@@ -3666,6 +4550,12 @@
           "name": "mail-folder-id",
           "key": "mailFolderId",
           "required": true,
+          "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            }
+          ],
           "description": "mailFolder ID. Returned by `ask-marcel list-mail-folders`. Well-known names also work, e.g. `inbox`, `sentitems`, `drafts`."
         },
         {
@@ -3721,6 +4611,12 @@
           "name": "mail-folder-id",
           "key": "mailFolderId",
           "required": true,
+          "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            }
+          ],
           "description": "Mail folder ID or well-known name (`inbox`, `archive`, `sentitems`, `deleteditems`, `junkemail`, `drafts`). Returned by `list-mail-folders`."
         },
         {
@@ -3827,7 +4723,7 @@
     },
     {
       "name": "list-mail-messages",
-      "summary": "List the most recent messages from across the signed-in user’s entire Outlook mailbox (every folder including Sent, Archive, Junk; default sort `receivedDateTime` desc). Use `list-mail-folder-messages` to scope to a single folder such as Inbox.",
+      "summary": "List the most recent messages from across the signed-in user's entire Outlook mailbox (every folder including Sent, Archive, Junk; default sort `receivedDateTime` desc). The CLI ships a slim default `--select=id,subject,from,toRecipients,ccRecipients,receivedDateTime,hasAttachments,isRead,importance,bodyPreview` so a page of 25 messages stays ~30-60 KB instead of ~1 MB. Pass `--select id,subject,body` (or any other comma-separated field list) to override. Use `list-mail-folder-messages` to scope to a single folder such as Inbox.",
       "category": "mail",
       "graphMethod": "GET",
       "graphPathTemplate": "/me/messages",
@@ -3871,7 +4767,7 @@
         }
       ],
       "example": "ask-marcel list-mail-messages",
-      "responseShape": "collection of Microsoft Graph `message` resources under `value[]`",
+      "responseShape": "collection of Microsoft Graph `message` resources under `value[]`, each projected to the default `--select` set (or the requested fields when overridden). The default omits `body`, `internetMessageHeaders`, and `uniqueBody`.",
       "pagination": true
     },
     {
@@ -4051,6 +4947,12 @@
           "name": "notebook-id",
           "key": "notebookId",
           "required": true,
+          "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            }
+          ],
           "description": "OneNote notebook ID. Returned by `ask-marcel list-onenote-notebooks`."
         },
         {
@@ -4157,6 +5059,10 @@
           "required": true,
           "description": "OneNote section ID. Returned by `ask-marcel list-onenote-notebook-sections` or `list-all-onenote-sections`.",
           "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            },
             {
               "name": "section-id",
               "key": "sectionId"
@@ -4229,6 +5135,10 @@
           "required": true,
           "description": "Planner plan ID. Returned in the `planId` field of any task from `ask-marcel list-planner-tasks`.",
           "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            },
             {
               "name": "plan-id",
               "key": "planId"
@@ -4260,6 +5170,10 @@
           "required": true,
           "description": "Planner plan ID. Returned in the `planId` field of any task from `ask-marcel list-planner-tasks`.",
           "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            },
             {
               "name": "plan-id",
               "key": "planId"
@@ -4384,7 +5298,7 @@
     },
     {
       "name": "list-recently-used-insights",
-      "summary": "List documents the signed-in user has *personally* used recently (Microsoft's machine-learning recency signal — distinct from `list-recent-files` which is the OneDrive recency feed). Returns `usageDetails` with `lastAccessedDateTime` + `lastModifiedDateTime`.",
+      "summary": "List documents the signed-in user has *personally* used recently (Microsoft's machine-learning recency signal — distinct from `list-recent-files` which is the OneDrive recency feed). Each item carries a `lastUsed` (a `usageDetails` object) with `lastAccessedDateTime` + `lastModifiedDateTime`.",
       "category": "drive",
       "graphMethod": "GET",
       "graphPathTemplate": "/me/insights/used",
@@ -4639,6 +5553,12 @@
           "name": "user-id",
           "key": "userId",
           "required": true,
+          "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            }
+          ],
           "description": "Azure AD user ID or UPN whose calendar to read. Requires `Calendars.Read.Shared` access (granted by the calendar owner)."
         },
         {
@@ -4694,19 +5614,37 @@
           "name": "user-id",
           "key": "userId",
           "required": true,
+          "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            }
+          ],
           "description": "Azure AD user ID or UPN of the calendar owner."
         },
         {
           "name": "start-date-time",
           "key": "startDateTime",
           "required": true,
-          "description": "ISO 8601 start of the window."
+          "aliases": [
+            {
+              "name": "start",
+              "key": "start"
+            }
+          ],
+          "description": "Start of the window. ISO 8601 UTC (e.g. `2026-04-01T00:00:00Z` or `2026-04-01`) OR a relative shape: `7d` / `1w` / `2h` / `30m` (past), `+7d` (future), `today` / `yesterday` / `tomorrow` / `now`, `monday`-`sunday` (most recent), `last-<weekday>` / `next-<weekday>`, `start-of-week|month|year`, `end-of-week|month|year`. Relative forms resolve at request time relative to the CLI process clock (UTC)."
         },
         {
           "name": "end-date-time",
           "key": "endDateTime",
           "required": true,
-          "description": "ISO 8601 end of the window."
+          "aliases": [
+            {
+              "name": "end",
+              "key": "end"
+            }
+          ],
+          "description": "End of the window. ISO 8601 UTC (e.g. `2026-04-01T00:00:00Z` or `2026-04-01`) OR a relative shape: `7d` / `1w` / `2h` / `30m` (past), `+7d` (future), `today` / `yesterday` / `tomorrow` / `now`, `monday`-`sunday` (most recent), `last-<weekday>` / `next-<weekday>`, `start-of-week|month|year`, `end-of-week|month|year`. Relative forms resolve at request time relative to the CLI process clock (UTC)."
         },
         {
           "name": "top",
@@ -4871,6 +5809,12 @@
           "name": "user-id",
           "key": "userId",
           "required": true,
+          "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            }
+          ],
           "description": "Azure AD user ID or UPN of the shared mailbox or delegated user. The signed-in user must have `Mail.Read.Shared` access (granted by the mailbox owner)."
         },
         {
@@ -4916,7 +5860,7 @@
     },
     {
       "name": "list-shared-with-me",
-      "summary": "List driveItems shared with the signed-in user (typically by colleagues). Each entry includes the original drive + item ID under `remoteItem` so you can chain into `get-drive-item`, `download-onedrive-file-content`, etc. Note: Graph does NOT honor any OData query parameters on this endpoint (top/select/filter/etc. are all silently ignored), so the CLI does not advertise them. The full collection (~500 items in a typical tenant) is always returned; slice client-side or pair with the global output-path flag to land the raw JSON on disk.",
+      "summary": "List driveItems shared with the signed-in user (typically by colleagues). Each entry includes the original drive + item ID under `remoteItem` so you can chain into `get-drive-item`, `download-drive-item-content`, etc. Note: Graph does NOT honor any OData query parameters on this endpoint (top/select/filter/etc. are all silently ignored), so the CLI does not advertise them. The full collection (~500 items in a typical tenant) is always returned; slice client-side or pair with the global output-path flag to land the raw JSON on disk.",
       "category": "drive",
       "graphMethod": "GET",
       "graphPathTemplate": "/me/drive/sharedWithMe",
@@ -5040,6 +5984,12 @@
           "name": "site-id",
           "key": "siteId",
           "required": true,
+          "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            }
+          ],
           "description": "SharePoint site ID. Returned by `ask-marcel search-sharepoint-sites-by-name`."
         },
         {
@@ -5147,6 +6097,12 @@
           "name": "site-id",
           "key": "siteId",
           "required": true,
+          "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            }
+          ],
           "description": "SharePoint site ID. Returned by `ask-marcel search-sharepoint-sites-by-name`."
         },
         {
@@ -5257,6 +6213,12 @@
           "name": "site-id",
           "key": "siteId",
           "required": true,
+          "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            }
+          ],
           "description": "SharePoint site ID."
         },
         {
@@ -5379,6 +6341,12 @@
           "name": "site-id",
           "key": "siteId",
           "required": true,
+          "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            }
+          ],
           "description": "SharePoint site ID."
         },
         {
@@ -5428,6 +6396,12 @@
           "name": "site-id",
           "key": "siteId",
           "required": true,
+          "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            }
+          ],
           "description": "SharePoint site ID. Returned by `search-sharepoint-sites-by-name`."
         },
         {
@@ -5458,6 +6432,12 @@
           "name": "site-id",
           "key": "siteId",
           "required": true,
+          "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            }
+          ],
           "description": "SharePoint site ID."
         },
         {
@@ -5507,6 +6487,12 @@
           "name": "calendar-id",
           "key": "calendarId",
           "required": true,
+          "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            }
+          ],
           "description": "Calendar ID, or the well-known short name `primary` / `default` for the signed-in user’s default calendar. Use `ask-marcel list-calendars` to discover non-default calendar IDs."
         },
         {
@@ -5562,19 +6548,37 @@
           "name": "calendar-id",
           "key": "calendarId",
           "required": true,
+          "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            }
+          ],
           "description": "Calendar ID, or `primary` / `default` for the signed-in user’s default calendar. Returned by `ask-marcel list-calendars`."
         },
         {
           "name": "start-date-time",
           "key": "startDateTime",
           "required": true,
-          "description": "ISO 8601 lower bound (UTC). Example: `2026-04-01T00:00:00Z`. Required by Graph; the request fails without it."
+          "aliases": [
+            {
+              "name": "start",
+              "key": "start"
+            }
+          ],
+          "description": "Lower bound. ISO 8601 UTC (e.g. `2026-04-01T00:00:00Z` or `2026-04-01`) OR a relative shape: `7d` / `1w` / `2h` / `30m` (past), `+7d` (future), `today` / `yesterday` / `tomorrow` / `now`, `monday`-`sunday` (most recent), `last-<weekday>` / `next-<weekday>`, `start-of-week|month|year`, `end-of-week|month|year`. Relative forms resolve at request time relative to the CLI process clock (UTC)."
         },
         {
           "name": "end-date-time",
           "key": "endDateTime",
           "required": true,
-          "description": "ISO 8601 upper bound (UTC). Example: `2026-05-01T00:00:00Z`. Required by Graph; the request fails without it."
+          "aliases": [
+            {
+              "name": "end",
+              "key": "end"
+            }
+          ],
+          "description": "Upper bound. ISO 8601 UTC (e.g. `2026-04-01T00:00:00Z` or `2026-04-01`) OR a relative shape: `7d` / `1w` / `2h` / `30m` (past), `+7d` (future), `today` / `yesterday` / `tomorrow` / `now`, `monday`-`sunday` (most recent), `last-<weekday>` / `next-<weekday>`, `start-of-week|month|year`, `end-of-week|month|year`. Relative forms resolve at request time relative to the CLI process clock (UTC)."
         },
         {
           "name": "top",
@@ -5628,6 +6632,12 @@
           "name": "team-id",
           "key": "teamId",
           "required": true,
+          "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            }
+          ],
           "description": "Microsoft Teams team ID. Returned by `ask-marcel list-joined-teams`."
         },
         {
@@ -5648,7 +6658,7 @@
     },
     {
       "name": "list-team-installed-apps",
-      "summary": "List the Teams apps installed in a team. The CLI hard-pins `$expand=teamsAppDefinition` so every entry includes `displayName`, `version`, and `distributionMethod` (the bare endpoint returns only opaque IDs). Useful for surfacing which integrations are wired into a given team. Graph rejects standard OData query parameters on this endpoint (`Query option 'Top' is not allowed`); the OData passthrough is intentionally NOT exposed.",
+      "summary": "List the Teams apps installed in a team. The CLI hard-pins `$expand=teamsAppDefinition` so every entry includes `displayName`, `version`, and `distributionMethod` (the bare endpoint returns only opaque IDs). Useful for surfacing which integrations are wired into a given team. Graph rejects user-supplied OData query parameters on this endpoint (`Query option 'Top' is not allowed`) — so the standard OData flags are intentionally NOT exposed here. The response itself is still server-paginated via `@odata.nextLink` when the team has many installed apps; chain with `next-page` to walk subsequent pages.",
       "category": "teams",
       "graphMethod": "GET",
       "graphPathTemplate": "/teams/{team-id}/installedApps?$expand=teamsAppDefinition",
@@ -5658,6 +6668,12 @@
           "name": "team-id",
           "key": "teamId",
           "required": true,
+          "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            }
+          ],
           "description": "Microsoft Teams team ID."
         }
       ],
@@ -5665,6 +6681,114 @@
       "responseShape": "collection of Microsoft Graph `teamsAppInstallation` resources under `value[]`, each with an inline `teamsAppDefinition` (`displayName`, `version`, `distributionMethod`)",
       "pagination": true
     },
+    {
+      "name": "list-teams-chat-history",
+      "summary": "Deep read of a Microsoft Teams chat's message history via the IC3 substrate (`teams.microsoft.com/api/chatsvc/<region>/v1/...`). Unlike `list-teams-chat-messages` (which caps at the 200 most recent messages with no working pagination cursor), this command follows the server-provided `_metadata.syncState` URL backward through history, fetching up to `--page-size` * `--max-pages` messages per invocation (default 200 * 20 = 4000). Uses the IC3-audience bearer captured at login (same Teams web client identity as the basic Teams token). The CLI ships a slim default projection — each message is reduced to `id, sequenceId, composetime, originalarrivaltime, messagetype, from, imdisplayname, content` and `content` is truncated to 4096 chars (with `truncated: true` and `originalContentChars` set on the affected entries). Pass `--full true` to opt out of projection and truncation; pass `--max-content-chars N` to override the truncation cap. **Best-effort, may break on Microsoft client updates** — the IC3 substrate is not in the public Microsoft Graph API. To page beyond `--max-pages`, take the response's `nextSyncState` and pass it back as `--sync-state` on the next call.",
+      "category": "chats",
+      "graphMethod": "GET",
+      "graphPathTemplate": "https://teams.microsoft.com/api/chatsvc/{region}/v1/users/ME/conversations/{chat-id}/messages",
+      "graphDocsUrl": "https://learn.microsoft.com/en-us/graph/api/chatmessage-list",
+      "options": [
+        {
+          "name": "chat-id",
+          "key": "chatId",
+          "required": true,
+          "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            }
+          ],
+          "description": "Teams chat ID — typically `19:<thread>@unq.gbl.spaces` (1:1) or `19:<thread>@thread.v2` (group). Source via `list-chats` or `list-teams-chats-with-messages`."
+        },
+        {
+          "name": "sync-state",
+          "key": "syncState",
+          "required": false,
+          "description": "Opaque pagination URL returned in the prior response's `nextSyncState` field. Pass it back to continue paging backward from where the previous invocation stopped. Omit on the first call."
+        },
+        {
+          "name": "page-size",
+          "key": "pageSize",
+          "required": false,
+          "description": "Messages per IC3 page (positive integer; default 200). Server may silently cap."
+        },
+        {
+          "name": "max-pages",
+          "key": "maxPages",
+          "required": false,
+          "description": "Safety cap on the backward walk (positive integer; default 20). Each page can return up to `--page-size` messages, so default ceiling is ~4000 messages or ~4 MB inline JSON per invocation. Raise carefully — response is buffered fully before returning."
+        },
+        {
+          "name": "full",
+          "key": "full",
+          "required": false,
+          "description": "Pass `--full true` to return the raw IC3 substrate shape (every field on every message, no truncation). Default (`--full false`, or omitted) projects each message down to `id, sequenceId, composetime, originalarrivaltime, messagetype, from, imdisplayname, content` — covering 'who said what, when' without the IC3 envelope noise."
+        },
+        {
+          "name": "max-content-chars",
+          "key": "maxContentChars",
+          "required": false,
+          "description": "When the slim projection is active (i.e. `--full` is not `true`), cap each message `content` at this many characters; messages cut at the cap also carry `truncated: true` and `originalContentChars` so a consumer can decide whether to re-fetch with `--full true`. Default 4096. Ignored when `--full true` is set."
+        }
+      ],
+      "example": "ask-marcel list-teams-chat-history --chat-id '19:abc...@unq.gbl.spaces' --max-pages 5",
+      "responseShape": "`{ messages: [...], hasMore: boolean, pagesFetched: number, nextSyncState?: string, projection: 'slim' | 'full' }`. Slim projection (default) emits `{ id, sequenceId, composetime, originalarrivaltime, messagetype, from, imdisplayname, content }` per message, with `truncated: true` + `originalContentChars` on entries whose `content` exceeded `--max-content-chars` (default 4096). With `--full true`, returns the raw IC3 substrate shape: `id`, `sequenceId` (monotonic per-chat counter), `composetime`, `originalarrivaltime`, `messagetype`, `content`, `from`, `imdisplayname`, `properties.subject`, etc. **`hasMore: true`** means the safety cap was hit and there is older history beyond what was returned — chain a follow-up call with `--sync-state $(jq -r .data.nextSyncState <prev>)` to continue. **`hasMore: false`** means the chat's earliest message was reached. **Microsoft-internal schema — fields may change without notice.**",
+      "needsSubstrateToken": true,
+      "stability": "experimental"
+    },
+    {
+      "name": "list-teams-chat-messages",
+      "summary": "List the most recent messages in a single Microsoft Teams chat via the chat substrate. Companion to `list-teams-chats-with-messages` when the inlined `lastMessage` isn't deep enough. Uses the chatsvcagg-audience bearer captured at login. **Best-effort, may break on Microsoft client updates** — the chat substrate is not in the public Microsoft Graph API. **No pagination**: the route caps at the 200 most recent messages per chat and the CLI cannot reach older history (Teams web itself uses WebSockets for scrollback, and the official `Chat.Read` Graph scope that would enable paginated reads is outside the appid's scope ceiling).",
+      "category": "chats",
+      "graphMethod": "GET",
+      "graphPathTemplate": "https://teams.microsoft.com/api/csa/{region}/api/v1/chats/{chat-id}/messages",
+      "graphDocsUrl": "https://learn.microsoft.com/en-us/graph/api/chatmessage-list",
+      "options": [
+        {
+          "name": "chat-id",
+          "key": "chatId",
+          "required": true,
+          "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            }
+          ],
+          "description": "Teams chat ID — typically `19:<thread>@unq.gbl.spaces` (1:1) or `19:<thread>@thread.v2` (group). Source via `list-chats` or `list-teams-chats-with-messages`."
+        }
+      ],
+      "example": "ask-marcel list-teams-chat-messages --chat-id '19:abc...@unq.gbl.spaces'",
+      "responseShape": "Substrate envelope: `{ messages: [...], messageToken: string }`. Returns up to the 200 most recent messages per chat — older history is NOT reachable via this endpoint. Each message has `id`, `from`, `imDisplayName`, `content`, `contentType`, `composeTime`, `originalArrivalTime`, `sequenceId`, etc. `messageToken` is returned for forward compatibility but is currently a static snapshot identifier (server ignores it as a pagination cursor). **Microsoft-internal schema — fields may change without notice.** For history older than the 200 most recent, use `list-teams-chat-history` (rides the IC3 substrate with a working syncState cursor).",
+      "needsSubstrateToken": true,
+      "stability": "experimental"
+    },
+    {
+      "name": "list-teams-chats-with-messages",
+      "summary": "List the signed-in user's Microsoft Teams chats with the last message body inlined per chat. Uses the chatsvcagg-audience bearer captured at login. Paginated via `continuationToken` (default page size 100; pass the response's `continuationToken` back as `--continuation-token` while `hasMoreData: true`). **Best-effort, may break on Microsoft client updates**: the chat substrate is not part of the public Microsoft Graph API; Microsoft can change route shapes without notice. Caller Graph scopes do NOT matter here; the substrate server gates access on the appid + identity, not on Graph scopes.",
+      "category": "chats",
+      "graphMethod": "GET",
+      "graphPathTemplate": "https://teams.microsoft.com/api/csa/{region}/api/v3/teams/users/me/chats",
+      "graphDocsUrl": "https://learn.microsoft.com/en-us/graph/api/chat-list",
+      "options": [
+        {
+          "name": "page-size",
+          "key": "pageSize",
+          "required": false,
+          "description": "Chats per page (positive integer; default 100, same value Teams web uses). Server may silently cap."
+        },
+        {
+          "name": "continuation-token",
+          "key": "continuationToken",
+          "required": false,
+          "description": "Opaque pagination cursor returned in the prior response's `continuationToken` field. Omit on the first call; loop until `hasMoreData` is false."
+        }
+      ],
+      "example": "ask-marcel list-teams-chats-with-messages --page-size 100",
+      "responseShape": "`{ chats: [...], continuationToken?: string, hasMoreData?: boolean }`. Each chat carries `id`, `title`, `chatType`, `threadType`, `members[]` (with each member's `mri`, `displayName`, `email`), `createdAt`, AND `lastMessage` (the most recent message body inlined — `content`, `from`, `composeTime`, `imDisplayName`, etc.). When `hasMoreData: true`, chain a follow-up call with `--continuation-token \"$(jq -r .data.continuationToken <prev>)\"`. **Microsoft-internal schema — fields may change without notice; treat the response as semi-structured.**",
+      "needsSubstrateToken": true,
+      "stability": "experimental"
+    },
     {
       "name": "list-todo-linked-resources",
       "summary": "List the linked resources (URLs, emails, files) attached to a Microsoft To Do task.",
@@ -5793,6 +6917,10 @@
           "required": true,
           "description": "To Do task list ID. Returned by `ask-marcel list-todo-task-lists`.",
           "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            },
             {
               "name": "task-list-id",
               "key": "taskListId"
@@ -5858,6 +6986,10 @@
           "required": true,
           "description": "Microsoft To Do task list ID. Returned by `list-todo-task-lists`.",
           "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            },
             {
               "name": "task-list-id",
               "key": "taskListId"
@@ -5934,6 +7066,12 @@
           "name": "user-id",
           "key": "userId",
           "required": true,
+          "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            }
+          ],
           "description": "Azure AD user ID or userPrincipalName (UPN) — typically the user's email address. Discover via `list-relevant-people` (relevance-ranked colleagues) or `microsoft-search-query --query <name>` (federated person search across the tenant directory)."
         },
         {
@@ -5998,14 +7136,14 @@
     },
     {
       "name": "my-quick-context",
-      "summary": "One-shot discovery for the IDs every other command needs. Issues nine Graph calls in parallel and returns the IDs each succeeded for. Partial-result mode: only `/me` is load-bearing — if any other sub-call fails (missing license, scope, or tenant policy) the corresponding field is `undefined` but the rest are still returned. Replaces the audit's 5-call discovery chain — feed the IDs straight into `list-mail-folder-messages`, `list-folder-files`, `list-todo-tasks`, `list-planner-tasks`, `list-onenote-notebook-sections`, etc.",
+      "summary": "One-shot discovery for the IDs every other command needs, plus the user's job title and tenant timezone / locale / working-hours. Issues 9 Graph calls in parallel and returns what each succeeded for. Partial-result mode: only `/me` is load-bearing — if any other sub-call fails (missing license, scope, or tenant policy) the corresponding field is `undefined` but the rest are still returned. Replaces the audit's 5-call discovery chain — feed the IDs straight into `list-mail-folder-messages`, `list-folder-files`, `list-planner-tasks`, `list-onenote-notebook-sections`, etc. For Microsoft To Do lists call `list-todo-task-lists` on demand (intentionally dropped from this command's fan-out — the array of {id, displayName, wellknownListName} entries crowded the envelope with IDs an LLM rarely needs on first contact). Audit Jane-session §5.2: `tenantTimeZone` lets an LLM stop treating every datetime as UTC on first contact.",
       "category": "meta",
       "graphMethod": "GET",
-      "graphPathTemplate": "(meta) parallel: /me, /me/drive, /me/mailFolders/inbox, /me/todo/lists, /me/calendar, /me/planner/plans, /me/onenote/notebooks, /me/joinedTeams, /me/drive/recent",
+      "graphPathTemplate": "(meta) parallel: /me, /me/drive, /me/mailFolders/inbox, /me/calendar, /me/planner/plans, /me/onenote/notebooks, /me/joinedTeams, /me/drive/recent, /me/mailboxSettings",
       "graphDocsUrl": "https://learn.microsoft.com/en-us/graph/api/user-get",
       "options": [],
       "example": "ask-marcel my-quick-context",
-      "responseShape": "{ user: { id, displayName, userPrincipalName, mail }, primaryDriveId?, inboxId?, todoLists: [{ id, displayName, wellknownListName }], primaryCalendarId?, primaryPlannerPlanId?, defaultNotebookId?, firstJoinedTeamId?, recentDriveItemId? } — every ID except `user.id` is optional and absent when its source call failed."
+      "responseShape": "`{ user: { id, displayName, userPrincipalName, mail, jobTitle? }, primaryDriveId?, inboxId?, primaryCalendarId?, primaryPlannerPlanId?, defaultNotebookId?, firstJoinedTeamId?, recentDriveItemId?, tenantTimeZone?, tenantLocale?, tenantWorkingHours?: { start, end, timeZone? } }` — every field except `user.id` is optional and absent when its source call failed. `user.jobTitle` is the user's role string from Azure AD (e.g. \"Engineering Manager\"). `tenantTimeZone` is the Outlook timezone string (e.g. \"Romance Standard Time\", \"Pacific Standard Time\"); `tenantLocale` is the IETF tag (e.g. \"en-US\"). For Microsoft To Do lists, call `list-todo-task-lists` separately — they were dropped from this command's fan-out to keep the envelope LLM-tractable."
     },
     {
       "name": "next-page",
@@ -6028,20 +7166,155 @@
       "example": "ask-marcel next-page --url 'https://graph.microsoft.com/v1.0/me/messages?$skip=10'",
       "responseShape": "same shape as the originating endpoint — `{ ok: true, data: { value: [...] }, nextLink: \"...\" }` with the cursor at envelope level."
     },
+    {
+      "name": "read-mail-attachment",
+      "summary": "Read an Outlook mail attachment whatever it is — one command that auto-routes by file type, preferring the content-type when the filename extension is misleading (a real `.jpg` that is actually a spreadsheet still converts), so a caller never has to choose between the convert-mail-attachment-* siblings. A `.zip` fileAttachment is unpacked and every entry converted (mirrors `convert-mail-attachment-zip`, returning the `{ count, files }` envelope; legacy GBK/CP437 names decoded). Any other attachment — docx/xlsx/pptx/odt/ods/odp + macro/template variants → markdown, csv → table, pdf → text layer (with `pageCount`), legacy .xls/.doc extracted, an inner Outlook .msg rendered recursively, plain text passed through, referenceAttachment resolved via `/shares`, and itemAttachment (embedded mail/event/contact) rendered — goes through the same dispatch as `convert-mail-attachment-to-markdown` (returning its `{ contentType, size, text }` envelope). Images, scanned/image-only PDFs, and legacy .ppt return an actionable 415 pointing at `convert-mail-attachment-to-pdf` + a vision model or `get-mail-attachment` for the raw bytes. Pass `--include-metadata true` to append Office side-channel metadata. Use the explicit `convert-mail-attachment-to-markdown` / `-to-pdf` / `-zip` siblings only when you need to force a specific output format.",
+      "category": "mail",
+      "graphMethod": "GET",
+      "graphPathTemplate": "/me/messages/{message-id}/attachments/{attachment-id}",
+      "graphDocsUrl": "https://learn.microsoft.com/en-us/graph/api/attachment-get",
+      "options": [
+        {
+          "name": "message-id",
+          "key": "messageId",
+          "required": true,
+          "description": "Outlook message ID. Returned by `list-mail-messages` or `list-mail-folder-messages`."
+        },
+        {
+          "name": "attachment-id",
+          "key": "attachmentId",
+          "required": true,
+          "description": "Attachment ID inside that message. Returned by `list-mail-attachments`."
+        },
+        {
+          "name": "include-metadata",
+          "key": "includeMetadata",
+          "required": false,
+          "description": "Pass `--include-metadata true` to append each converted Office file’s side-channel metadata block (docx / xlsx / pptx / OpenDocument). No-op on images, embedded items, and plain text.",
+          "argumentHint": {
+            "kind": "magicValue",
+            "values": [
+              "true",
+              "false"
+            ]
+          }
+        }
+      ],
+      "example": "ask-marcel read-mail-attachment --message-id 'AAMkAD...' --attachment-id 'AAMkAD...attach1'",
+      "responseShape": "Polymorphic by attachment content-type. A zip → `{ count, files: [{ path, contentType, size, text } | { path, note }], truncated? }` (the convert-mail-attachment-zip shape). Everything else → `{ contentType: \"text/markdown\" | \"text/plain\", size, text, pageCount? }` (the convert-mail-attachment-to-markdown shape; `pageCount` present for PDF sources). Unsupported types (image / scanned PDF / legacy .ppt) return an api_error (415/400) naming the right next command.",
+      "producesBytes": true
+    },
+    {
+      "name": "resolve-calendar-link",
+      "summary": "Parse a Microsoft Outlook calendar item link (the URL emitted by the \"Copy link\" / share action on a calendar event) into its `eventId`. Pure transformation — no Graph call. Pipe the result into `get-calendar-event` to fetch the event body. For Outlook mail message links use `resolve-mail-link` instead — this command rejects them with a pointer.",
+      "category": "calendar",
+      "graphMethod": "GET",
+      "graphPathTemplate": "{url}",
+      "graphDocsUrl": "https://learn.microsoft.com/en-us/graph/api/event-get",
+      "options": [
+        {
+          "name": "url",
+          "key": "url",
+          "required": true,
+          "description": "Outlook web URL for a single calendar item. Accepted hosts: `outlook.office.com`, `outlook.office365.com`, `outlook.live.com`. Accepted shapes: path-style (`/calendar/item/AAMkA...`) and OWA query-style with calendar path (`/owa/?itemid=AAMkA...&path=/calendar/item`). Mail links (`/mail/...` or `/owa/?itemid=...` without `path=/calendar`) are rejected with `cli_reject_mail_link_on_calendar_resolver` — use `resolve-mail-link` for those."
+        }
+      ],
+      "example": "ask-marcel resolve-calendar-link --url 'https://outlook.office.com/calendar/item/AAMkAGI2THVS...'",
+      "responseShape": "`{ eventId: string }`. `eventId` is URL-decoded and ready to pass to `get-calendar-event --event-id <id>`."
+    },
+    {
+      "name": "resolve-drive-share-link",
+      "summary": "Encode a OneDrive / SharePoint sharing URL into the Graph `/shares/{token}` share token (`u!<base64url>` per [shares-get](https://learn.microsoft.com/en-us/graph/api/shares-get)). Pure transformation — no Graph call. Pipe the returned `graphPath` (`/shares/{token}/driveItem`) into a sibling lookup (`get-drive-item`, `download-drive-item-content`, `convert-mail-attachment-to-pdf`, etc.) once the file has been resolved to a `driveItem`. Accepts any `*.sharepoint.com` URL (tenant + `*-my.sharepoint.com` personal OneDrive) and Microsoft's short-link host `1drv.ms`.",
+      "category": "drive",
+      "graphMethod": "GET",
+      "graphPathTemplate": "{url}",
+      "graphDocsUrl": "https://learn.microsoft.com/en-us/graph/api/shares-get",
+      "options": [
+        {
+          "name": "url",
+          "key": "url",
+          "required": true,
+          "description": "A OneDrive / SharePoint sharing URL — the address from the \"Copy link\" / \"Share\" action in the OneDrive or SharePoint UI. Examples: `https://contoso.sharepoint.com/:b:/s/sitename/EaB1cD...`, `https://contoso-my.sharepoint.com/personal/user_contoso_com/Documents/file.pdf`, `https://1drv.ms/b/s!AbCdEfGh...`. The CLI does not follow the redirect on `1drv.ms` links — the short URL itself is encoded as the share token (Graph resolves it on the server side)."
+        }
+      ],
+      "example": "ask-marcel resolve-drive-share-link --url 'https://contoso.sharepoint.com/:b:/s/team/EaB1cD2eF...?e=abc'",
+      "responseShape": "`{ shareToken: string, graphPath: string, originalUrl: string }`. `shareToken` is the `u!<base64url>` form. `graphPath` is the ready-to-use `/shares/{token}/driveItem` URL — pass it to `ask-marcel next-page --url <link>` for a one-shot driveItem fetch, or feed the `shareToken` into any future `/shares/{token}/...` endpoint. `originalUrl` is echoed back for round-trip confirmation."
+    },
+    {
+      "name": "resolve-mail-link",
+      "summary": "Parse a Microsoft Outlook web mail link (the URL emitted by the \"Copy link\" / address-bar share of an email) into its `messageId`. Pure transformation — no Graph call. Pipe the result into `get-mail-message` to fetch the body, or `convert-mail-to-markdown` to render it. For Outlook calendar links use `resolve-calendar-link` instead — this command rejects them with a pointer.",
+      "category": "mail",
+      "graphMethod": "GET",
+      "graphPathTemplate": "{url}",
+      "graphDocsUrl": "https://learn.microsoft.com/en-us/graph/api/message-get",
+      "options": [
+        {
+          "name": "url",
+          "key": "url",
+          "required": true,
+          "description": "Outlook web URL for a single mail message. Accepted hosts: `outlook.office.com`, `outlook.office365.com`, `outlook.live.com`. Accepted shapes: OWA query-style (`/owa/?itemid=AAMkA...` or `/owa/?ItemID=AAMkA...`), modern path-style (`/mail/inbox/id/AAMkA...`), legacy short (`/mail/AAMkA...`). Calendar links (`/calendar/item/...` or `?path=/calendar/item`) are rejected with `cli_reject_calendar_link_on_mail_resolver` — use `resolve-calendar-link` for those."
+        }
+      ],
+      "example": "ask-marcel resolve-mail-link --url 'https://outlook.office.com/mail/inbox/id/AAMkAGI2THVS...'",
+      "responseShape": "`{ messageId: string }`. `messageId` is URL-decoded and ready to pass to `get-mail-message --message-id <id>` or `convert-mail-to-markdown --message-id <id>`."
+    },
+    {
+      "name": "resolve-teams-link",
+      "summary": "Parse a Microsoft Teams `Copy link` URL (the share link emitted by the message context menu in Teams) into its `chatId` + `messageId` components. Pure transformation — no Graph call. Pipe the result into `get-teams-chat-message` to fetch the message body, or into `list-teams-chat-history` to read the chat that contains it.",
+      "category": "chats",
+      "graphMethod": "GET",
+      "graphPathTemplate": "{url}",
+      "graphDocsUrl": "https://learn.microsoft.com/en-us/graph/api/chatmessage-get",
+      "options": [
+        {
+          "name": "url",
+          "key": "url",
+          "required": true,
+          "description": "Teams message link, copied from Teams web/desktop via the message's `Copy link` action. Expected shape: `https://teams.microsoft.com/l/message/<url-encoded-chat-id>/<message-id>?tenantId=...&groupId=...&ctx=...`"
+        }
+      ],
+      "example": "ask-marcel resolve-teams-link --url 'https://teams.microsoft.com/l/message/19%3A...%40unq.gbl.spaces/1700000000000?tenantId=...&groupId=...&ctx=chat'",
+      "responseShape": "`{ chatId: string, messageId: string, tenantId?: string, groupId?: string, parentMessageId?: string, context?: string }`. `chatId` and `messageId` are URL-decoded and ready to pass to other commands. Optional fields are included only when the source URL carried them."
+    },
     {
       "name": "scopes-check",
-      "summary": "Decode the cached Teams web client access token and return its scopes, audience, and expiry without making a Graph call. Use this as a self-test before running a command an LLM expects to fail with `accessDenied` — if the required scope isn't in the returned list, the call will reject regardless of tenant config. Each command's `scopesRequired` field in `help-json` lists the scopes that command needs; intersect with the array returned here for a pre-flight check (pipe both through `jq` and diff).",
+      "summary": "Decode the cached Teams web client access token and return its scopes, audience, and expiry without making a Graph call. Use this as a self-test before running a command an LLM expects to fail with `accessDenied` — if the required scope isn't in the returned list, the call will reject regardless of tenant config. Each command's `scopesRequired` field in `help-json` lists the scopes that command needs; intersect with the array returned here for a pre-flight check (pipe both through `jq` and diff). The `expiresInSeconds` field (added Jane-session §4) lets an LLM decide pre-emptively to `login` again — typically worth doing under ~5 minutes (300 s) so a long-running session doesn't hit the wall mid-command.",
       "category": "meta",
       "graphMethod": "GET",
       "graphPathTemplate": "(meta) cached-token introspection — no Graph endpoint",
       "graphDocsUrl": "https://learn.microsoft.com/en-us/graph/permissions-reference",
       "options": [],
       "example": "ask-marcel scopes-check",
-      "responseShape": "{ scopes: string[], audience: string, expiresAt: string (ISO 8601) }"
+      "responseShape": "`{ scopes: string[], audience: string, expiresAt: string (ISO 8601), expiresInSeconds: number }`. `expiresInSeconds` is negative when the cached token has already expired (run `login`); `audience` is the JWT `aud` claim (typically `https://graph.microsoft.com`)."
+    },
+    {
+      "name": "search-all-accessible-sites",
+      "summary": "Enumerate EVERY SharePoint site the signed-in user can access via the Microsoft Search index — far more than `search-sharepoint-sites-by-name`, which calls `GET /sites?search=` and returns a single capped page with no continuation. This command deep-pages the Search API (`POST /search/query` with `entityTypes: [\"site\"]`) using `from`/`size`, following the index's own `moreResultsAvailable` flag until exhausted (or the page ceiling of 60×25 = 1500 is reached, signalled by `truncated: true`), and dedupes site resources by id. The index is security-trimmed, so it returns sites you can open even when you are not a member (the gap `list-accessible-drives` cannot fill). Conversely it does NOT return OneDrives, private channel sites, or direct-link-only sites — so the *union of this command and `list-accessible-drives` is the practical maximum reachable on a delegated token* (a truly exhaustive list of every site in the tenant needs admin-only app permissions: `GET /sites/getAllSites`). Sites you cannot open are EXCLUDED so the list is not polluted with 404s: `nonNavigableExcluded` drops add-in app domains, `/contentstorage/` (SharePoint Embedded) containers, and `/_layouts/` system URLs by URL shape (no probe); each remaining site is probed (`GET /sites/{id}?$select=…,siteCollection`) and `archivedExcluded` drops archived / `423 resourceLocked` sites (e.g. an auto-archived OneDrive of a departed user) while `notFoundExcluded` drops probes that 404. Active personal OneDrives are kept. All three counters are omitted when 0. Optional `--query` narrows the index (default `*` = all accessible sites) and keeps the per-site probe cheap.",
+      "category": "sharepoint",
+      "graphMethod": "POST",
+      "graphPathTemplate": "/search/query",
+      "graphDocsUrl": "https://learn.microsoft.com/en-us/graph/api/search-query",
+      "options": [
+        {
+          "name": "query",
+          "key": "query",
+          "required": false,
+          "description": "Optional KQL filter applied to the site index (default `*` = every site you can access). Examples: a name fragment like `budget`, or `contentclass:STS_Site` to restrict to site collections. Free text is matched against site title/url."
+        },
+        {
+          "name": "count-files",
+          "key": "countFiles",
+          "required": false,
+          "description": "Pass `--count-files true` to add `estimatedFileCount` to each kept site — the Microsoft Search index's security-trimmed `driveItem` total (files + folders) scoped to that site's `webUrl` via KQL `path:`. OFF by default because it issues ONE extra Search query per site (chunked, capped at 200) — a real fan-out with 429-throttling risk; narrow with `--query` first. It is an estimate, not an exact count."
+        }
+      ],
+      "example": "ask-marcel search-all-accessible-sites --output json",
+      "responseShape": "`{ value: [<Microsoft Graph site resource: { id, name, displayName?, webUrl, size?, estimatedFileCount?, … }>], count, fileEstimate?, archivedExcluded?, nonNavigableExcluded?, notFoundExcluded?, archiveProbeErrors?, truncated?: true, archiveProbeTruncated?: true }`. `estimatedFileCount` appears only with `--count-files true` — the security-trimmed `driveItem` (files+folders) estimate scoped to each site, omitted past the 200-site count cap or when the per-site query fails. `value[]` is deduped by site `id` across pages; `count` is the number of distinct sites returned (the authoritative figure). `size` (when present) is the site's DEFAULT document library's total bytes used (`drive.quota.used`, recursive) — folded onto the same per-site probe for free, omitted for sites past the probe ceiling or without a default drive; it is a data-volume signal, not a file count. `fileEstimate` (best-effort, omitted if the extra query fails) is the Microsoft Search index's security-trimmed `driveItem` count — roughly how many files+folders the user can access across all of SharePoint/OneDrive. `truncated: true` means paging stopped early (page ceiling hit, or a later page errored) — narrow with `--query` to see the rest; its absence means the sweep ran to completion. `archivedExcluded` (omitted when 0) counts sites dropped as archived/locked by the per-site probe; `nonNavigableExcluded` counts sites dropped by URL shape (add-in app domains, `/contentstorage/` SharePoint Embedded containers, `/_layouts/` system pages); `notFoundExcluded` counts sites whose probe returned 404. `archiveProbeErrors` (omitted when 0) counts sites whose probe failed for an unrelated reason — those are KEPT, so an archived one could slip through. `archiveProbeTruncated: true` means more sites were returned than the probe ceiling (250); the overflow is kept unprobed — narrow with `--query`.",
+      "bodyTemplate": "{ requests: [{ entityTypes: ['site'], query: { queryString: '{query}' }, from: <page*25>, size: 25 }] } — `{query}` defaults to `*` (all accessible sites); re-issued per page, advancing `from` by 25 until `moreResultsAvailable` is false"
     },
     {
       "name": "search-mail-messages",
-      "summary": "Search the signed-in user's entire Outlook mailbox using KQL or free text. Results are ranked by Graph relevance. Note: Graph does not allow `$search` and `$filter` together — the CLI rejects `--filter` client-side with a pointer to `list-mail-messages` (which supports OData filtering). For sorting, server-side `$orderby` is also not allowed with `$search`; use the relevance ranking Graph returns.",
+      "summary": "Search the signed-in user's entire Outlook mailbox using KQL or free text. Results are ranked by Graph relevance. The CLI ships a slim default `--select=id,subject,from,toRecipients,ccRecipients,receivedDateTime,hasAttachments,isRead,importance,bodyPreview` (same as `list-mail-messages`) so a 3-result page stays ~3 KB instead of ~30 KB. Pass `--select id,subject,body` to widen, or override entirely. Note: Graph does not allow `$search` and `$filter` together — the CLI rejects `--filter` client-side with a pointer to `list-mail-messages` (which supports OData filtering). For sorting, server-side `$orderby` is also not allowed with `$search`; use the relevance ranking Graph returns. **KQL quoting gotcha**: pass the raw KQL expression, e.g. `--query 'subject:invoice from:alice'`; do NOT wrap your terms in extra double-quotes (Graph then rejects with `BadRequest: An identifier was expected at position 0` because it sees `\"...\"` after the `$search=` interpolation). The CLI already wraps the entire `--query` value in `\"...\"` on the wire.",
       "category": "mail",
       "graphMethod": "GET",
       "graphPathTemplate": "/me/messages?$search=\"{query}\"",
@@ -6091,7 +7364,7 @@
         }
       ],
       "example": "ask-marcel search-mail-messages --query 'from:alice subject:Q3'",
-      "responseShape": "collection of Microsoft Graph `message` resources under `value[]`, ranked by relevance",
+      "responseShape": "collection of Microsoft Graph `message` resources under `value[]`, ranked by relevance, each projected to the default `--select` set (or the requested fields when overridden). The default omits `body`, `internetMessageHeaders`, and `uniqueBody`.",
       "pagination": true
     },
     {
@@ -6155,7 +7428,13 @@
           "name": "drive-id",
           "key": "driveId",
           "required": true,
-          "description": "Microsoft Graph drive ID to search inside. Returned by `ask-marcel list-drives`."
+          "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            }
+          ],
+          "description": "Microsoft Graph drive ID to search inside. Use `ask-marcel list-drives` for the personal OneDrive, or `ask-marcel list-sharepoint-site-drives --site-id <id>` for a SharePoint document library."
         },
         {
           "name": "query",
@@ -6305,8 +7584,94 @@
         }
       ],
       "example": "ask-marcel search-sharepoint-sites-by-name --query 'marketing'",
-      "responseShape": "collection of Microsoft Graph `site` resources under `value[]` (up to 25)",
+      "responseShape": "collection of Microsoft Graph `site` resources under `value[]` (up to 25), each carrying `size?` — its default document library's total bytes used (`drive.quota.used`, recursive), folded onto the same probe for free (a data-volume signal, not a file count; omitted when the site has no default drive). Sites you cannot open are excluded: `nonNavigableExcluded` drops add-in app domains, `/contentstorage/` (SharePoint Embedded) containers, and `/_layouts/` system URLs by URL shape (no probe); each remaining match is probed (`GET /sites/{id}?$select=…,siteCollection&$expand=drive($select=quota)`) and `archivedExcluded` drops archived / `423 resourceLocked` sites while `notFoundExcluded` drops probes that 404. All three counters are omitted when 0. `archiveProbeErrors` (omitted when 0) counts matches kept because their probe failed for an unrelated reason. Active personal OneDrives are kept.",
       "pagination": true
+    },
+    {
+      "name": "update-mail-draft",
+      "summary": "Update an existing mail draft. PATCH /me/messages/{id} — modifies a draft created by create-mail-draft (or any existing draft in the Drafts folder). Only the fields you pass are updated; omitted fields are left unchanged. At least one field must be provided. Returns the updated message object. Use get-mail-message to verify the final state before sending.",
+      "category": "mail",
+      "graphMethod": "PATCH",
+      "graphPathTemplate": "/me/messages/{message-id}",
+      "graphDocsUrl": "https://learn.microsoft.com/en-us/graph/api/message-update",
+      "options": [
+        {
+          "name": "message-id",
+          "key": "messageId",
+          "required": true,
+          "aliases": [
+            {
+              "name": "id",
+              "key": "id"
+            }
+          ],
+          "description": "Draft message ID to update. Source from create-mail-draft response or list-mail-folder-messages --mail-folder-id drafts. Accepts `--id` as an alias.",
+          "argumentHint": {
+            "kind": "idOrName"
+          }
+        },
+        {
+          "name": "subject",
+          "key": "subject",
+          "required": false,
+          "description": "New email subject line. Omit to keep the current subject."
+        },
+        {
+          "name": "body-content",
+          "key": "bodyContent",
+          "required": false,
+          "description": "New email body content. Replaces the entire body. Pass --body-content-type HTML for rich text."
+        },
+        {
+          "name": "body-content-type",
+          "key": "bodyContentType",
+          "required": false,
+          "description": "Body format for the new body: Text (default) or HTML. Only used when --body-content is provided.",
+          "argumentHint": {
+            "kind": "magicValue",
+            "values": [
+              "Text",
+              "HTML"
+            ]
+          }
+        },
+        {
+          "name": "to-recipients",
+          "key": "toRecipients",
+          "required": false,
+          "description": "Comma-separated list of recipient email addresses. Replaces the entire toRecipients list."
+        },
+        {
+          "name": "cc-recipients",
+          "key": "ccRecipients",
+          "required": false,
+          "description": "Comma-separated list of CC recipient email addresses. Replaces the entire ccRecipients list."
+        },
+        {
+          "name": "bcc-recipients",
+          "key": "bccRecipients",
+          "required": false,
+          "description": "Comma-separated list of BCC recipient email addresses. Replaces the entire bccRecipients list."
+        },
+        {
+          "name": "importance",
+          "key": "importance",
+          "required": false,
+          "description": "Email importance: Low, Normal, or High.",
+          "argumentHint": {
+            "kind": "magicValue",
+            "values": [
+              "Low",
+              "Normal",
+              "High"
+            ]
+          }
+        }
+      ],
+      "example": "ask-marcel update-mail-draft --message-id \"AAMkAD...\" --subject \"Updated: Q3 Report\" --to-recipients \"alice@example.com,charlie@example.com\"",
+      "responseShape": "The updated Microsoft Graph message object: `{ id, subject, body, from, toRecipients, ccRecipients, bccRecipients, receivedDateTime, isDraft, … }`. Graph returns 204 No Content on success with no body — the CLI surfaces `{ ok: true }` in that case.",
+      "bodyTemplate": "{ subject?: '{subject}', body?: { contentType: '{body-content-type}', content: '{body-content}' }, toRecipients?: '{to-recipients}', ccRecipients?: '{cc-recipients}', bccRecipients?: '{bcc-recipients}', importance?: '{importance}' } — only provided fields are sent",
+      "mutates": true
     }
   ]
 }