ask-marcel-office-cli 2.2.0 → 2.4.0

package/dist/commands.json

@@ -1,7 +1,7 @@
 {
   "package": "ask-marcel-office-cli",
-  "version": "2.2.0",
-  "generatedAt": "2026-07-19T12:40:32.946Z",
+  "version": "2.4.0",
+  "generatedAt": "2026-09-02T16:06:32.040Z",
   "commands": [
     {
       "name": "convert-calendar-event-attachment-to-markdown",
@@ -83,9 +83,6 @@
       "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",
-      "commandAliases": [
-        "convert-drive-item-zip"
-      ],
       "graphMethod": "GET",
       "graphPathTemplate": "/drives/{drive-id}/items/{item-id}/content",
       "graphDocsUrl": "https://learn.microsoft.com/en-us/graph/api/driveitem-get-content",
@@ -142,9 +139,6 @@
       "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",
-      "commandAliases": [
-        "convert-local-file"
-      ],
       "graphMethod": "GET",
       "graphPathTemplate": "(local) reads {path} from the local filesystem; not a Graph endpoint",
       "graphDocsUrl": "https://learn.microsoft.com/en-us/graph/",
@@ -298,9 +292,6 @@
       "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",
-      "commandAliases": [
-        "convert-mail-attachment-zip"
-      ],
       "graphMethod": "GET",
       "graphPathTemplate": "/me/messages/{message-id}/attachments/{attachment-id}",
       "graphDocsUrl": "https://learn.microsoft.com/en-us/graph/api/attachment-get",
@@ -359,13 +350,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`."
         },
         {
           "name": "inline-images",
@@ -377,7 +362,7 @@
           "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`, 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.",
+          "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, in either the hex or the `border-color:rgb(…)` longhand new Outlook writes), the new-Outlook `mail-editor-reference-message-container` but only when a header block opens inside it (the same id also wraps a body that quotes nothing, so the id alone never cuts), 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. When a chain is stripped the `note` reports what share of the body’s readable text went with it (`removed 62% of the body text`), so a caller can tell a normal strip from one that swallowed the message without refetching to compare.",
           "argumentHint": {
             "kind": "magicValue",
             "values": [
@@ -388,7 +373,7 @@
         }
       ],
       "example": "ask-marcel-office convert-mail-to-markdown --message-id 'AAMkAD...'",
-      "responseShape": "`{ contentType: \"text/markdown\", size, text, note? }` — headers + turndown-rendered body + (when present) a file-attachments list. The optional `note` carries a partial-success hint when the attachments-metadata fetch fails after the body succeeded, and/or a flag that a quoted reply chain was stripped (use `--keep-quoted true` to include it).",
+      "responseShape": "`{ contentType: \"text/markdown\", size, text, note? }` — headers + turndown-rendered body + (when present) a file-attachments list. The optional `note` carries a partial-success hint when the attachments-metadata fetch fails after the body succeeded, and/or a flag that a quoted reply chain was stripped, carrying the share of the body’s readable text that went with it (`quoted reply chain stripped (removed 62% of the body text) — pass --keep-quoted true to include it`). A share near 100% on a message that should have had a real reply above the quote is the signature of a mis-detected boundary: refetch with `--keep-quoted true` to confirm.",
       "producesBytes": true
     },
     {
@@ -403,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"
           }
@@ -427,10 +406,10 @@
           "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. Plain text by default; pass --body-content-type HTML to send it as markup."
+          "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",
@@ -442,7 +421,7 @@
           "name": "body-content-type",
           "key": "bodyContentType",
           "required": false,
-          "description": "Format of --body-content: 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.",
+          "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": [
@@ -452,9 +431,9 @@
           }
         }
       ],
-      "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.\"",
+      "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: '{body-content}', 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: <'{body-content}' spliced at the top of the body, above Graph's <hr> separator and the quote> }, ccRecipients?: '{cc-recipients}', subject?: '{subject}' }",
+      "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
     },
     {
@@ -549,28 +528,22 @@
           "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. Plain text by default; pass --body-content-type HTML to send it as markup."
+          "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 --body-content: 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.",
+          "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": [
@@ -599,9 +572,9 @@
           }
         }
       ],
