ask-marcel-office-cli 2.1.0 → 2.3.0

package/dist/commands.json

@@ -1,7 +1,7 @@
 {
   "package": "ask-marcel-office-cli",
-  "version": "2.1.0",
-  "generatedAt": "2026-07-13T10:43:42.181Z",
+  "version": "2.3.0",
+  "generatedAt": "2026-07-24T04:09:19.614Z",
   "commands": [
     {
       "name": "convert-calendar-event-attachment-to-markdown",
@@ -35,6 +35,19 @@
               "false"
             ]
           }
+        },
+        {
+          "name": "keep-quoted",
+          "key": "keepQuoted",
+          "required": false,
+          "description": "Applies to Outlook `.msg` input only. The quoted reply chain / forwarded-message block is stripped by default (it duplicates history and inflates the context budget) and replaced with a single visible marker naming this flag, so nothing is removed silently. Pass `--keep-quoted true` to render the full body. The recognized markers are the same set `convert-mail-to-markdown` uses — see `ask-marcel-office docs convert-mail-to-markdown`.",
+          "argumentHint": {
+            "kind": "magicValue",
+            "values": [
+              "true",
+              "false"
+            ]
+          }
         }
       ],
       "example": "ask-marcel-office convert-calendar-event-attachment-to-markdown --event-id 'AAMkAD...' --attachment-id 'AAMkAD...attach1'",
@@ -67,7 +80,7 @@
       "producesBytes": true
     },
     {
-      "name": "convert-drive-item-zip",
+      "name": "convert-drive-item-zip-to-markdown",
       "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",
@@ -86,6 +99,12 @@
           "required": true,
           "description": "driveItem ID of the .zip file. Returned by `list-folder-files` or `search-onedrive-files`."
         },
+        {
+          "name": "tenant-id",
+          "key": "tenantId",
+          "required": false,
+          "description": "Tenant GUID of a PARTNER tenant you are a guest in, when the file does not live in your own tenant. Get it from `resolve-drive-share-link`, which returns `tenantId` on any sharing URL whose file belongs to another tenant — that is the only place the tenant is knowable, because `--drive-id` and `--item-id` carry no tenant at all. Omit it for files in your own tenant (the normal case). Pass it and the request is signed with a guest token minted for that tenant instead of your home token; without it, a partner-tenant file fails with `invalidAudienceUri` no matter which of your tokens is used."
+        },
         {
           "name": "include-metadata",
           "key": "includeMetadata",
@@ -98,14 +117,27 @@
               "false"
             ]
           }
+        },
+        {
+          "name": "keep-quoted",
+          "key": "keepQuoted",
+          "required": false,
+          "description": "Applies to Outlook `.msg` input only. The quoted reply chain / forwarded-message block is stripped by default (it duplicates history and inflates the context budget) and replaced with a single visible marker naming this flag, so nothing is removed silently. Pass `--keep-quoted true` to render the full body. The recognized markers are the same set `convert-mail-to-markdown` uses — see `ask-marcel-office docs convert-mail-to-markdown`.",
+          "argumentHint": {
+            "kind": "magicValue",
+            "values": [
+              "true",
+              "false"
+            ]
+          }
         }
       ],
-      "example": "ask-marcel-office convert-drive-item-zip --drive-id 'b!1234' --item-id '01ABC'",
+      "example": "ask-marcel-office convert-drive-item-zip-to-markdown --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.",
+      "name": "convert-local-file-to-markdown",
+      "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 with the quoted reply chain stripped — `--keep-quoted true` restores it — and inline `cid:` images shown as placeholders, 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",
@@ -130,6 +162,19 @@
             ]
           }
         },
+        {
+          "name": "keep-quoted",
+          "key": "keepQuoted",
+          "required": false,
+          "description": "Applies to Outlook `.msg` input only. The quoted reply chain / forwarded-message block is stripped by default (it duplicates history and inflates the context budget) and replaced with a single visible marker naming this flag, so nothing is removed silently. Pass `--keep-quoted true` to render the full body. The recognized markers are the same set `convert-mail-to-markdown` uses — see `ask-marcel-office docs convert-mail-to-markdown`.",
+          "argumentHint": {
+            "kind": "magicValue",
+            "values": [
+              "true",
+              "false"
+            ]
+          }
+        },
         {
           "name": "inline-images",
           "key": "inlineImages",
@@ -163,13 +208,13 @@
           "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-office convert-local-file --path ./report.docx",
+      "example": "ask-marcel-office convert-local-file-to-markdown --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). With `--include-images true` each `.zip` entry also carries `images: [{ path, contentType, sizeBytes, base64 }]` when it has extractable embedded images. 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, 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).",
+      "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 (quoted reply chain stripped unless `--keep-quoted true`; inline `cid:` images shown as placeholders) 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}",
@@ -199,6 +244,19 @@
               "false"
             ]
           }
+        },
+        {
+          "name": "keep-quoted",
+          "key": "keepQuoted",
+          "required": false,
+          "description": "Applies to Outlook `.msg` input only. The quoted reply chain / forwarded-message block is stripped by default (it duplicates history and inflates the context budget) and replaced with a single visible marker naming this flag, so nothing is removed silently. Pass `--keep-quoted true` to render the full body. The recognized markers are the same set `convert-mail-to-markdown` uses — see `ask-marcel-office docs convert-mail-to-markdown`.",
+          "argumentHint": {
+            "kind": "magicValue",
+            "values": [
+              "true",
+              "false"
+            ]
+          }
         }
       ],
       "example": "ask-marcel-office convert-mail-attachment-to-markdown --message-id 'AAMkAD...' --attachment-id 'AAMkAD...attach1'",
@@ -231,8 +289,8 @@
       "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).",
+      "name": "convert-mail-attachment-zip-to-markdown",
+      "summary": "Unzip a `.zip` Outlook mail attachment and convert every contained file in one call — the mail-side mirror of `convert-drive-item-zip-to-markdown`, 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}",
@@ -262,14 +320,27 @@
               "false"
             ]
           }
+        },
+        {
+          "name": "keep-quoted",
+          "key": "keepQuoted",
+          "required": false,
+          "description": "Applies to Outlook `.msg` input only. The quoted reply chain / forwarded-message block is stripped by default (it duplicates history and inflates the context budget) and replaced with a single visible marker naming this flag, so nothing is removed silently. Pass `--keep-quoted true` to render the full body. The recognized markers are the same set `convert-mail-to-markdown` uses — see `ask-marcel-office docs convert-mail-to-markdown`.",
+          "argumentHint": {
+            "kind": "magicValue",
+            "values": [
+              "true",
+              "false"
+            ]
+          }
         }
       ],
-      "example": "ask-marcel-office convert-mail-attachment-zip --message-id 'AAMkAD...' --attachment-id 'AAMkAD...attach1'",
+      "example": "ask-marcel-office convert-mail-attachment-zip-to-markdown --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. 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: 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 NO image bytes are fetched: every inline `cid:` image renders as a readable `[inline image: <name>]` placeholder and the images surface in the file-attachments list, so the output stays close to the text size (an email whose 6 KB body carried 30 KB of signature-image base64 now ships at ~6 KB). Pass `--inline-images true` to embed inline images (`isInline:true` + `image/*` content-type, size ≤ 2 MB) as base64 `data:` URIs for self-contained output (non-image inline attachments are never embedded; oversize inline images keep a placeholder note; a cid whose per-image fetch fails degrades to the placeholder too). 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: one call for the body, one for the attachments-metadata list (only if `hasAttachments:true`), and with `--inline-images true` 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}",
@@ -279,25 +350,19 @@
           "name": "message-id",
           "key": "messageId",
           "required": true,
-          "aliases": [
-            {
-              "name": "id",
-              "key": "id"
-            }
-          ],
-          "description": "Outlook message ID. Returned by `list-mail-messages` or `list-mail-folder-messages`. Accepts `--id` as an alias."
+          "description": "Outlook message ID. Returned by `list-mail-messages` or `list-mail-folder-messages`."
         },
         {
           "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."
+          "description": "Pass `--inline-images true` to fetch small inline images (≤ 2 MB, `image/*` only) and embed them as base64 `data:` URIs. Default is `false` (text-first): no per-image bytes fetch, and every inline `cid:` image renders as a `[inline image: <name>]` placeholder while still appearing in the file-attachments list, so the LLM caller sees what exists and can fetch any specific image via `get-mail-attachment` on demand. Embedding a 6-inline-image email inflated a 6 KB body to ~36 KB; the default keeps it near 6 KB."
         },
         {
           "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.",
+          "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`, Gmail `gmail_quote`, the Outlook reply border separator (`#E1E1E1` on desktop, `#B5C4DF` on Mac/mobile), and a bold `From:`/`Sent:` header-label pair (localized variants recognized: 发件人/发送时间, De/Envoyé, Von/Gesendet, Da/Inviato, De/Enviado, Van/Verzonden, 差出人/送信日時, 보낸 사람/보낸 날짜 — a lone bolded \"From:\" without its companion label never cuts); in plain-text bodies the `Original Message` banner, the `On … wrote:` attribution line, leading `>` quote lines, and the same localized `From:`+`Sent:` line pairs.",
           "argumentHint": {
             "kind": "magicValue",
             "values": [
@@ -323,13 +388,7 @@
           "name": "forward-message-id",
           "key": "forwardMessageId",
           "required": true,
-          "aliases": [
-            {
-              "name": "id",
-              "key": "id"
-            }
-          ],
-          "description": "The message being forwarded. Source from list-mail-folder-messages or search-mail-messages. Accepts `--id` as an alias.",
+          "description": "The message being forwarded. Source from list-mail-folder-messages or search-mail-messages.",
           "argumentHint": {
             "kind": "idOrName"
           }
@@ -347,26 +406,39 @@
           "description": "Comma-separated list of CC recipient email addresses."
         },
         {
-          "name": "body-content",
-          "key": "bodyContent",
+          "name": "comment",
+          "key": "comment",
           "required": true,
-          "description": "The comment text, placed above the quoted forwarded message by Graph."
+          "description": "The comment text, placed above the quoted forwarded message. Named for Graph's own createForward payload field, and the same word update-mail-draft uses for the same role. Plain text by default; pass --body-content-type HTML to send it as markup."
         },
         {
           "name": "subject",
           "key": "subject",
           "required": false,
           "description": "Optional subject override. Omit to keep the inherited \"FW: ...\" subject."
+        },
+        {
+          "name": "body-content-type",
+          "key": "bodyContentType",
+          "required": false,
+          "description": "Format of --comment: Text (default) or HTML. Text is handed to Graph as the forward comment, which HTML-escapes it, so markup shows as literal characters. HTML instead creates the draft with an empty comment and splices your markup in at the TOP of the body — above Graph's separator (the `<hr>` line) and the forwarded original, so your comment leads the body content — leaving the original and its styles byte-identical. Rejected when your markup itself contains a quote boundary marker (a pasted reply chain), and when the original is a plain-text message.",
+          "argumentHint": {
+            "kind": "magicValue",
+            "values": [
+              "Text",
+              "HTML"
+            ]
+          }
         }
       ],
-      "example": "ask-marcel-office create-forward-draft --forward-message-id \"AAMkAD...\" --to-recipients \"bob@example.com\" --body-content \"Bob owns this now, forwarding for your action.\"",
-      "responseShape": "The updated draft message object (or `{ ok: true }` when Graph answers 204): `{ id, subject, body, toRecipients, ccRecipients, isDraft: true, … }`. The `id` is the draft - update further with update-mail-draft, or open Outlook Drafts to review and send.",
-      "bodyTemplate": "POST { comment: '{body-content}', toRecipients: '{to-recipients}' } then optional PATCH { ccRecipients?: '{cc-recipients}', subject?: '{subject}' }",
+      "example": "ask-marcel-office create-forward-draft --forward-message-id \"AAMkAD...\" --to-recipients \"bob@example.com\" --comment \"Bob owns this now, forwarding for your action.\"",
+      "responseShape": "A confirmation of the write, NOT the whole message: `{ id, subject, toRecipients, ccRecipients, bccRecipients, importance, bodyPreview, isDraft, webLink, conversationId }` (only the fields Graph returned; `{ ok: true }` when Graph answers 204). The `body` is deliberately omitted — you just wrote it, and echoing a long thread's quoted history back cost ~174 KB of context per call. Read the full body with `get-mail-message --id <the returned id>` when you actually need it; `bodyPreview` is Graph's ~255-char summary, enough to confirm WHICH draft answered. The `id` is the draft — refine it with `update-mail-draft`, or open Outlook Drafts to review and send. Dedup caveat: a `conversationId` `$filter` on the Drafts folder is not a reliable 'does a draft already exist on this thread' check. Reply and forward drafts do not always inherit the inbound message's `conversationId` (one thread can split across several), and Graph `$filter` on Drafts is not read-your-writes consistent, so a just-created draft can be missed. To find existing drafts, use the `find-mail-drafts` command, which scans recent drafts and matches client-side on subject and recipients; to revise a draft this session created, reuse the returned `id`.",
+      "bodyTemplate": "Text: POST { comment: '{comment}', toRecipients: '{to-recipients}' } then optional PATCH { ccRecipients?: '{cc-recipients}', subject?: '{subject}' }. HTML ({body-content-type}): POST { comment: '', toRecipients: '{to-recipients}' } then ONE PATCH { body: { contentType: 'HTML', content: <'{comment}' spliced at the top of the body, above Graph's <hr> separator and the quote> }, ccRecipients?: '{cc-recipients}', subject?: '{subject}' }",
       "mutates": 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.",
+      "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 a slim confirmation (id, subject, recipients, importance, bodyPreview, …) - NOT the body you just wrote; read the full draft back with get-mail-message if you need it. Use the returned id with update-mail-draft to modify before sending.",
       "category": "mail",
       "graphMethod": "POST",
       "graphPathTemplate": "/me/messages (or /me/mailFolders/{mail-folder-id}/messages)",
@@ -440,49 +512,69 @@
         }
       ],
       "example": "ask-marcel-office 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.",
+      "responseShape": "A confirmation of the write, NOT the whole message: `{ id, subject, toRecipients, ccRecipients, bccRecipients, importance, bodyPreview, isDraft, webLink, conversationId }` (only the fields Graph returned; `{ ok: true }` when Graph answers 204). The `body` is deliberately omitted — you just supplied it; read it back with `get-mail-message --id <the returned id>` if you need it. The `id` is the draft — modify it with `update-mail-draft` 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": "create-reply-draft",
-      "summary": "Create an UNSENT reply-all draft threaded on an existing message. POST /me/messages/{id}/createReplyAll mints the draft (inherited recipients, RE: subject, quoted history) with your reply text placed above the quote, in one call. Reply-all by design - dropping recipients is a deliberate act for the human in Outlook, not a default. The draft is saved in Drafts and can be reviewed, edited, and sent from any Outlook client; the CLI still cannot send.",
+      "summary": "Create an UNSENT reply draft threaded on an existing message. POST /me/messages/{id}/createReplyAll mints the draft (inherited recipients, RE: subject, quoted history) with your reply text placed above the quote, in one call. Reply-all by default - dropping recipients is a deliberate act, so pass --reply-all false to reply to the sender only, which switches the action to createReply. The draft is saved in Drafts and can be reviewed, edited, and sent from any Outlook client; the CLI still cannot send.",
       "category": "mail",
       "graphMethod": "POST",
-      "graphPathTemplate": "/me/messages/{reply-to-message-id}/createReplyAll (+ optional body-free PATCH for subject)",
+      "graphPathTemplate": "/me/messages/{reply-to-message-id}/createReplyAll, or /createReply when {reply-all} is false (+ optional body-free PATCH for subject)",
       "graphDocsUrl": "https://learn.microsoft.com/en-us/graph/api/message-createreplyall",
       "options": [
         {
           "name": "reply-to-message-id",
           "key": "replyToMessageId",
           "required": true,
-          "aliases": [
-            {
-              "name": "id",
-              "key": "id"
-            }
-          ],
-          "description": "The message being replied to. Source from list-mail-folder-messages or search-mail-messages. Accepts `--id` as an alias.",
+          "description": "The message being replied to. Source from list-mail-folder-messages or search-mail-messages.",
           "argumentHint": {
             "kind": "idOrName"
           }
         },
         {
-          "name": "body-content",
-          "key": "bodyContent",
+          "name": "comment",
+          "key": "comment",
           "required": true,
-          "description": "The reply text, placed above the quoted history by Graph."
+          "description": "The reply text, placed above the quoted history. Named for Graph's own createReply payload field, and the same word update-mail-draft uses for the same role. Plain text by default; pass --body-content-type HTML to send it as markup."
+        },
+        {
+          "name": "body-content-type",
+          "key": "bodyContentType",
+          "required": false,
+          "description": "Format of --comment: Text (default) or HTML. Text is handed to Graph as the reply comment, which HTML-escapes it, so markup shows as literal characters. HTML instead creates the draft with an empty comment and splices your markup in at the TOP of the body — above Graph's reply separator (the `<hr>` line) and the quoted thread, so your reply leads the body content — leaving the quoted thread and its styles byte-identical. Rejected when your markup itself contains a quote boundary marker (a pasted reply chain), and when the thread is a plain-text one.",
+          "argumentHint": {
+            "kind": "magicValue",
+            "values": [
+              "Text",
+              "HTML"
+            ]
+          }
         },
         {
           "name": "subject",
           "key": "subject",
           "required": false,
           "description": "Optional subject override. Omit to keep the inherited \"RE: ...\" subject."
+        },
+        {
+          "name": "reply-all",
+          "key": "replyAll",
+          "required": false,
+          "description": "Who the draft replies to. Defaults to true (everyone on the thread: sender + To + Cc, via createReplyAll). Pass `false` to reply to the sender only, via createReply. Only an explicit `false` narrows the recipients - anything else keeps reply-all.",
+          "argumentHint": {
+            "kind": "magicValue",
+            "values": [
+              "true",
+              "false"
+            ]
+          }
         }
       ],
-      "example": "ask-marcel-office create-reply-draft --reply-to-message-id \"AAMkAD...\" --body-content \"Confirmed for Concur, aligned with the group choice.\"",
-      "responseShape": "The updated draft message object (or `{ ok: true }` when Graph answers 204): `{ id, subject, body, toRecipients, ccRecipients, isDraft: true, … }`. The `id` is the draft - update further with update-mail-draft, or open Outlook Drafts to review and send.",
-      "bodyTemplate": "POST { comment: '{body-content}' } then optional PATCH { subject?: '{subject}' }",
+      "example": "ask-marcel-office create-reply-draft --reply-to-message-id \"AAMkAD...\" --comment \"Confirmed for Contoso, aligned with the group choice.\"",
+      "responseShape": "A confirmation of the write, NOT the whole message: `{ id, subject, toRecipients, ccRecipients, bccRecipients, importance, bodyPreview, isDraft, webLink, conversationId }` (only the fields Graph returned; `{ ok: true }` when Graph answers 204). The `body` is deliberately omitted — you just wrote it, and echoing a long thread's quoted history back cost ~174 KB of context per call. Read the full body with `get-mail-message --id <the returned id>` when you actually need it; `bodyPreview` is Graph's ~255-char summary, enough to confirm WHICH draft answered. The `id` is the draft — refine it with `update-mail-draft`, or open Outlook Drafts to review and send. Dedup caveat: a `conversationId` `$filter` on the Drafts folder is not a reliable 'does a draft already exist on this thread' check. Reply and forward drafts do not always inherit the inbound message's `conversationId` (one thread can split across several), and Graph `$filter` on Drafts is not read-your-writes consistent, so a just-created draft can be missed. To find existing drafts, use the `find-mail-drafts` command, which scans recent drafts and matches client-side on subject and recipients; to revise a draft this session created, reuse the returned `id`.",
+      "bodyTemplate": "Text: POST { comment: '{comment}' } then optional PATCH { subject?: '{subject}' }. HTML ({body-content-type}): POST { comment: '' } then ONE PATCH { body: { contentType: 'HTML', content: <'{comment}' spliced at the top of the body, above Graph's <hr> separator and the quote> }, subject?: '{subject}' }",
       "mutates": true
     },
     {
@@ -505,6 +597,12 @@
           "required": true,
           "description": "driveItem ID of the file to convert. Returned by `list-folder-files` or `search-onedrive-files`."
         },
+        {
+          "name": "tenant-id",
+          "key": "tenantId",
+          "required": false,
+          "description": "Tenant GUID of a PARTNER tenant you are a guest in, when the file does not live in your own tenant. Get it from `resolve-drive-share-link`, which returns `tenantId` on any sharing URL whose file belongs to another tenant — that is the only place the tenant is knowable, because `--drive-id` and `--item-id` carry no tenant at all. Omit it for files in your own tenant (the normal case). Pass it and the request is signed with a guest token minted for that tenant instead of your home token; without it, a partner-tenant file fails with `invalidAudienceUri` no matter which of your tokens is used."
+        },
         {
           "name": "include-metadata",
           "key": "includeMetadata",
@@ -518,6 +616,19 @@
             ]
           }
         },
+        {
+          "name": "keep-quoted",
+          "key": "keepQuoted",
+          "required": false,
+          "description": "Applies to Outlook `.msg` input only. The quoted reply chain / forwarded-message block is stripped by default (it duplicates history and inflates the context budget) and replaced with a single visible marker naming this flag, so nothing is removed silently. Pass `--keep-quoted true` to render the full body. The recognized markers are the same set `convert-mail-to-markdown` uses — see `ask-marcel-office docs convert-mail-to-markdown`.",
+          "argumentHint": {
+            "kind": "magicValue",
+            "values": [
+              "true",
+              "false"
+            ]
+          }
+        },
         {
           "name": "inline-images",
           "key": "inlineImages",
@@ -561,6 +672,12 @@
           "key": "itemId",
           "required": true,
           "description": "driveItem ID of the file to convert. Returned by `list-folder-files` or `search-onedrive-files`."
+        },
+        {
+          "name": "tenant-id",
+          "key": "tenantId",
+          "required": false,
+          "description": "Tenant GUID of a PARTNER tenant you are a guest in, when the file does not live in your own tenant. Get it from `resolve-drive-share-link`, which returns `tenantId` on any sharing URL whose file belongs to another tenant — that is the only place the tenant is knowable, because `--drive-id` and `--item-id` carry no tenant at all. Omit it for files in your own tenant (the normal case). Pass it and the request is signed with a guest token minted for that tenant instead of your home token; without it, a partner-tenant file fails with `invalidAudienceUri` no matter which of your tokens is used."
         }
       ],
       "example": "ask-marcel-office download-drive-item-as-pdf --drive-id 'b!1234' --item-id '01ABC'",