-      "example": "ask-marcel-office create-reply-draft --reply-to-message-id \"AAMkAD...\" --body-content \"Confirmed for Contoso, aligned with the group choice.\"",
+      "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: '{body-content}' } then optional PATCH { subject?: '{subject}' }. HTML ({body-content-type}): POST { comment: '' } then ONE PATCH { body: { contentType: 'HTML', content: <'{body-content}' spliced at the top of the body, above Graph's <hr> separator and the quote> }, subject?: '{subject}' }",
+      "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
     },
     {
@@ -634,7 +607,7 @@
           "name": "include-metadata",
           "key": "includeMetadata",
           "required": false,
-          "description": "Pass `--include-metadata true` to surface the side-channel content the rendered body hides. For docx (`## DOCX metadata`): core/app/custom document properties, people registry, external hyperlinks, comments, tracked changes (insertions + deletions), hidden-formatted text (w:vanish), field instructions (MERGEFIELD / HYPERLINK / DOCVARIABLE), bookmarks. For xlsx (`## Workbook metadata`): core/app/custom properties, external relationships, defined names, hidden / very-hidden sheets, legacy cell comments, threaded comments, persons. For pptx (`## PPTX metadata`): properties, external relationships, slide tags, comment authors + comments (legacy + modern), and per-slide title / speaker notes / hidden flag — returned as a standalone document since pptx has no convertible body (use `download-drive-item-as-pdf` for slide visuals). For OpenDocument (`.odt`/`.ods`/`.odp`, `## OpenDocument metadata`): Dublin Core + ODF properties, keywords, user-defined custom fields — appended after the converted body. Each OOXML family also covers its macro-enabled (`.docm` / `.xlsm` / `.pptm`) and template (`.dotx` / `.xltx` / `.potx`, etc.) variants, with a `### Macros (VBA)` section flagging an embedded `vbaProject.bin`. No-op on other sources.",
+          "description": "Pass `--include-metadata true` to surface the side-channel content the rendered body hides. For docx (`## DOCX metadata`): core/app/custom document properties, people registry, external hyperlinks, comments, tracked changes (a deletion sitting next to an insertion by the same author is reported once as a `replacement` carrying `before` + `after`; the halves that pair with nothing stay under `insertions` / `deletions`; `moves` joins the two ends of a moved span by its range name; `formatChanges` names which run or paragraph properties a reviewer altered. Table-structure revisions — cell insert / delete / merge, numbering and section properties — are still unreported), hidden-formatted text (w:vanish), field instructions (MERGEFIELD / HYPERLINK / DOCVARIABLE), bookmarks. For xlsx (`## Workbook metadata`): core/app/custom properties, external relationships, defined names, hidden / very-hidden sheets, legacy cell comments, threaded comments, persons. For pptx (`## PPTX metadata`): properties, external relationships, slide tags, comment authors + comments (legacy + modern), and per-slide title / speaker notes / hidden flag — returned as a standalone document since pptx has no convertible body (use `download-drive-item-as-pdf` for slide visuals). For OpenDocument (`.odt`/`.ods`/`.odp`, `## OpenDocument metadata`): Dublin Core + ODF properties, keywords, user-defined custom fields — appended after the converted body. Each OOXML family also covers its macro-enabled (`.docm` / `.xlsm` / `.pptm`) and template (`.dotx` / `.xltx` / `.potx`, etc.) variants, with a `### Macros (VBA)` section flagging an embedded `vbaProject.bin`. No-op on other sources.",
           "argumentHint": {
             "kind": "magicValue",
             "values": [
@@ -715,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",
@@ -915,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...'",
@@ -995,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."
         },
         {
@@ -1067,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`."
         },
         {
@@ -1134,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",
@@ -1154,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",
@@ -1377,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",
@@ -1412,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."
         },
         {
@@ -1638,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."
         },
         {
@@ -1711,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",
@@ -1747,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...'",
@@ -1778,17 +1676,7 @@
           "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...'",
@@ -1806,13 +1694,7 @@
           "name": "message-id",
           "key": "messageId",
           "required": false,
-          "aliases": [
-            {
-              "name": "id",
-              "key": "id"
-            }
-          ],
-          "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. Accepts `--id` as an alias.",
+          "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"
           }
@@ -1905,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",
@@ -1960,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...'",
@@ -2013,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'",
@@ -2041,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'",
@@ -2069,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'",
@@ -2097,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'",
@@ -2125,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)."
         },
         {
@@ -2261,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."
         },
         {
@@ -2411,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",
@@ -2453,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'",
@@ -2478,12 +2264,6 @@
           "name": "site-id",
           "key": "siteId",
           "required": true,
-          "aliases": [
-            {
-              "name": "id",
-              "key": "id"
-            }
-          ],
           "description": "SharePoint site ID."
         }
       ],
@@ -2538,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`."
         },
         {
@@ -2610,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`."
         },
         {
@@ -2672,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",
@@ -2714,7 +2466,7 @@
     },
     {
       "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.",
+      "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 basic token — no elevated login needed. On a tenant that restricts basic directory reads the id path falls back to the elevated M365 token; re-capture that with `ask-marcel-office login` (preflight tiers with `ask-marcel-office scopes-check`, no Graph call). 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)",
@@ -2724,13 +2476,7 @@
           "name": "user-id",
           "key": "userId",
           "required": true,
-          "aliases": [
-            {
-              "name": "id",
-              "key": "id"
-            }
-          ],
-          "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`."
+          "description": "Azure AD user ID, UPN, or email (returns the full profile via the basic token, falling back to the elevated token only on tenants that restrict basic directory reads), OR a display name (returns relevant-people candidates on the basic token). Discover ids via `list-relevant-people` or `microsoft-search-query`."
         },
         {
           "name": "select",
@@ -2746,7 +2492,7 @@
         }
       ],
       "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.",
+      "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 resolves on the basic token; on a tenant that restricts basic directory reads it falls back to the elevated M365 token, which fail-fasts with `secondary_token_unavailable` when that token is cold (preflight with `ask-marcel-office scopes-check`, re-capture with `ask-marcel-office login`).",
       "needsElevatedToken": true
     },
     {
@@ -2761,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)."
         },
         {
@@ -2876,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`."
         },
         {
@@ -2950,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)."
         },
         {
@@ -3103,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`."
         },
         {
@@ -3213,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)."
         },
         {
@@ -3285,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)."
         },
         {
@@ -3377,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`."
         },
         {
@@ -3458,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`)."
         },
         {
@@ -3492,7 +3166,7 @@
         }
       ],
       "example": "ask-marcel-office list-conversation-messages --conversation-id 'AAQkAD...=' --top 5 --select id,subject,receivedDateTime",