@@ -571,9 +688,6 @@
       "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}/content",
       "graphDocsUrl": "https://learn.microsoft.com/en-us/graph/api/driveitem-get-content",
@@ -589,6 +703,12 @@
           "key": "itemId",
           "required": true,
           "description": "driveItem ID of the file to download. Returned by `ask-marcel-office list-folder-files` (works on SharePoint library drives too) or `search-onedrive-files`."
+        },
+        {
+          "name": "tenant-id",
+          "key": "tenantId",
+          "required": false,
+          "description": "Tenant GUID of a PARTNER tenant you are a guest in, when the file does not live in your own tenant. Get it from `resolve-drive-share-link`, which returns `tenantId` on any sharing URL whose file belongs to another tenant — that is the only place the tenant is knowable, because `--drive-id` and `--item-id` carry no tenant at all. Omit it for files in your own tenant (the normal case). Pass it and the request is signed with a guest token minted for that tenant instead of your home token; without it, a partner-tenant file fails with `invalidAudienceUri` no matter which of your tokens is used."
         }
       ],
       "example": "ask-marcel-office download-drive-item-content --drive-id 'b!1234' --item-id '01ABC'",
@@ -673,6 +793,12 @@
           "key": "itemId",
           "required": true,
           "description": "driveItem ID of the pdf / docx / xlsx / pptx file. Returned by `list-folder-files` or `search-onedrive-files`."
+        },
+        {
+          "name": "tenant-id",
+          "key": "tenantId",
+          "required": false,
+          "description": "Tenant GUID of a PARTNER tenant you are a guest in, when the file does not live in your own tenant. Get it from `resolve-drive-share-link`, which returns `tenantId` on any sharing URL whose file belongs to another tenant — that is the only place the tenant is knowable, because `--drive-id` and `--item-id` carry no tenant at all. Omit it for files in your own tenant (the normal case). Pass it and the request is signed with a guest token minted for that tenant instead of your home token; without it, a partner-tenant file fails with `invalidAudienceUri` no matter which of your tokens is used."
         }
       ],
       "example": "ask-marcel-office extract-drive-item-images --drive-id 'b!1234' --item-id '01ABC' --output-dir ./deck-images",
@@ -681,7 +807,7 @@
     },
     {
       "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.",
+      "summary": "Extract the embedded images from a file ON DISK — the local sibling of `extract-drive-item-images`, and like `convert-local-file-to-markdown` 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",
@@ -759,13 +885,7 @@
           "name": "message-id",
           "key": "messageId",
           "required": true,
-          "aliases": [
-            {
-              "name": "id",
-              "key": "id"
-            }
-          ],
-          "description": "Outlook message ID. Returned by `list-mail-messages` or `list-mail-folder-messages`. Accepts `--id` as an alias."
+          "description": "Outlook message ID. Returned by `list-mail-messages` or `list-mail-folder-messages`."
         }
       ],
       "example": "ask-marcel-office extract-sharepoint-links-in-mail --message-id 'AAMkADk0...'",
@@ -800,9 +920,33 @@
       ],
       "example": "ask-marcel-office find-chats-with-user --name 'Alex Kim'",
       "responseShape": "`{ name, matches: [{ chatId, title, chatType, threadType, memberCount, lastMessageAt?, matchedMembers: [{ mri, displayName, email, userSubType }] }], matchCount, pagesFetched, chatsScanned, chatsHydrated, unresolvedMemberCount, hasMore, nextContinuationToken?, hint? }`. `matchedMembers` always carries the matching entries' identifying fields — pass `chatId` into `list-teams-chat-history` to read message bodies. `chatsHydrated` counts the per-chat members lookups spent resolving bare cross-tenant members in direct (1:1) chats. `unresolvedMemberCount` is how many cross-tenant members are still unresolved by name (bare members in group/meeting chats, which are not deep-probed, plus any 1:1 hydration that errored); when `matchCount` is 0 and this is non-zero, a `hint` is present explaining the likely cause and the object-id / read-by-chat-id remedy — so an empty result is never silently confident. `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,
+      "needsSubstrateToken": "chatsvcagg",
       "stability": "experimental"
     },
+    {
+      "name": "find-mail-drafts",
+      "summary": "Find existing drafts on a mail thread WITHOUT trusting a conversationId $filter. Reply and forward drafts do not always inherit the inbound message conversationId (a thread can split across several), and Graph $filter on the Drafts folder is not read-your-writes consistent, so filtering Drafts by conversationId misses drafts. This command instead scans the 50 most recently modified drafts and matches them client-side on a normalized subject (stripping RE:/FW: and localized reply/forward prefixes) plus, optionally, a shared recipient. Use it before create-reply-draft to avoid creating a duplicate: if a match comes back, revise it with update-mail-draft instead of making a new one. Read-only.",
+      "category": "mail",
+      "graphMethod": "GET",
+      "graphPathTemplate": "/me/mailFolders/drafts/messages?$top=50&$orderby=lastModifiedDateTime desc&$select=id,subject,toRecipients,ccRecipients,conversationId,lastModifiedDateTime,webLink (a read-only scan of the 50 most recently modified drafts; each is matched CLIENT-SIDE on a normalized {subject} and, when given, a shared {to-recipients} address, so neither value is sent to Graph)",
+      "graphDocsUrl": "https://learn.microsoft.com/en-us/graph/api/mailfolder-list-messages",
+      "options": [
+        {
+          "name": "subject",
+          "key": "subject",
+          "required": true,
+          "description": "The thread subject to match. Reply and forward prefixes (RE:, FW:, and localized variants) are stripped on both sides before comparing, so \"Contoso Q3\" matches a draft titled \"RE: Contoso Q3\"."
+        },
+        {
+          "name": "to-recipients",
+          "key": "toRecipients",
+          "required": false,
+          "description": "Optional comma-separated recipient addresses. When given, a draft matches only if it shares at least one To or Cc address with this list, narrowing subject-only collisions."
+        }
+      ],
+      "example": "ask-marcel-office find-mail-drafts --subject \"Contoso Q3 budget\" --to-recipients \"kim@example.com\"",
+      "responseShape": "`{ matches: message[], conversationIds: string[], scanned: number, scanLimit: number }`. `matches` are the drafts whose normalized subject (RE:/FW:/localized prefixes stripped) equals yours, each carrying `{ id, subject, toRecipients, ccRecipients, conversationId, lastModifiedDateTime, webLink }`; pass a match `id` to update-mail-draft to revise it instead of creating a duplicate. `conversationIds` is the de-duplicated union of conversationIds across the matches (a thread can span several). `scanned` is how many drafts were examined and `scanLimit` the cap (50): when `scanned` equals `scanLimit`, older drafts may exist beyond the window."
+    },
     {
       "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).",
@@ -815,12 +959,6 @@
           "name": "event-id",
           "key": "eventId",
           "required": true,
-          "aliases": [
-            {
-              "name": "id",
-              "key": "id"
-            }
-          ],
           "description": "Microsoft Graph event ID. Returned by `ask-marcel-office list-calendar-events` in the `id` field of each event."
         },
         {
@@ -887,12 +1025,6 @@
           "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`."
         },
         {
@@ -954,13 +1086,7 @@
           "name": "item-id",
           "key": "itemId",
           "required": true,
-          "description": "driveItem ID of the folder whose subtree to track. Use the root folder ID from `get-drive-root-item` to track the entire drive. Accepts `--folder-id` as an alias for parity with `list-folder-files` (same concept, same flag name).",
-          "aliases": [
-            {
-              "name": "folder-id",
-              "key": "folderId"
-            }
-          ]
+          "description": "driveItem ID of the folder whose subtree to track. Use the root folder ID from `get-drive-root-item` to track the entire drive."
         },
         {
           "name": "top",
@@ -974,18 +1100,6 @@
           "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",
@@ -1017,6 +1131,12 @@
           "required": true,
           "description": "driveItem ID. Returned by `list-folder-files`, `search-onedrive-files`, or `get-drive-root-item`."
         },
+        {
+          "name": "tenant-id",
+          "key": "tenantId",
+          "required": false,
+          "description": "Tenant GUID of a PARTNER tenant you are a guest in, when the file does not live in your own tenant. Get it from `resolve-drive-share-link`, which returns `tenantId` on any sharing URL whose file belongs to another tenant — that is the only place the tenant is knowable, because `--drive-id` and `--item-id` carry no tenant at all. Omit it for files in your own tenant (the normal case). Pass it and the request is signed with a guest token minted for that tenant instead of your home token; without it, a partner-tenant file fails with `invalidAudienceUri` no matter which of your tokens is used."
+        },
         {
           "name": "select",
           "key": "select",
@@ -1160,6 +1280,12 @@
           "key": "expand",
           "required": false,
           "description": "OData $expand: navigation properties to include inline (e.g. `attachments`). Increases response size; use sparingly."
+        },
+        {
+          "name": "tenant-id",
+          "key": "tenantId",
+          "required": false,
+          "description": "Tenant GUID of a PARTNER tenant you are a guest in, when the file does not live in your own tenant. Get it from `resolve-drive-share-link`, which returns `tenantId` on any sharing URL whose file belongs to another tenant — that is the only place the tenant is knowable, because `--drive-id` and `--item-id` carry no tenant at all. Omit it for files in your own tenant (the normal case). Pass it and the request is signed with a guest token minted for that tenant instead of your home token; without it, a partner-tenant file fails with `invalidAudienceUri` no matter which of your tokens is used."
         }
       ],
       "example": "ask-marcel-office get-drive-item-list-item --drive-id 'b!1234' --item-id '01ABC'",
@@ -1185,18 +1311,6 @@
           "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",
@@ -1220,12 +1334,6 @@
           "name": "drive-id",
           "key": "driveId",
           "required": true,
-          "aliases": [
-            {
-              "name": "id",
-              "key": "id"
-            }
-          ],
           "description": "Microsoft Graph drive ID. Use `ask-marcel-office list-drives` for the personal OneDrive, or `ask-marcel-office list-sharepoint-site-drives --site-id <id>` for a SharePoint document library."
         },
         {
@@ -1446,12 +1554,6 @@
           "name": "group-id",
           "key": "groupId",
           "required": true,
-          "aliases": [
-            {
-              "name": "id",
-              "key": "id"
-            }
-          ],
           "description": "Azure AD group object ID. Use `list-groups` to find one."
         },
         {
@@ -1509,7 +1611,7 @@
     },
     {
       "name": "get-mail-message",
-      "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.",
+      "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,conversationId` (`conversationId` gives you the thread, e.g. for `list-conversation-messages`) 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}",
@@ -1519,13 +1621,7 @@
           "name": "message-id",
           "key": "messageId",
           "required": true,
-          "aliases": [
-            {
-              "name": "id",
-              "key": "id"
-            }
-          ],
-          "description": "Outlook message ID. Returned by `ask-marcel-office list-mail-messages` or `list-mail-folder-messages`. Accepts `--id` as an alias."
+          "description": "Outlook message ID. Returned by `ask-marcel-office list-mail-messages` or `list-mail-folder-messages`."
         },
         {
           "name": "select",
@@ -1555,13 +1651,7 @@
           "name": "message-id",
           "key": "messageId",
           "required": true,
-          "aliases": [
-            {
-              "name": "id",
-              "key": "id"
-            }
-          ],
-          "description": "Outlook message ID. Returned by `list-mail-messages` or `search-mail-messages`. Accepts `--id` as an alias."
+          "description": "Outlook message ID. Returned by `list-mail-messages` or `search-mail-messages`."
         }
       ],
       "example": "ask-marcel-office get-mail-message-mime --message-id 'AAMkAD...'",
@@ -1586,22 +1676,34 @@
           "name": "message-rule-id",
           "key": "messageRuleId",
           "required": true,
-          "description": "Message rule ID. Returned by `list-mail-rules`.",
-          "aliases": [
-            {
-              "name": "id",
-              "key": "id"
-            },
-            {
-              "name": "rule-id",
-              "key": "ruleId"
-            }
-          ]
+          "description": "Message rule ID. Returned by `list-mail-rules`."
         }
       ],
       "example": "ask-marcel-office get-mail-rule --message-rule-id 'AQAAANC...'",
       "responseShape": "single Microsoft Graph `messageRule` resource"
     },
+    {
+      "name": "get-mail-signature",
+      "summary": "Read your own email signature as HTML, lifted from a message you already sent. Graph-created drafts carry NO signature (create-mail-draft, create-reply-draft, and create-forward-draft all produce unsigned bodies), so this is where you get one: take the `text` this returns, append it to your reply text, and hand the result to `update-mail-draft` in comment mode (HTML body-content-type) to place it above the quoted history. Scans your last 10 sent messages newest-first and returns the first `<div id=\"Signature\">` block it finds, stopping there, with any logo the block references embedded as a base64 data: URI so the HTML renders on its own. Read-only. NOTE: the marker is written by Outlook on the web and new Outlook; mail composed in Outlook desktop does not carry it, so pin a webmail-sent message with --message-id if the scan finds nothing.",
+      "category": "mail",
+      "graphMethod": "GET",
+      "graphPathTemplate": "/me/mailFolders/sentitems/messages (scan, skipped when {message-id} is given) then /me/messages/{message-id}?$select=body,sentDateTime,hasAttachments (+ /attachments per referenced logo)",
+      "graphDocsUrl": "https://learn.microsoft.com/en-us/graph/api/message-get",
+      "options": [
+        {
+          "name": "message-id",
+          "key": "messageId",
+          "required": false,
+          "description": "Read the signature from THIS message instead of scanning the sent folder. Use when the scan finds nothing (the message was composed in Outlook desktop) or to pin a specific signature. Source from list-mail-folder-messages --mail-folder-id sentitems.",
+          "argumentHint": {
+            "kind": "idOrName"
+          }
+        }
+      ],
+      "example": "ask-marcel-office get-mail-signature",
+      "responseShape": "`{ contentType: \"text/html\", size, text, sourceMessageId, sentDateTime?, inlinedImages, note? }`. `text` is the signature block itself (the `<div id=\"Signature\">` element, not the whole body), ready to append to a reply. `inlinedImages` counts the logos embedded as data: URIs; any image too large (> 2 MB) or unfetchable keeps its raw `cid:` reference and is named in `note` — no placeholder is substituted, so the reference stays resolvable via get-mail-attachment. `--output-path` writes the HTML to a file.",
+      "producesBytes": true
+    },
     {
       "name": "get-mailbox-settings",
       "summary": "Get the signed-in user's Outlook mailbox settings (timezone, working hours, automatic replies). Note: Graph silently ignores `$select` / `$expand` on this endpoint, so the CLI does NOT expose them — the full payload (including the auto-reply HTML body) is always returned. Slim client-side if you only need a subset.",
@@ -1685,17 +1787,7 @@
           "name": "onenote-page-id",
           "key": "onenotePageId",
           "required": true,
-          "description": "OneNote page ID. Returned by `ask-marcel-office list-onenote-section-pages`.",
-          "aliases": [
-            {
-              "name": "id",
-              "key": "id"
-            },
-            {
-              "name": "page-id",
-              "key": "pageId"
-            }
-          ]
+          "description": "OneNote page ID. Returned by `ask-marcel-office list-onenote-section-pages`."
         },
         {
           "name": "inline-images",
@@ -1740,17 +1832,7 @@
           "name": "onenote-page-id",
           "key": "onenotePageId",
           "required": true,
-          "description": "OneNote page ID. Returned by `ask-marcel-office list-onenote-section-pages`.",
-          "aliases": [
-            {
-              "name": "id",
-              "key": "id"
-            },
-            {
-              "name": "page-id",
-              "key": "pageId"
-            }
-          ]
+          "description": "OneNote page ID. Returned by `ask-marcel-office list-onenote-section-pages`."
         }
       ],
       "example": "ask-marcel-office get-onenote-page-content --onenote-page-id '1-abc...'",
@@ -1793,17 +1875,7 @@
           "name": "planner-bucket-id",
           "key": "plannerBucketId",
           "required": true,
-          "description": "Planner bucket ID. Returned by `ask-marcel-office list-plan-buckets`.",
-          "aliases": [
-            {
-              "name": "id",
-              "key": "id"
-            },
-            {
-              "name": "bucket-id",
-              "key": "bucketId"
-            }
-          ]
+          "description": "Planner bucket ID. Returned by `ask-marcel-office list-plan-buckets`."
         }
       ],
       "example": "ask-marcel-office get-planner-bucket --planner-bucket-id 'sFNeQRFu_kqhxpwwAhmA15gAGfoT'",
@@ -1821,17 +1893,7 @@
           "name": "planner-plan-id",
           "key": "plannerPlanId",
           "required": true,
-          "description": "Planner plan ID. Returned in the `planId` field of any task from `ask-marcel-office list-planner-tasks`.",
-          "aliases": [
-            {
-              "name": "id",
-              "key": "id"
-            },
-            {
-              "name": "plan-id",
-              "key": "planId"
-            }
-          ]
+          "description": "Planner plan ID. Returned in the `planId` field of any task from `ask-marcel-office list-planner-tasks`."
         }
       ],
       "example": "ask-marcel-office get-planner-plan --planner-plan-id 'xqQg5FS2LkCp935s-FIFm5gAB6'",
@@ -1849,17 +1911,7 @@
           "name": "planner-task-id",
           "key": "plannerTaskId",
           "required": true,
-          "description": "Planner task ID. Returned by `ask-marcel-office 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"
-            }
-          ]
+          "description": "Planner task ID. Returned by `ask-marcel-office list-planner-tasks` or `list-plan-tasks`."
         }
       ],
       "example": "ask-marcel-office get-planner-task --planner-task-id '01tx7Ic7-USXEwt0lvR1cmgAH8gK'",
@@ -1877,17 +1929,7 @@
           "name": "planner-task-id",
           "key": "plannerTaskId",
           "required": true,
-          "description": "Planner task ID. Returned by `ask-marcel-office 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"
-            }
-          ]
+          "description": "Planner task ID. Returned by `ask-marcel-office list-planner-tasks` or `list-plan-tasks`."
         }
       ],
       "example": "ask-marcel-office get-planner-task-details --planner-task-id '01tx7Ic7-USXEwt0lvR1cmgAH8gK'",
@@ -1905,36 +1947,18 @@
           "name": "schedules",
           "key": "schedules",
           "required": true,
-          "aliases": [
-            {
-              "name": "emails",
-              "key": "emails"
-            }
-          ],
           "description": "Comma-separated SMTP addresses of the users and/or room resources to check (e.g. `alice@contoso.com,bob@contoso.com,room-4a@contoso.com`). Resolve names to addresses first via `list-relevant-people` or `microsoft-search-query`."
         },
         {
           "name": "start-date-time",
           "key": "startDateTime",
           "required": true,
-          "aliases": [
-            {
-              "name": "start",
-              "key": "start"
-            }
-          ],
           "description": "Window lower bound (interpreted as UTC). 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,
-          "aliases": [
-            {
-              "name": "end",
-              "key": "end"
-            }
-          ],
           "description": "Window upper bound (interpreted as UTC). Graph caps the span at 62 days. 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)."
         },
         {
@@ -2041,12 +2065,6 @@
           "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-office search-sharepoint-sites-by-name`, or the literal `root` to refer to the tenant root site."
         },
         {
@@ -2191,13 +2209,7 @@
           "name": "list-item-id",
           "key": "listItemId",
           "required": true,
-          "description": "listItem ID (typically a small integer). Returned by `ask-marcel-office list-sharepoint-site-list-items`.",
-          "aliases": [
-            {
-              "name": "item-id",
-              "key": "itemId"
-            }
-          ]
+          "description": "listItem ID (typically a small integer). Returned by `ask-marcel-office list-sharepoint-site-list-items`."
         },
         {
           "name": "select",
@@ -2233,13 +2245,7 @@
           "name": "onenote-page-id",
           "key": "onenotePageId",
           "required": true,
-          "description": "OneNote page ID inside the site.",
-          "aliases": [
-            {
-              "name": "page-id",
-              "key": "pageId"
-            }
-          ]
+          "description": "OneNote page ID inside the site."
         }
       ],
       "example": "ask-marcel-office get-sharepoint-site-onenote-page-content --site-id 'contoso.sharepoint.com,...' --onenote-page-id 'p1'",
@@ -2258,12 +2264,6 @@
           "name": "site-id",
           "key": "siteId",
           "required": true,
-          "aliases": [
-            {
-              "name": "id",
-              "key": "id"
-            }
-          ],
           "description": "SharePoint site ID."
         }
       ],
@@ -2318,12 +2318,6 @@
           "name": "team-id",
           "key": "teamId",
           "required": true,
-          "aliases": [
-            {
-              "name": "id",
-              "key": "id"
-            }
-          ],
           "description": "Microsoft Teams team ID. Returned by `ask-marcel-office list-joined-teams`."
         },
         {
@@ -2390,12 +2384,6 @@
           "name": "team-id",
           "key": "teamId",
           "required": true,
-          "aliases": [
-            {
-              "name": "id",
-              "key": "id"
-            }
-          ],
           "description": "Microsoft Teams team ID. Returned by `list-joined-teams`."
         },
         {
@@ -2437,7 +2425,7 @@
       ],
       "example": "ask-marcel-office 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,
+      "needsSubstrateToken": "chatsvcagg",
       "stability": "experimental"
     },
     {
@@ -2452,29 +2440,13 @@
           "name": "todo-task-list-id",
           "key": "todoTaskListId",
           "required": true,
-          "description": "To Do task list ID. Returned by `ask-marcel-office list-todo-task-lists`.",
-          "aliases": [
-            {
-              "name": "task-list-id",
-              "key": "taskListId"
-            },
-            {
-              "name": "todo-list-id",
-              "key": "todoListId"
-            }
-          ]
+          "description": "To Do task list ID. Returned by `ask-marcel-office list-todo-task-lists`."
         },
         {
           "name": "todo-task-id",
           "key": "todoTaskId",
           "required": true,
-          "description": "To Do task ID. Returned by `ask-marcel-office list-todo-tasks`. Accepts `--task-id` as a shorter alias (within this command's flag set the To Do context is unambiguous).",
-          "aliases": [
-            {
-              "name": "task-id",
-              "key": "taskId"
-            }
-          ]
+          "description": "To Do task ID. Returned by `ask-marcel-office list-todo-tasks`."
         },
         {
           "name": "select",
@@ -2492,6 +2464,37 @@
       "example": "ask-marcel-office get-todo-task --todo-task-list-id 'AAMkAGI...' --todo-task-id 'AAMkABC...'",
       "responseShape": "single Microsoft Graph `todoTask` resource (slimmed by `--select` when supplied)"
     },