-      "responseShape": "collection of Microsoft Graph `message` resources under `value[]` (unordered)",
+      "responseShape": "collection of Microsoft Graph `message` resources under `value[]` (unordered). This command ships no default `$select`, so an unflagged call returns the full `message` resource. `internetMessageHeaders` IS honored here (verified live 2026-08-29): naming it in `--select` returns the raw RFC 5322 headers for every message in the thread in ONE call, so a per-message `get-mail-message --select internetMessageHeaders` follow-up is unnecessary. Use `get-mail-message-mime` when the complete raw source, not just the headers, is needed.",
       "pagination": true
     },
     {
@@ -4203,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",
@@ -4307,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)."
         },
         {
@@ -4392,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."
         },
         {
@@ -4453,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."
         },
         {
@@ -4514,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."
         },
         {
@@ -4575,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."
         },
         {
@@ -4636,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."
         },
         {
@@ -4789,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",
@@ -4870,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",
@@ -4931,14 +4531,21 @@
           "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`."
         },
+        {
+          "name": "include-hidden-folders",
+          "key": "includeHiddenFolders",
+          "required": false,
+          "description": "Graph HIDES folders flagged as hidden from this listing by default (a mailbox typically hides system folders such as `Social Activity Notifications`, and an Outlook client can hide any folder). Pass `true` to append the plain `includeHiddenFolders=true` query parameter and get them as well; every returned folder then carries `isHidden` to tell the two apart. Omit it for the default visible-only listing.",
+          "argumentHint": {
+            "kind": "magicValue",
+            "values": [
+              "true",
+              "false"
+            ]
+          }
+        },
         {
           "name": "top",
           "key": "top",
@@ -4992,12 +4599,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`. 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."
         },
         {
@@ -5043,7 +4644,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()",
@@ -5053,12 +4654,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`."
         },
         {
@@ -5067,12 +4662,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",
@@ -5085,12 +4674,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",
@@ -5099,7 +4682,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
     },
     {
@@ -5110,6 +4693,19 @@
       "graphPathTemplate": "/me/mailFolders",
       "graphDocsUrl": "https://learn.microsoft.com/en-us/graph/api/user-list-mailfolders",
       "options": [
+        {
+          "name": "include-hidden-folders",
+          "key": "includeHiddenFolders",
+          "required": false,
+          "description": "Graph HIDES folders flagged as hidden from this listing by default (a mailbox typically hides system folders such as `Social Activity Notifications`, and an Outlook client can hide any folder). Pass `true` to append the plain `includeHiddenFolders=true` query parameter and get them as well; every returned folder then carries `isHidden` to tell the two apart. Omit it for the default visible-only listing.",
+          "argumentHint": {
+            "kind": "magicValue",
+            "values": [
+              "true",
+              "false"
+            ]
+          }
+        },
         {
           "name": "top",
           "key": "top",
@@ -5389,12 +4985,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`."
         },
         {
@@ -5499,17 +5089,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",
@@ -5575,17 +5155,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",
@@ -5610,17 +5180,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'",
@@ -5995,12 +5555,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)."
         },
         {
@@ -6056,36 +5610,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)."
         },
         {
@@ -6178,6 +5714,80 @@
       "responseShape": "collection of Microsoft Graph `sharedInsight` resources under `value[]`",
       "pagination": true
     },
+    {
+      "name": "list-shared-mailbox-child-folders",
+      "summary": "List the subfolders of one mail folder in a shared or delegated mailbox. The `/me` sibling is `list-mail-child-folders`. Walk it from the folder IDs `list-shared-mailbox-folders` returns to reach nested custom folders. 403 if the signed-in user does not have shared access to that mailbox.",
+      "category": "mail",
+      "graphMethod": "GET",
+      "graphPathTemplate": "/users/{user-id}/mailFolders/{mail-folder-id}/childFolders",
+      "graphDocsUrl": "https://learn.microsoft.com/en-us/graph/api/mailfolder-list-childfolders",
+      "options": [
+        {
+          "name": "user-id",
+          "key": "userId",
+          "required": true,
+          "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)."
+        },
+        {
+          "name": "mail-folder-id",
+          "key": "mailFolderId",
+          "required": true,
+          "description": "Mail folder ID or well-known name (`inbox`, `sentitems`, etc.) inside that mailbox. Returned by `ask-marcel-office list-shared-mailbox-folders`."
+        },
+        {
+          "name": "include-hidden-folders",
+          "key": "includeHiddenFolders",
+          "required": false,
+          "description": "Graph HIDES folders flagged as hidden from this listing by default (a mailbox typically hides system folders such as `Social Activity Notifications`, and an Outlook client can hide any folder). Pass `true` to append the plain `includeHiddenFolders=true` query parameter and get them as well; every returned folder then carries `isHidden` to tell the two apart. Omit it for the default visible-only listing.",
+          "argumentHint": {
+            "kind": "magicValue",
+            "values": [
+              "true",
+              "false"
+            ]
+          }
+        },
+        {
+          "name": "top",
+          "key": "top",
+          "required": false,
+          "description": "OData $top: maximum number of items to return on this page (positive integer, ≤ 1000). Graph silently caps at 1000 on every collection endpoint, so the CLI rejects larger values with a clear validation error rather than letting the request silently truncate. Combine with `next-page` to paginate beyond the cap."
+        },
+        {
+          "name": "skip",
+          "key": "skip",
+          "required": false,
+          "description": "OData $skip: skip the first N items before returning results (non-negative integer). Useful with $top for offset paging."
+        },
+        {
+          "name": "select",
+          "key": "select",
+          "required": false,
+          "description": "OData $select: comma-separated list of fields to include in each item (e.g. `id,subject,from`). May shrink payloads dramatically — Graph honors $select on most endpoints, but some collections (notably `/me/mailboxSettings`, `/me/outlook/masterCategories`, `/me/mailFolders/inbox/messageRules`) silently ignore it and always return the full resource. Bogus field names are silently dropped by Graph — if a field you asked for is missing from the response, double-check the spelling against the documented `responseShape`."
+        },
+        {
+          "name": "filter",
+          "key": "filter",
+          "required": false,
+          "description": "OData $filter: predicate to narrow results server-side. Quoting rules: string literals MUST use SINGLE quotes (`subject eq 'invoice'`), NOT double quotes — Graph rejects `subject eq \"invoice\"` with `InvalidFilterClause`. To embed a single quote inside a string, double it (`subject eq 'O''Brien'`). Booleans, numbers, and dates are unquoted (`isRead eq false`, `receivedDateTime ge 2026-01-01T00:00:00Z`). Wrap the whole flag value in shell DOUBLE quotes so the inner single quotes survive (`--filter \"subject eq 'invoice'\"`). Same syntax Graph documents per resource type."
+        },
+        {
+          "name": "orderby",
+          "key": "orderby",
+          "required": false,
+          "description": "OData $orderby: sort expression with optional asc/desc (e.g. `receivedDateTime desc`). Some Graph filter combinations are rejected; remove $orderby if InefficientFilter occurs."
+        },
+        {
+          "name": "expand",
+          "key": "expand",
+          "required": false,
+          "description": "OData $expand: navigation properties to include inline (e.g. `attachments`). Increases response size; use sparingly."
+        }
+      ],
+      "example": "ask-marcel-office list-shared-mailbox-child-folders --user-id 'shared-mailbox@contoso.com' --mail-folder-id 'inbox'",
+      "responseShape": "collection of Microsoft Graph `mailFolder` resources under `value[]`",
+      "pagination": true
+    },
     {
       "name": "list-shared-mailbox-folder-messages",
       "summary": "List messages in a single folder of a shared / delegated mailbox.",
@@ -6239,6 +5849,74 @@
       "responseShape": "collection of Microsoft Graph `message` resources under `value[]`",
       "pagination": true
     },