+    {
+      "name": "get-user",
+      "summary": "Look up a directory user. Pass an Azure AD id, UPN, or email as --user-id and get that user's FULL profile (displayName, mail, jobTitle, department, officeLocation, phones) via GET /users/{id} on the elevated M365 token — preflight it with `ask-marcel-office scopes-check` (no Graph call) and run `ask-marcel-office login` first if it is cold. An email resolves even when it is the user's `mail` rather than their sign-in UPN: guest / B2B users carry a `#EXT#` UPN whose local part is NOT their email address, so when the direct lookup 404s the command falls back to `GET /users?$filter=mail eq '<email>'` and returns the single match. Only THIS tenant's directory is queried: a person's home-tenant object id (e.g. a cross-tenant Teams `8:orgid:<home-id>` participant, whose id lives in their own tenant) and any email that is not their `mail`/UPN here are unresolvable by design — reach an external person via their LOCAL guest projection (by name, or by their real `mail`), never by their home id. Pass a NAME instead and it searches your relevant-people graph (GET /me/people) and returns candidate matches (id, displayName, mail, jobTitle, department) so you can pick the right person and re-query. Re-query by the candidate's `id` when it is a directory GUID; an EXTERNAL contact's candidate carries a base64-ish People-API id instead, which nothing can resolve — re-query those by the candidate's `mail` (the CLI rejects an opaque contact id with that remedy rather than returning empty matches). Name search covers colleagues in your people graph, not the whole tenant directory; use `microsoft-search-query` for a broader tenant-wide person search. Without `--select`, the profile ships a default projection of id, displayName, userPrincipalName, mail, jobTitle, department, officeLocation, businessPhones, mobilePhone.",
+      "category": "user",
+      "graphMethod": "GET",
+      "graphPathTemplate": "/users/{user-id}  (id / UPN; an email that misses falls back to /users?$filter=mail eq)  OR /me/people?$search=\"{user-id}\"  (a bare name)",
+      "graphDocsUrl": "https://learn.microsoft.com/en-us/graph/api/user-get",
+      "options": [
+        {
+          "name": "user-id",
+          "key": "userId",
+          "required": true,
+          "description": "Azure AD user ID, UPN, or email (returns the full profile via the elevated token), OR a display name (returns relevant-people candidates on the basic token). Discover ids via `list-relevant-people` or `microsoft-search-query`."
+        },
+        {
+          "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-office get-user --user-id 'alice@contoso.com' --select 'id,displayName,mail,jobTitle,department'",
+      "responseShape": "For an id / UPN / email: a single Microsoft Graph `user` resource projected to the default `$select` (id, displayName, userPrincipalName, mail, jobTitle, department, officeLocation, businessPhones, mobilePhone) unless `--select` overrides it; honours `--expand`. An email is tried against the sign-in UPN first, then falls back to the `mail` attribute (`$filter=mail eq`) so guest/B2B users resolve; an email that matches nobody returns the direct-path 404. For a name: `{ query, matches: [{ id, displayName, mail, jobTitle, department }] }` from the People API (empty `matches` when nobody in your relevant-people graph matches; re-query by a chosen GUID `id`, or by `mail` when the candidate is an external contact with a base64-ish People-API id — passing that id back is rejected with the same remedy). The id path needs the elevated M365 token and fail-fasts with `secondary_token_unavailable` when it is cold — preflight with `ask-marcel-office scopes-check` and run `ask-marcel-office login` to re-capture it.",
+      "needsElevatedToken": true
+    },
     {
       "name": "get-user-manager",
       "summary": "Return a specific user's manager (a single `user` resource). When the user has no manager set in the directory, Graph returns 404 `Request_ResourceNotFound`; this command maps that one specific 404 to `{ ok: true, data: { manager: null, note: '...' } }` (same shape as `get-my-manager`) so an LLM can distinguish 'no manager' from 'unknown user' with a single discriminator across both commands. Use `--select` to slim the response.",
@@ -2504,12 +2507,6 @@
           "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)."
         },
         {
@@ -2619,12 +2616,6 @@
           "name": "event-id",
           "key": "eventId",
           "required": true,
-          "aliases": [
-            {
-              "name": "id",
-              "key": "id"
-            }
-          ],
           "description": "Outlook calendar event ID. Returned by `ask-marcel-office list-calendar-events` or `get-calendar-event`."
         },
         {
@@ -2693,36 +2684,18 @@
           "name": "event-id",
           "key": "eventId",
           "required": true,
-          "aliases": [
-            {
-              "name": "id",
-              "key": "id"
-            }
-          ],
           "description": "Recurring event ID. Returned by `ask-marcel-office list-specific-calendar-events`."
         },
         {
           "name": "start-date-time",
           "key": "startDateTime",
           "required": true,
-          "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,
-          "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)."
         },
         {
@@ -2846,12 +2819,6 @@
           "name": "calendar-group-id",
           "key": "calendarGroupId",
           "required": true,
-          "aliases": [
-            {
-              "name": "id",
-              "key": "id"
-            }
-          ],
           "description": "Calendar group ID. Returned by `list-calendar-groups`."
         },
         {
@@ -2956,24 +2923,12 @@
           "name": "start-date-time",
           "key": "startDateTime",
           "required": true,
-          "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,
-          "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)."
         },
         {
@@ -3028,24 +2983,12 @@
           "name": "start-date-time",
           "key": "startDateTime",
           "required": true,
-          "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,
-          "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)."
         },
         {
@@ -3120,12 +3063,6 @@
           "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-office 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`."
         },
         {
@@ -3201,12 +3138,6 @@
           "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`)."
         },
         {
@@ -3287,6 +3218,12 @@
           "key": "expand",
           "required": false,
           "description": "OData $expand: navigation properties to include inline (e.g. `attachments`). Increases response size; use sparingly."
+        },
+        {
+          "name": "tenant-id",
+          "key": "tenantId",
+          "required": false,
+          "description": "Tenant GUID of a PARTNER tenant you are a guest in, when the file does not live in your own tenant. Get it from `resolve-drive-share-link`, which returns `tenantId` on any sharing URL whose file belongs to another tenant — that is the only place the tenant is knowable, because `--drive-id` and `--item-id` carry no tenant at all. Omit it for files in your own tenant (the normal case). Pass it and the request is signed with a guest token minted for that tenant instead of your home token; without it, a partner-tenant file fails with `invalidAudienceUri` no matter which of your tokens is used."
         }
       ],
       "example": "ask-marcel-office list-drive-item-permissions --drive-id 'b!1234' --item-id '01ABC'",
@@ -3342,6 +3279,12 @@
           "key": "expand",
           "required": false,
           "description": "OData $expand: navigation properties to include inline (e.g. `attachments`). Increases response size; use sparingly."
+        },
+        {
+          "name": "tenant-id",
+          "key": "tenantId",
+          "required": false,
+          "description": "Tenant GUID of a PARTNER tenant you are a guest in, when the file does not live in your own tenant. Get it from `resolve-drive-share-link`, which returns `tenantId` on any sharing URL whose file belongs to another tenant — that is the only place the tenant is knowable, because `--drive-id` and `--item-id` carry no tenant at all. Omit it for files in your own tenant (the normal case). Pass it and the request is signed with a guest token minted for that tenant instead of your home token; without it, a partner-tenant file fails with `invalidAudienceUri` no matter which of your tokens is used."
         }
       ],
       "example": "ask-marcel-office list-drive-item-thumbnails --drive-id 'b!1234' --item-id '01ABC'",
@@ -3397,6 +3340,12 @@
           "key": "expand",
           "required": false,
           "description": "OData $expand: navigation properties to include inline (e.g. `attachments`). Increases response size; use sparingly."
+        },
+        {
+          "name": "tenant-id",
+          "key": "tenantId",
+          "required": false,
+          "description": "Tenant GUID of a PARTNER tenant you are a guest in, when the file does not live in your own tenant. Get it from `resolve-drive-share-link`, which returns `tenantId` on any sharing URL whose file belongs to another tenant — that is the only place the tenant is knowable, because `--drive-id` and `--item-id` carry no tenant at all. Omit it for files in your own tenant (the normal case). Pass it and the request is signed with a guest token minted for that tenant instead of your home token; without it, a partner-tenant file fails with `invalidAudienceUri` no matter which of your tokens is used."
         }
       ],
       "example": "ask-marcel-office list-drive-item-versions --drive-id 'b!1234' --item-id '01ABC'",
@@ -3928,13 +3877,7 @@
           "name": "item-id",
           "key": "itemId",
           "required": true,
-          "description": "driveItem ID of the folder (Graph identifies folders as driveItems too — there is no separate folder type). Use the root folder ID from `ask-marcel-office get-drive-root-item` to list the top of a drive. Accepts `--folder-id` as an alias since the command name implies \"folder\".",
-          "aliases": [
-            {
-              "name": "folder-id",
-              "key": "folderId"
-            }
-          ]
+          "description": "driveItem ID of the folder (Graph identifies folders as driveItems too — there is no separate folder type). Use the root folder ID from `ask-marcel-office get-drive-root-item` to list the top of a drive."
         },
         {
           "name": "top",
@@ -3965,6 +3908,12 @@
           "key": "expand",
           "required": false,
           "description": "OData $expand: navigation properties to include inline (e.g. `attachments`). Increases response size; use sparingly."
+        },
+        {
+          "name": "tenant-id",
+          "key": "tenantId",
+          "required": false,
+          "description": "Tenant GUID of a PARTNER tenant you are a guest in, when the file does not live in your own tenant. Get it from `resolve-drive-share-link`, which returns `tenantId` on any sharing URL whose file belongs to another tenant — that is the only place the tenant is knowable, because `--drive-id` and `--item-id` carry no tenant at all. Omit it for files in your own tenant (the normal case). Pass it and the request is signed with a guest token minted for that tenant instead of your home token; without it, a partner-tenant file fails with `invalidAudienceUri` no matter which of your tokens is used."
         }
       ],
       "example": "ask-marcel-office list-folder-files --drive-id 'b!1234' --item-id '01ROOT'",
@@ -4026,36 +3975,18 @@
           "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,
-          "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,
-          "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)."
         },
         {
@@ -4111,12 +4042,6 @@
           "name": "group-id",
           "key": "groupId",
           "required": true,
-          "aliases": [
-            {
-              "name": "id",
-              "key": "id"
-            }
-          ],
           "description": "Azure AD group object ID for a unified (Microsoft 365) group."
         },
         {
@@ -4172,12 +4097,6 @@
           "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."
         },
         {
@@ -4233,12 +4152,6 @@
           "name": "group-id",
           "key": "groupId",
           "required": true,
-          "aliases": [
-            {
-              "name": "id",
-              "key": "id"
-            }
-          ],
           "description": "Azure AD group object ID. Use `list-groups` to find one."
         },
         {
@@ -4294,12 +4207,6 @@
           "name": "group-id",
           "key": "groupId",
           "required": true,
-          "aliases": [
-            {
-              "name": "id",
-              "key": "id"
-            }
-          ],
           "description": "Azure AD group object ID. Use `list-groups` to find one."
         },
         {
@@ -4355,12 +4262,6 @@
           "name": "group-id",
           "key": "groupId",
           "required": true,
-          "aliases": [
-            {
-              "name": "id",
-              "key": "id"
-            }
-          ],
           "description": "Azure AD group object ID for a unified (Microsoft 365) group."
         },
         {
@@ -4508,21 +4409,7 @@
           "name": "todo-task-list-id",
           "key": "todoTaskListId",
           "required": true,
-          "description": "todoTaskList ID. Returned by `ask-marcel-office 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"
-            },
-            {
-              "name": "todo-list-id",
-              "key": "todoListId"
-            }
-          ]
+          "description": "todoTaskList ID. Returned by `ask-marcel-office 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."
         },
         {
           "name": "top",
@@ -4589,13 +4476,7 @@
           "name": "message-id",
           "key": "messageId",
           "required": true,
-          "aliases": [
-            {
-              "name": "id",
-              "key": "id"
-            }
-          ],
-          "description": "Outlook message ID. Returned by `ask-marcel-office list-mail-messages` or `list-mail-folder-messages`. Accepts `--id` as an alias."
+          "description": "Outlook message ID. Returned by `ask-marcel-office list-mail-messages` or `list-mail-folder-messages`."
         },
         {
           "name": "top",
@@ -4650,12 +4531,6 @@
           "name": "mail-folder-id",
           "key": "mailFolderId",
           "required": true,
-          "aliases": [
-            {
-              "name": "id",
-              "key": "id"
-            }
-          ],
           "description": "mailFolder ID. Returned by `ask-marcel-office list-mail-folders`. Well-known names also work, e.g. `inbox`, `sentitems`, `drafts`."
         },
         {
@@ -4711,13 +4586,7 @@
           "name": "mail-folder-id",
           "key": "mailFolderId",
           "required": true,
-          "aliases": [
-            {
-              "name": "id",
-              "key": "id"
-            }
-          ],
-          "description": "mailFolder ID. Returned by `ask-marcel-office list-mail-folders`. Well-known names also work, e.g. `inbox`, `sentitems`, `drafts`."
+          "description": "mailFolder ID. Returned by `ask-marcel-office list-mail-folders`. Well-known names also work, e.g. `inbox`, `sentitems`, `drafts`. When listing `drafts`, a `conversationId` `$filter` is not a reliable check for whether a draft already exists on a thread: reply and forward drafts can split across several conversationIds, and `$filter` on Drafts is not read-your-writes consistent. Match client-side on subject and recipients instead, or use the `find-mail-drafts` command, which does exactly that."
         },
         {
           "name": "top",
@@ -4762,7 +4631,7 @@
     },
     {
       "name": "list-mail-folder-messages-delta",
-      "summary": "Track incremental changes (added / updated / deleted messages) within a single mail folder using Microsoft Graph delta tokens. The first call returns the current snapshot plus a `@odata.deltaLink`; subsequent calls with that link return only what has changed since.",
+      "summary": "Track incremental changes (added / updated / deleted messages) within a single mail folder using Microsoft Graph delta tokens. The first call returns the current snapshot plus a `@odata.deltaLink`; subsequent calls with that link return only what has changed since. `--top` is translated into the `Prefer: odata.maxpagesize=N` header: as a `$top` query parameter Graph reads a satisfied count as \"sync complete\" and hands back a deltaLink after N items, silently abandoning the rest of the folder. `$skip` and `$orderby` are NOT exposed — Graph ignores the former on this endpoint and rejects the latter unless it merely restates the default `receivedDateTime desc`.",
       "category": "mail",
       "graphMethod": "GET",
       "graphPathTemplate": "/me/mailFolders/{mail-folder-id}/messages/delta()",
@@ -4772,12 +4641,6 @@
           "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`."
         },
         {
@@ -4786,12 +4649,6 @@
           "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",
@@ -4804,12 +4661,6 @@
           "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",
@@ -4818,7 +4669,7 @@
         }
       ],
       "example": "ask-marcel-office list-mail-folder-messages-delta --mail-folder-id 'inbox'",
-      "responseShape": "collection of Microsoft Graph `message` resources under `data.value[]`. Cursor tokens are hoisted to envelope level: top-level `nextLink` while paging, then top-level `deltaLink` on the final page (CLI strips the original `@odata.*` keys from `data`).",
+      "responseShape": "collection of Microsoft Graph `message` resources under `data.value[]`. Cursor tokens are hoisted to envelope level: top-level `nextLink` while paging, then top-level `deltaLink` on the final page (CLI strips the original `@odata.*` keys from `data`). A `deltaLink` on the FIRST page means the folder is fully synced, not that it was truncated.",
       "pagination": true
     },
     {
@@ -4884,7 +4735,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). 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.",
+      "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,conversationId` (`conversationId` groups messages into a thread and can be handed to `list-conversation-messages`) 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",
@@ -5108,12 +4959,6 @@
           "name": "notebook-id",
           "key": "notebookId",
           "required": true,
-          "aliases": [
-            {
-              "name": "id",
-              "key": "id"
-            }
-          ],
           "description": "OneNote notebook ID. Returned by `ask-marcel-office list-onenote-notebooks`."
         },
         {
@@ -5218,17 +5063,7 @@
           "name": "onenote-section-id",
           "key": "onenoteSectionId",
           "required": true,
-          "description": "OneNote section ID. Returned by `ask-marcel-office list-onenote-notebook-sections` or `list-all-onenote-sections`.",
-          "aliases": [
-            {
-              "name": "id",
-              "key": "id"
-            },
-            {
-              "name": "section-id",
-              "key": "sectionId"
-            }
-          ]
+          "description": "OneNote section ID. Returned by `ask-marcel-office list-onenote-notebook-sections` or `list-all-onenote-sections`."
         },
         {
           "name": "top",
@@ -5294,17 +5129,7 @@
           "name": "planner-plan-id",
           "key": "plannerPlanId",
           "required": true,
-          "description": "Planner plan ID. Returned in the `planId` field of any task from `ask-marcel-office list-planner-tasks`.",
-          "aliases": [
-            {
-              "name": "id",
-              "key": "id"
-            },
-            {
-              "name": "plan-id",
-              "key": "planId"
-            }
-          ]
+          "description": "Planner plan ID. Returned in the `planId` field of any task from `ask-marcel-office list-planner-tasks`."
         },
         {
           "name": "select",
@@ -5329,17 +5154,7 @@
           "name": "planner-plan-id",
           "key": "plannerPlanId",
           "required": true,
-          "description": "Planner plan ID. Returned in the `planId` field of any task from `ask-marcel-office list-planner-tasks`.",
-          "aliases": [
-            {
-              "name": "id",
-              "key": "id"
-            },
-            {
-              "name": "plan-id",
-              "key": "planId"
-            }
-          ]
+          "description": "Planner plan ID. Returned in the `planId` field of any task from `ask-marcel-office list-planner-tasks`."
         }
       ],
       "example": "ask-marcel-office list-plan-tasks --planner-plan-id 'xqQg5FS2LkCp935s-FIFm5gAB6'",
@@ -5714,12 +5529,6 @@
           "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)."
         },
         {
@@ -5775,36 +5584,18 @@
           "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,
-          "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,
-          "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)."
         },
         {
@@ -5970,12 +5761,6 @@
           "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)."
         },
         {
@@ -6090,13 +5875,7 @@
           "name": "list-item-id",
           "key": "listItemId",
           "required": true,
-          "description": "List item ID inside the list. Returned by `list-sharepoint-site-list-items`.",
-          "aliases": [
-            {
-              "name": "item-id",
-              "key": "itemId"
-            }
-          ]
+          "description": "List item ID inside the list. Returned by `list-sharepoint-site-list-items`."
         },
         {
           "name": "top",
@@ -6145,12 +5924,6 @@
           "name": "site-id",
           "key": "siteId",
           "required": true,
-          "aliases": [
-            {
-              "name": "id",
-              "key": "id"
-            }
-          ],
           "description": "SharePoint site ID. Returned by `ask-marcel-office search-sharepoint-sites-by-name`."
         },
         {
@@ -6258,12 +6031,6 @@
           "name": "site-id",
           "key": "siteId",
           "required": true,
-          "aliases": [
-            {
-              "name": "id",
-              "key": "id"
-            }
-          ],
           "description": "SharePoint site ID. Returned by `ask-marcel-office search-sharepoint-sites-by-name`."
         },
         {
@@ -6374,12 +6141,6 @@
           "name": "site-id",
           "key": "siteId",
           "required": true,
-          "aliases": [
-            {
-              "name": "id",
-              "key": "id"
-            }
-          ],
           "description": "SharePoint site ID."
         },
         {
@@ -6441,13 +6202,7 @@
           "name": "onenote-section-id",
           "key": "onenoteSectionId",
           "required": true,
-          "description": "OneNote section ID inside the site.",
-          "aliases": [
-            {
-              "name": "section-id",
-              "key": "sectionId"
-            }
-          ]
+          "description": "OneNote section ID inside the site."
         },
         {
           "name": "top",
@@ -6502,12 +6257,6 @@
           "name": "site-id",
           "key": "siteId",
           "required": true,
-          "aliases": [
-            {
-              "name": "id",
-              "key": "id"
-            }
-          ],
           "description": "SharePoint site ID."
         },
         {
@@ -6557,12 +6306,6 @@
           "name": "site-id",
           "key": "siteId",
           "required": true,
-          "aliases": [
-            {
-              "name": "id",
-              "key": "id"
-            }
-          ],
           "description": "SharePoint site ID. Returned by `search-sharepoint-sites-by-name`."
         },
         {
@@ -6593,12 +6336,6 @@
           "name": "site-id",
           "key": "siteId",
           "required": true,
-          "aliases": [
-            {
-              "name": "id",
-              "key": "id"
-            }
-          ],
           "description": "SharePoint site ID."
         },
         {
@@ -6648,12 +6385,6 @@
           "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-office list-calendars` to discover non-default calendar IDs."
         },
         {
@@ -6709,36 +6440,18 @@
           "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-office list-calendars`."
         },
         {
           "name": "start-date-time",
           "key": "startDateTime",
           "required": true,
-          "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,
-          "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)."
         },
         {
@@ -6793,12 +6506,6 @@
           "name": "team-id",
           "key": "teamId",
           "required": true,
-          "aliases": [
-            {
-              "name": "id",
-              "key": "id"
-            }
-          ],
           "description": "Microsoft Teams team ID. Returned by `ask-marcel-office list-joined-teams`."
         },
         {
@@ -6829,12 +6536,6 @@
           "name": "team-id",
           "key": "teamId",
           "required": true,
-          "aliases": [
-            {
-              "name": "id",
-              "key": "id"
-            }
-          ],
           "description": "Microsoft Teams team ID."
         }
       ],
@@ -6854,12 +6555,6 @@
           "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`."
         },
         {
@@ -6895,7 +6590,7 @@
       ],
       "example": "ask-marcel-office 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,