+    {
+      "name": "list-shared-mailbox-folders",
+      "summary": "List the top-level mail folders of a shared or delegated mailbox. The `/me` sibling is `list-mail-folders`. Use it to discover the folder IDs that `list-shared-mailbox-folder-messages` needs: without it only the well-known names (`inbox`, `sentitems`, `drafts`, …) are reachable, so custom folders are invisible. 403 if the signed-in user does not have shared access to that mailbox.",
+      "category": "mail",
+      "graphMethod": "GET",
+      "graphPathTemplate": "/users/{user-id}/mailFolders",
+      "graphDocsUrl": "https://learn.microsoft.com/en-us/graph/api/user-list-mailfolders",
+      "options": [
+        {
+          "name": "user-id",
+          "key": "userId",
+          "required": true,
+          "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)."
+        },
+        {
+          "name": "include-hidden-folders",
+          "key": "includeHiddenFolders",
+          "required": false,
+          "description": "Graph HIDES folders flagged as hidden from this listing by default (a mailbox typically hides system folders such as `Social Activity Notifications`, and an Outlook client can hide any folder). Pass `true` to append the plain `includeHiddenFolders=true` query parameter and get them as well; every returned folder then carries `isHidden` to tell the two apart. Omit it for the default visible-only listing.",
+          "argumentHint": {
+            "kind": "magicValue",
+            "values": [
+              "true",
+              "false"
+            ]
+          }
+        },
+        {
+          "name": "top",
+          "key": "top",
+          "required": false,
+          "description": "OData $top: maximum number of items to return on this page (positive integer, ≤ 1000). Graph silently caps at 1000 on every collection endpoint, so the CLI rejects larger values with a clear validation error rather than letting the request silently truncate. Combine with `next-page` to paginate beyond the cap."
+        },
+        {
+          "name": "skip",
+          "key": "skip",
+          "required": false,
+          "description": "OData $skip: skip the first N items before returning results (non-negative integer). Useful with $top for offset paging."
+        },
+        {
+          "name": "select",
+          "key": "select",
+          "required": false,
+          "description": "OData $select: comma-separated list of fields to include in each item (e.g. `id,subject,from`). May shrink payloads dramatically — Graph honors $select on most endpoints, but some collections (notably `/me/mailboxSettings`, `/me/outlook/masterCategories`, `/me/mailFolders/inbox/messageRules`) silently ignore it and always return the full resource. Bogus field names are silently dropped by Graph — if a field you asked for is missing from the response, double-check the spelling against the documented `responseShape`."
+        },
+        {
+          "name": "filter",
+          "key": "filter",
+          "required": false,
+          "description": "OData $filter: predicate to narrow results server-side. Quoting rules: string literals MUST use SINGLE quotes (`subject eq 'invoice'`), NOT double quotes — Graph rejects `subject eq \"invoice\"` with `InvalidFilterClause`. To embed a single quote inside a string, double it (`subject eq 'O''Brien'`). Booleans, numbers, and dates are unquoted (`isRead eq false`, `receivedDateTime ge 2026-01-01T00:00:00Z`). Wrap the whole flag value in shell DOUBLE quotes so the inner single quotes survive (`--filter \"subject eq 'invoice'\"`). Same syntax Graph documents per resource type."
+        },
+        {
+          "name": "orderby",
+          "key": "orderby",
+          "required": false,
+          "description": "OData $orderby: sort expression with optional asc/desc (e.g. `receivedDateTime desc`). Some Graph filter combinations are rejected; remove $orderby if InefficientFilter occurs."
+        },
+        {
+          "name": "expand",
+          "key": "expand",
+          "required": false,
+          "description": "OData $expand: navigation properties to include inline (e.g. `attachments`). Increases response size; use sparingly."
+        }
+      ],
+      "example": "ask-marcel-office list-shared-mailbox-folders --user-id 'shared-mailbox@contoso.com'",
+      "responseShape": "collection of Microsoft Graph `mailFolder` resources under `value[]`",
+      "pagination": true
+    },
     {
       "name": "list-shared-mailbox-messages",
       "summary": "List messages from a shared or delegated mailbox the signed-in user has read access to. Same shape as `list-mail-messages` but scoped to a specific mailbox owner. 403 if the signed-in user does not have shared access to that mailbox.",
@@ -6251,12 +5929,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)."
         },
         {
@@ -6371,13 +6043,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",
@@ -6426,12 +6092,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`."
         },
         {
@@ -6539,12 +6199,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`."
         },
         {
@@ -6655,12 +6309,6 @@
           "name": "site-id",
           "key": "siteId",
           "required": true,
-          "aliases": [
-            {
-              "name": "id",
-              "key": "id"
-            }
-          ],
           "description": "SharePoint site ID."
         },
         {
@@ -6722,13 +6370,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",
@@ -6783,12 +6425,6 @@
           "name": "site-id",
           "key": "siteId",
           "required": true,
-          "aliases": [
-            {
-              "name": "id",
-              "key": "id"
-            }
-          ],
           "description": "SharePoint site ID."
         },
         {
@@ -6838,12 +6474,6 @@
           "name": "site-id",
           "key": "siteId",
           "required": true,
-          "aliases": [
-            {
-              "name": "id",
-              "key": "id"
-            }
-          ],
           "description": "SharePoint site ID. Returned by `search-sharepoint-sites-by-name`."
         },
         {
@@ -6874,12 +6504,6 @@
           "name": "site-id",
           "key": "siteId",
           "required": true,
-          "aliases": [
-            {
-              "name": "id",
-              "key": "id"
-            }
-          ],
           "description": "SharePoint site ID."
         },
         {
@@ -6929,12 +6553,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."
         },
         {
@@ -6990,36 +6608,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)."
         },
         {
@@ -7074,12 +6674,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`."
         },
         {
@@ -7110,12 +6704,6 @@
           "name": "team-id",
           "key": "teamId",
           "required": true,
-          "aliases": [
-            {
-              "name": "id",
-              "key": "id"
-            }
-          ],
           "description": "Microsoft Teams team ID."
         }
       ],
@@ -7135,12 +6723,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`."
         },
         {
@@ -7191,12 +6773,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`."
         }
       ],
@@ -7243,29 +6819,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",
@@ -7357,21 +6917,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",
@@ -7426,21 +6972,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...'",
@@ -7508,12 +7040,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)."
         },
         {
@@ -7589,7 +7115,7 @@
     },
     {
       "name": "next-page",
-      "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.",
+      "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. When the cursor came from a partner-tenant (guest) drive listing, pass the same `--tenant-id` you used on the originating command, since the cursor carries no tenant and without it page 2 fails with `invalidAudienceUri`.",
       "category": "meta",
       "graphMethod": "GET",
       "graphPathTemplate": "{url}",
@@ -7603,6 +7129,12 @@
           "argumentHint": {
             "kind": "graphSubpath"
           }
+        },
+        {
+          "name": "tenant-id",
+          "key": "tenantId",
+          "required": false,
+          "description": "Tenant GUID of a PARTNER tenant you are a guest in. Pass it only to continue a partner-tenant drive listing (a folder / `*-drive-item` cursor whose file lives in another tenant), using the same `--tenant-id` you gave the originating command (ultimately from `resolve-drive-share-link`). The page is then signed with a guest token for that tenant; without it a partner-tenant cursor 401s with `invalidAudienceUri` on page 2 even though page 1 succeeded. Omit it for your own tenant and for every `/me/...` and chat cursor (the normal case)."
         }
       ],
       "example": "ask-marcel-office next-page --url 'https://graph.microsoft.com/v1.0/me/messages?$skip=10'",
@@ -7733,14 +7265,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. 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.",
+      "summary": "Decode the cached Teams web client access token and return its scopes, audience, and expiry without making a Graph call. It never opens a browser: an expired or missing session is reported as such (negative `expiresInSeconds`, or a not-signed-in error), and `login` is the command that refreshes it. 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: 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."
+      "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. EVERY tier — `basic` included — is reported as its own block with the SAME shape, and each block carries a `reads` line: a plain-language description of what that tier lets you read (e.g. `chatsvcagg` -> \"Teams chat message content\"), so a caller never has to know what a tier codename means. The `basic` block mirrors the loose top-level `scopes`/`expiresAt`/`expiresInSeconds` fields, which are still emitted unchanged for back-compat; prefer the block. `basic.available` applies the same 300-second freshness buffer as the other tiers, so `available` means the same thing everywhere."
     },
     {
       "name": "search-all-accessible-sites",
@@ -7902,12 +7434,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."
         },
         {
@@ -7956,20 +7482,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",
@@ -8002,7 +7522,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
     },
@@ -8063,23 +7583,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. 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 would replace the whole body and drop the thread. 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.",
+      "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} (+ a GET of body,isDraft first when {comment} is used)",
+      "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"
           }
@@ -8094,7 +7608,7 @@
           "name": "body-content",
           "key": "bodyContent",
           "required": false,
-          "description": "New email body content. Replaces the ENTIRE body, quoted history included. On a threaded reply or forward draft this is almost never what you want - use --comment to revise only your own text and keep the quote. Pass --body-content-type HTML for rich text. Mutually exclusive with --comment."
+          "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",
@@ -8102,6 +7616,19 @@
           "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",
@@ -8150,7 +7677,7 @@
       ],
       "example": "ask-marcel-office update-mail-draft --message-id \"AAMkAD...\" --subject \"Updated: Q3 Report\" --to-recipients \"alice@example.com,charlie@example.com\"",
       "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",
+      "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
     }
   ]