+      "needsSubstrateToken": "ic3",
       "stability": "experimental"
     },
     {
@@ -6910,18 +6605,12 @@
           "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-office 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,
+      "needsSubstrateToken": "chatsvcagg",
       "stability": "experimental"
     },
     {
@@ -6947,7 +6636,7 @@
       ],
       "example": "ask-marcel-office 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,
+      "needsSubstrateToken": "chatsvcagg",
       "stability": "experimental"
     },
     {
@@ -6962,29 +6651,13 @@
           "name": "todo-task-list-id",
           "key": "todoTaskListId",
           "required": true,
-          "description": "To Do task list ID. Returned by `ask-marcel-office list-todo-task-lists`.",
-          "aliases": [
-            {
-              "name": "task-list-id",
-              "key": "taskListId"
-            },
-            {
-              "name": "todo-list-id",
-              "key": "todoListId"
-            }
-          ]
+          "description": "To Do task list ID. Returned by `ask-marcel-office list-todo-task-lists`."
         },
         {
           "name": "todo-task-id",
           "key": "todoTaskId",
           "required": true,
-          "description": "To Do task ID. Returned by `ask-marcel-office list-todo-tasks`. Accepts `--task-id` as a shorter alias (within this command's flag set the To Do context is unambiguous).",
-          "aliases": [
-            {
-              "name": "task-id",
-              "key": "taskId"
-            }
-          ]
+          "description": "To Do task ID. Returned by `ask-marcel-office list-todo-tasks`."
         },
         {
           "name": "top",
@@ -7076,21 +6749,7 @@
           "name": "todo-task-list-id",
           "key": "todoTaskListId",
           "required": true,
-          "description": "To Do task list ID. Returned by `ask-marcel-office list-todo-task-lists`.",
-          "aliases": [
-            {
-              "name": "id",
-              "key": "id"
-            },
-            {
-              "name": "task-list-id",
-              "key": "taskListId"
-            },
-            {
-              "name": "todo-list-id",
-              "key": "todoListId"
-            }
-          ]
+          "description": "To Do task list ID. Returned by `ask-marcel-office list-todo-task-lists`."
         },
         {
           "name": "top",
@@ -7145,21 +6804,7 @@
           "name": "todo-task-list-id",
           "key": "todoTaskListId",
           "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"
-            },
-            {
-              "name": "todo-list-id",
-              "key": "todoListId"
-            }
-          ]
+          "description": "Microsoft To Do task list ID. Returned by `list-todo-task-lists`."
         }
       ],
       "example": "ask-marcel-office list-todo-tasks-delta --todo-task-list-id 'AAMkAD...'",
@@ -7227,12 +6872,6 @@
           "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)."
         },
         {
@@ -7308,7 +6947,7 @@
     },
     {
       "name": "next-page",
-      "summary": "Fetch the next page of a paginated Graph response. Pass the cursor the previous command emitted — in text mode that is the `next: <url>` value in the `---` footer; in JSON mode it is the top-level `nextLink` field. Never reach into `data[\"@odata.nextLink\"]`; the CLI strips that and surfaces it as a first-class envelope/footer field. Automatically signs `/me/chats` and `/chats/...` cursors with the M365ChatClient elevated token to match the chat-metadata commands.",
+      "summary": "Fetch the next page of a paginated Graph response. Pass the cursor the previous command emitted — in text mode the `---` footer prints the whole ready-to-run command (`next: ask-marcel-office next-page --url '<url>'`), so copy the line as-is (the URL is single-quoted because it contains `$`); in JSON mode use the top-level `nextLink` field. Never reach into `data[\"@odata.nextLink\"]`; the CLI strips that and surfaces it as a first-class envelope/footer field. Automatically signs `/me/chats` and `/chats/...` cursors with the M365ChatClient elevated token to match the chat-metadata commands.",
       "category": "meta",
       "graphMethod": "GET",
       "graphPathTemplate": "{url}",
@@ -7329,7 +6968,7 @@
     },
     {
       "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.",
+      "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-to-markdown`, 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 (quoted chain stripped unless `--keep-quoted true`), 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}",
@@ -7359,10 +6998,23 @@
               "false"
             ]
           }
+        },
+        {
+          "name": "keep-quoted",
+          "key": "keepQuoted",
+          "required": false,
+          "description": "Applies to Outlook `.msg` input only. The quoted reply chain / forwarded-message block is stripped by default (it duplicates history and inflates the context budget) and replaced with a single visible marker naming this flag, so nothing is removed silently. Pass `--keep-quoted true` to render the full body. The recognized markers are the same set `convert-mail-to-markdown` uses — see `ask-marcel-office docs convert-mail-to-markdown`.",
+          "argumentHint": {
+            "kind": "magicValue",
+            "values": [
+              "true",
+              "false"
+            ]
+          }
         }
       ],
       "example": "ask-marcel-office 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.",
+      "responseShape": "Polymorphic by attachment content-type. A zip → `{ count, files: [{ path, contentType, size, text } | { path, note }], truncated? }` (the convert-mail-attachment-zip-to-markdown 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
     },
     {
@@ -7385,10 +7037,10 @@
     },
     {
       "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`.",
+      "summary": "Resolve a OneDrive / SharePoint sharing URL (a \"Copy link\" address someone sent you) to the file it points at, returning `driveId` + `itemId` ready to feed `get-drive-item`, `download-drive-item-content`, `convert-drive-item-*`, `extract-drive-item-images`, and the rest of the `*-drive-item` family. It encodes the URL to the Graph `/shares/{token}` share token (`u!<base64url>` per [shares-get](https://learn.microsoft.com/en-us/graph/api/shares-get)) and fetches `/shares/{token}/driveItem` in ONE call (basic token, `Files.Read.All`) — a raw sharing URL carries no ids, so this is the entry point into the drive-item family from a shared link. Accepts any `*.sharepoint.com` URL (tenant + `*-my.sharepoint.com` personal OneDrive) and Microsoft's short-link host `1drv.ms`. **Cross-tenant links work too**: when the URL belongs to a tenant you are only a GUEST in, your home token cannot read its SharePoint (Graph answers `invalidAudienceUri` — it cannot mint a SharePoint token for a foreign tenant), so this command identifies the owning tenant from the URL host and retries with a guest token automatically, then returns that tenant as `tenantId` — see `responseShape` for how to pass it on to the follow-up calls.",
       "category": "drive",
       "graphMethod": "GET",
-      "graphPathTemplate": "{url}",
+      "graphPathTemplate": "/shares/(u!<base64url> of {url})/driveItem",
       "graphDocsUrl": "https://learn.microsoft.com/en-us/graph/api/shares-get",
       "options": [
         {
@@ -7399,7 +7051,7 @@
         }
       ],
       "example": "ask-marcel-office 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-office 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."
+      "responseShape": "`{ driveId, itemId, name, webUrl, size, lastModifiedDateTime, shareToken, tenantId? }`. `driveId` (from the item's `parentReference`) + `itemId` feed every `*-drive-item` command directly — no second call. `shareToken` is the `u!<base64url>` form, kept for reuse against other `/shares/{token}/...` endpoints. **`tenantId` is present ONLY when the link belongs to a partner tenant you are a guest in** — when it is there, pass it as `--tenant-id` to every follow-up `*-drive-item` call (`download-drive-item-content`, `convert-drive-item-*`, `extract-drive-item-images`, `get-drive-item`, …), because `driveId`/`itemId` carry no tenant and those commands would otherwise fail with `invalidAudienceUri`. When `tenantId` is absent the file is in your own tenant and no flag is needed. Any other field is absent/`undefined` when the resolved driveItem omits it (e.g. `size` on a folder)."
     },
     {
       "name": "resolve-mail-link",
@@ -7439,14 +7091,14 @@
     },
     {
       "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). The `expiresInSeconds` field 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. The `elevated` block reports whether the *separate* M365ChatClient-elevated token (needed by the historical-version download / convert commands) is cached and still usable — so a fresh process can pre-flight `deep-scan`-style workloads instead of discovering a 403 mid-run; `available:false` when it is absent, expired, or within the same 5-minute buffer the download path applies. The `chatsvcagg` and `ic3` blocks report the two Teams-chat substrate tokens (used by `list-teams-chat*` / `find-chats-with-user`) the same way; both self-heal from the shared refresh token, so they are informational rather than a preflight gate.",
+      "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 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. The `elevated` block reports whether the *separate* M365ChatClient-elevated token (needed by the historical-version download / convert commands) is cached and still usable — so a fresh process can pre-flight `deep-scan`-style workloads instead of discovering a 403 mid-run; `available:false` when it is absent, expired, or within the same 5-minute buffer the download path applies. The `chatsvcagg` and `ic3` blocks report the two Teams-chat substrate tokens (used by `list-teams-chat*` / `find-chats-with-user`) the same way; both self-heal from the shared refresh token, so they are informational rather than a preflight gate. Every tier block also lists that token's OWN granted scopes (decoded from its `scp` claim, distinct per token) and its `refresh` route (`automatic` = self-heals from the shared refresh token; `interactive` = the elevated tier, which carries no refresh token of its own and is re-captured by a browser login); the `hint` field says how to refresh them.",
       "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-office scopes-check",
-      "responseShape": "`{ scopes: string[], audience: string, expiresAt: string (ISO 8601), expiresInSeconds: number, elevated: { available: boolean, expiresInSeconds?: number }, chatsvcagg: { available: boolean, expiresInSeconds?: number }, ic3: { available: boolean, 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`). `elevated.available` is `true` only when the cached M365ChatClient-elevated token (used by the historical-version commands) is present and beyond the 5-minute buffer; `elevated.expiresInSeconds` is its raw remaining seconds and is omitted (the key is absent) when no elevated token is cached. `chatsvcagg` and `ic3` are the two Teams-chat substrate tokens, same shape as `elevated`; both self-heal from the shared refresh token, so they are informational rather than a preflight gate."
+      "responseShape": "`{ scopes: string[], audience: string, expiresAt: string (ISO 8601), expiresInSeconds: number, elevated: TokenTier, chatsvcagg: TokenTier, ic3: TokenTier, hint: string }` where `TokenTier = { available: boolean, expiresInSeconds?: number, scopes: string[], refresh: \"automatic\" | \"interactive\", reason?: string }`. Top-level `scopes`/`audience`/`expiresAt`/`expiresInSeconds` describe the basic Teams token (back-compat). Each tier block also carries that token's OWN `scopes` (decoded from its `scp` claim: elevated ~20 Graph scopes, chatsvcagg `user_impersonation`, ic3 `Teams.AccessAsUser.All`) and its `refresh` route (`automatic` = self-heals from the shared refresh token; `interactive` = the elevated token, re-captured only by a browser login). `available` is `true` only when the token is present and beyond the 5-minute buffer; `expiresInSeconds` is the raw remaining seconds (negative when expired) and is omitted when the token is absent. `reason` is present ONLY when `available` is `false` — a plain-language note on why the tier is missing and how to restore it (so an empty `scopes: []` on an absent token is not mistaken for \"no scopes\"); it is omitted when the token is available. `hint` names `login --force` as the single refresh action."
     },
     {
       "name": "search-all-accessible-sites",
@@ -7473,9 +7125,28 @@
       "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-all-files",
+      "summary": "Search EVERY file the signed-in user can access — their personal OneDrive, files shared with them, and every SharePoint and Teams (channel) document library they can open — for a free-text query. Unlike `search-my-documents` (personal OneDrive only) or `search-onedrive-files` (one drive by id), this reaches across all accessible drives via the security-trimmed Microsoft Search index; unlike `microsoft-search-query` it returns FILES ONLY (`entityTypes: [\"driveItem\"]`), not mail/calendar/people/sites. It deep-pages `POST /search/query` with `from`/`size` (200 per page) following the index's `moreResultsAvailable` flag until exhausted, or the ceiling of 25×200 = 5000 files is reached (`truncated: true` — narrow with `--query` to see the rest). Hits are deduped by `hitId`. Each returned `driveItem` carries `id` + `parentReference.driveId`, the pair `download-drive-item-content` / `download-drive-item-as-markdown` need to open it.",
+      "category": "drive",
+      "graphMethod": "POST",
+      "graphPathTemplate": "/search/query",
+      "graphDocsUrl": "https://learn.microsoft.com/en-us/graph/api/search-query",
+      "options": [
+        {
+          "name": "query",
+          "key": "query",
+          "required": true,
+          "description": "KQL / free-text search query. Matches filename, content, and metadata across every drive the user can access. Add `filetype:` to narrow (e.g. `q1 budget filetype:xlsx`), or field operators like `filename:`. Free text works everywhere."
+        }
+      ],
+      "example": "ask-marcel-office search-all-files --query 'q1 budget filetype:xlsx'",
+      "responseShape": "`{ value: [<Microsoft Graph driveItem resource: { id, name, webUrl, parentReference: { driveId }, size, … }>], count, truncated?: true }`. `value[]` is deduped by `hitId` across pages; `count` is the number of distinct files returned. `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.",
+      "bodyTemplate": "{ requests: [{ entityTypes: ['driveItem'], query: { queryString: '{query}' }, from: <page*200>, size: 200 }] } — re-issued per page, advancing `from` by 200 until `moreResultsAvailable` is false or the 25-page ceiling is hit"
+    },
     {
       "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. 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.",
+      "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,conversationId` (same as `list-mail-messages`; `conversationId` is included so you can group hits into a thread or feed one to `list-conversation-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. **Exact-phrase search works**: `--query '\"budget allocation\"'` and embedded field phrases like `--query 'subject:\"Contoso A2 & B7 timeline\"'` are supported — the CLI escapes your double quotes into KQL phrase quotes, wraps the whole expression in the `\"…\"` Graph requires, and percent-encodes the value so `&`, `#`, and `+` are wire-safe. Pass raw KQL otherwise, e.g. `--query 'subject:invoice from:alice'`.",
       "category": "mail",
       "graphMethod": "GET",
       "graphPathTemplate": "/me/messages?$search=\"{query}\"",
@@ -7589,12 +7260,6 @@
           "name": "drive-id",
           "key": "driveId",
           "required": true,
-          "aliases": [
-            {
-              "name": "id",
-              "key": "id"
-            }
-          ],
           "description": "Microsoft Graph drive ID to search inside. Use `ask-marcel-office list-drives` for the personal OneDrive, or `ask-marcel-office list-sharepoint-site-drives --site-id <id>` for a SharePoint document library."
         },
         {
@@ -7643,20 +7308,14 @@
       "summary": "Find OneNote pages whose title contains a substring (case-sensitive — page content is NOT searched). Microsoft removed full-text OneNote `?search=` from v1.0 Graph; only $filter against `title` remains, which is what this command runs. Accepts the OData passthrough flags top/skip/select/orderby/expand. The filter passthrough is intentionally omitted — the path already pins a `$filter` for the title-contains predicate, and Graph rejects two `$filter` query params.",
       "category": "notes",
       "graphMethod": "GET",
-      "graphPathTemplate": "/me/onenote/pages?$filter=contains(title,'{title-substring}')",
+      "graphPathTemplate": "/me/onenote/pages?$filter=contains(title,'{query}')",
       "graphDocsUrl": "https://learn.microsoft.com/en-us/graph/api/onenote-list-pages",
       "options": [
         {
-          "name": "title-substring",
-          "key": "titleSubstring",
+          "name": "query",
+          "key": "query",
           "required": true,
-          "description": "Substring to look for inside OneNote page titles (case-sensitive, exact substring). This is title-only — full-text body search is not available on OneNote pages in v1.0 Graph. Use `list-onenote-section-pages` if you already know the section.",
-          "aliases": [
-            {
-              "name": "query",
-              "key": "query"
-            }
-          ]
+          "description": "Substring to look for inside OneNote page TITLES (case-sensitive, exact substring — not a full-text query, despite the flag name shared with the other search commands). Full-text body search is not available on OneNote pages in v1.0 Graph. Use `list-onenote-section-pages` if you already know the section."
         },
         {
           "name": "top",
@@ -7689,7 +7348,7 @@
           "description": "OData $expand: navigation properties to include inline (e.g. `attachments`). Increases response size; use sparingly."
         }
       ],
-      "example": "ask-marcel-office search-onenote-pages --title-substring 'meeting notes' --top 25",
+      "example": "ask-marcel-office search-onenote-pages --query 'meeting notes' --top 25",
       "responseShape": "collection of Microsoft Graph `onenotePage` resources under `value[]` whose title contains the substring",
       "pagination": true
     },
@@ -7750,23 +7409,17 @@
     },
     {
       "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.",
+      "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. On a THREADED draft (one made by create-reply-draft / create-forward-draft), revise your text with --comment, which rewrites only what sits above the quoted history and leaves the quote byte-identical; --body-content replaces the whole body and would drop the thread, so it is REFUSED on a draft that still carries a quote unless you pass --replace-quoted-history true. Passing an EMPTY string to a recipient flag clears that list, which is how you drop recipients a reply-all or forward inherited; omitting the flag leaves the list alone. Returns a slim confirmation (id, subject, recipients, importance, bodyPreview, …) - NOT the full body, which you just wrote; read it back with get-mail-message if you need the whole draft before sending.",
       "category": "mail",
       "graphMethod": "PATCH",
-      "graphPathTemplate": "/me/messages/{message-id}",
+      "graphPathTemplate": "/me/messages/{message-id} (+ a GET of body,isDraft first when {comment} is used, or when {body-content} is used without {replace-quoted-history})",
       "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.",
+          "description": "Draft message ID to update. Source from create-mail-draft response or list-mail-folder-messages --mail-folder-id drafts.",
           "argumentHint": {
             "kind": "idOrName"
           }
@@ -7781,13 +7434,32 @@
           "name": "body-content",
           "key": "bodyContent",
           "required": false,
-          "description": "New email body content. Replaces the entire body. Pass --body-content-type HTML for rich text."
+          "description": "New email body content. Replaces the ENTIRE body, quoted history included. On a threaded reply or forward draft that is almost never what you want, so the command reads the draft first and REFUSES when it still carries a quote - use --comment to revise only your own text and keep the quote, or pass --replace-quoted-history true to drop it deliberately. Note the sibling commands: create-reply-draft / create-forward-draft name their above-the-quote text --comment; --body-content exists only here. Pass --body-content-type HTML for rich text. Mutually exclusive with --comment."
+        },
+        {
+          "name": "comment",
+          "key": "comment",
+          "required": false,
+          "description": "Rewrite ONLY the reply text above the quoted history on a threaded draft, keeping the quote and its styles byte-identical. This is the flag for revising a draft made by create-reply-draft or create-forward-draft; repeated edits replace your text rather than stacking. Refused when the draft has no quoted history (use --body-content), when it is not a draft, and when HTML markup you pass carries a quote boundary marker of its own. Mutually exclusive with --body-content."
+        },
+        {
+          "name": "replace-quoted-history",
+          "key": "replaceQuotedHistory",
+          "required": false,
+          "description": "Allow --body-content to drop the quoted history on a threaded draft. Without it, --body-content is REFUSED when the draft still carries a quote, because replacing the whole body there silently loses the thread; the refusal points at --comment, which revises only your own text. Pass `true` for the deliberate case: strip the quote but keep the draft threaded on its conversation. Ignored in comment mode, which never touches the quote.",
+          "argumentHint": {
+            "kind": "magicValue",
+            "values": [
+              "true",
+              "false"
+            ]
+          }
         },
         {
           "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.",
+          "description": "Format of --body-content, or of --comment in comment mode: Text (default) or HTML. With --comment on an HTML draft, Text is escaped into the draft (markup shows as characters) and HTML is spliced in as markup; HTML is refused on a plain-text draft. The draft keeps its own body format either way - this flag describes what you are passing, not what the draft becomes.",
           "argumentHint": {
             "kind": "magicValue",
             "values": [
@@ -7800,19 +7472,19 @@
           "name": "to-recipients",
           "key": "toRecipients",
           "required": false,
-          "description": "Comma-separated list of recipient email addresses. Replaces the entire toRecipients list."
+          "description": "Comma-separated list of recipient email addresses. Replaces the entire toRecipients list. Pass an empty string to CLEAR the list (the only way to drop recipients a reply or forward inherited)."
         },
         {
           "name": "cc-recipients",
           "key": "ccRecipients",
           "required": false,
-          "description": "Comma-separated list of CC recipient email addresses. Replaces the entire ccRecipients list."
+          "description": "Comma-separated list of CC recipient email addresses. Replaces the entire ccRecipients list. Pass an empty string to CLEAR the list (the only way to drop recipients a reply or forward inherited)."
         },
         {
           "name": "bcc-recipients",
           "key": "bccRecipients",
           "required": false,
-          "description": "Comma-separated list of BCC recipient email addresses. Replaces the entire bccRecipients list."
+          "description": "Comma-separated list of BCC recipient email addresses. Replaces the entire bccRecipients list. Pass an empty string to CLEAR the list (the only way to drop recipients a reply or forward inherited)."
         },
         {
           "name": "importance",
@@ -7830,8 +7502,8 @@
         }
       ],
       "example": "ask-marcel-office 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",
+      "responseShape": "A confirmation of the write, NOT the whole message: `{ id, subject, toRecipients, ccRecipients, bccRecipients, importance, bodyPreview, isDraft, webLink, conversationId }` (only the fields Graph returned; `{ ok: true }` when Graph answers 204). The `body` is deliberately omitted — you just wrote it, and echoing a long thread's quoted history back cost ~174 KB of context per call. Read the full body with `get-mail-message --id <the returned id>` when you actually need it; `bodyPreview` is Graph's ~255-char summary, enough to confirm WHICH draft answered. The `id` is the draft — refine it with `update-mail-draft`, or open Outlook Drafts to review and send. Dedup caveat: a `conversationId` `$filter` on the Drafts folder is not a reliable 'does a draft already exist on this thread' check. Reply and forward drafts do not always inherit the inbound message's `conversationId` (one thread can split across several), and Graph `$filter` on Drafts is not read-your-writes consistent, so a just-created draft can be missed. To find existing drafts, use the `find-mail-drafts` command, which scans recent drafts and matches client-side on subject and recipients; to revise a draft this session created, reuse the returned `id`.",
+      "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. With '{comment}': body.content is the draft's own body with the text above the quote replaced, and body.contentType is the draft's own, unchanged. A '{body-content}' aimed at a draft that still carries a quote costs one GET of body,isDraft and is refused unless '{replace-quoted-history}' is true",
       "mutates": true
     }
   ]