ask-marcel-office-cli 2.2.0 → 2.3.0

package/dist/presenter/output.d.ts

@@ -1,7 +1,7 @@
 import type { Logger } from '../use-cases/ports/logger.js';
 import type { ErrorSource } from './error-hints.js';
-import type { OutputFormat } from './render-to-string.js';
-declare const render: (data: unknown, logger: Logger, format: OutputFormat) => void;
+import type { OutputFormat, SizeHintContext } from './render-to-string.js';
+declare const render: (data: unknown, logger: Logger, format: OutputFormat, context?: SizeHintContext) => void;
 declare const renderError: (message: string, format: OutputFormat, errorCode?: string, explicitSource?: ErrorSource, retryAfterSeconds?: number) => void;
 export { render, renderError };
 export type { OutputFormat };

package/dist/presenter/render-to-string.d.ts

@@ -1,10 +1,42 @@
 import type { ErrorSource } from './error-hints.js';
 type OutputFormat = 'text' | 'json';
+/**
+ * Which front end the caller is on. It changes what a remedy can even BE: a
+ * terminal caller can redirect stdout to a file, an MCP client cannot (it has
+ * no shell), and the `--output-path` flag reaches MCP as an `outputPath` tool
+ * param rather than a flag.
+ */
+type RenderSurface = 'cli' | 'mcp';
+/**
+ * What the presenter needs in order to name a remedy the caller can actually
+ * use. Built in composition (which owns the command manifest); omitted by the
+ * renders that have no command behind them at all — the 548 KB `list-commands`
+ * manifest, a login summary, a logout status.
+ *
+ * 2026-07-23: the banner used to call `--output-path` a "universal remedy
+ * (works on every command)". It is not. Plain-JSON commands REFUSE the flag,
+ * and the two commands that trip the banner most often (`search-all-files`,
+ * `microsoft-search-query`) advertise only `--query` — so every remedy the
+ * banner named was a dead end there, and an agentic caller following it burned
+ * a call to find out.
+ */
+type SizeHintContext = {
+    readonly commandName: string;
+    /** `meta.producesBytes` — the manifest flag that decides whether --output-path is accepted. */
+    readonly producesBytes: boolean;
+    readonly supportsSelect: boolean;
+    readonly supportsTop: boolean;
+    readonly surface: RenderSurface;
+};
 /**
  * Render a use-case success value to its final string, newline included.
  * `output.ts` writes this to stdout; `mcp.ts` returns it as tool content.
+ *
+ * `context` is what makes the oversized-response banner honest — pass it
+ * whenever a registry command produced the data. Omit it for the renders that
+ * have no command behind them; the banner then claims no flag-level remedy.
  */
-declare const renderToString: (data: unknown, format: OutputFormat) => string;
+declare const renderToString: (data: unknown, format: OutputFormat, context?: SizeHintContext) => string;
 /**
  * Render an error to its final string, newline included. The `hint` / `source`
  * lookup is shared with the CLI so an MCP consumer sees the same curated
@@ -12,4 +44,4 @@ declare const renderToString: (data: unknown, format: OutputFormat) => string;
  */
 declare const renderErrorToString: (message: string, format: OutputFormat, errorCode?: string, explicitSource?: ErrorSource, retryAfterSeconds?: number) => string;
 export { renderErrorToString, renderToString };
-export type { OutputFormat };
+export type { OutputFormat, RenderSurface, SizeHintContext };

package/dist/use-cases/commands/command-types.d.ts

@@ -5,10 +5,6 @@ type CommandSchema = z.ZodType;
 type CommandExecute = (graph: GraphClient, params: Record<string, string>) => Promise<Result<unknown, import('../../infra/graph-client.js').GraphError>>;
 type CommandCategory = 'drive' | 'excel' | 'sharepoint' | 'tasks' | 'mail' | 'notes' | 'user' | 'calendar' | 'chats' | 'teams' | 'meta' | 'lifecycle';
 type CommandHttpMethod = 'GET' | 'POST' | 'PATCH' | 'DELETE';
-type CommandOptionAlias = {
-    readonly name: string;
-    readonly key: string;
-};
 /**
  * Structured type-hint for a CLI flag value. Surfaces in `help-json` so an
  * LLM can avoid the trial-and-error of "is this an ID or a name?" prose
@@ -38,13 +34,6 @@ type CommandOptionMeta = {
      * commands accept but do not demand.
      */
     readonly required: boolean;
-    /**
-     * Optional secondary spellings of the same flag. Both the canonical
-     * `name` and every alias name are accepted on the command line; values
-     * passed under an alias are normalized to the canonical `key` before
-     * the schema runs. The canonical name is what `--help` shows first.
-     */
-    readonly aliases?: ReadonlyArray<CommandOptionAlias>;
     /**
      * Structured value-type hint for LLM consumers. Optional.
      */
@@ -80,14 +69,6 @@ type PaginationStrategy =
 type CommandMeta = {
     readonly summary: string;
     readonly category: CommandCategory;
-    /**
-     * Deprecated former command names kept working as commander-level aliases for
-     * back-compat after a rename (e.g. `download-onedrive-file-content` →
-     * `download-drive-item-content`). The canonical registry key is what `--help`
-     * and the manifest list first; each alias here is also accepted on the CLI and
-     * surfaced in the manifest so an LLM that learned the old name still resolves.
-     */
-    readonly commandAliases?: ReadonlyArray<string>;
     readonly graphMethod: CommandHttpMethod;
     readonly graphPathTemplate: string;
     readonly graphDocsUrl: string;
@@ -178,4 +159,4 @@ type Command = {
      */
     readonly executeLocal?: (fs: import('../ports/filesystem.js').FileSystem, params: Record<string, string>) => Promise<Result<unknown, import('../../infra/graph-client.js').GraphError>>;
 };
-export type { ArgumentHint, Command, CommandCategory, CommandExecute, CommandHttpMethod, CommandMeta, CommandOptionAlias, CommandOptionMeta, CommandPositionalArgumentMeta, CommandSchema, PaginationStrategy, };
+export type { ArgumentHint, Command, CommandCategory, CommandExecute, CommandHttpMethod, CommandMeta, CommandOptionMeta, CommandPositionalArgumentMeta, CommandSchema, PaginationStrategy, };

package/dist/use-cases/commands/create-forward-draft.d.ts

@@ -4,7 +4,7 @@ declare const schema: z.ZodObject<{
     forwardMessageId: z.ZodString;
     toRecipients: z.ZodString;
     ccRecipients: z.ZodOptional<z.ZodString>;
-    bodyContent: z.ZodString;
+    comment: z.ZodString;
     subject: z.ZodOptional<z.ZodString>;
     bodyContentType: z.ZodOptional<z.ZodEnum<{
         Text: "Text";

package/dist/use-cases/commands/create-reply-draft.d.ts

@@ -2,7 +2,7 @@ import { z } from 'zod';
 import type { Command, CommandMeta } from './command-types.js';
 declare const schema: z.ZodObject<{
     replyToMessageId: z.ZodString;
-    bodyContent: z.ZodString;
+    comment: z.ZodString;
     subject: z.ZodOptional<z.ZodString>;
     replyAll: z.ZodOptional<z.ZodEnum<{
         true: "true";

package/dist/use-cases/commands/docs-render.d.ts

@@ -3,7 +3,6 @@ export type CommandManifestEntry = {
     readonly name: string;
     readonly summary: string;
     readonly category: CommandCategory;
-    readonly commandAliases?: CommandMeta['commandAliases'];
     readonly graphMethod: CommandMeta['graphMethod'];
     readonly graphPathTemplate: string;
     readonly graphDocsUrl: string;

package/dist/use-cases/commands/draft-comment-splicer.d.ts

@@ -21,9 +21,16 @@ declare const findBodyInsertStart: (html: string) => number;
  * silently dropping the real quoted history below.
  */
 declare const commentCarriesQuoteBoundary: (commentHtml: string) => boolean;
+/**
+ * True when a draft body still carries the quoted history Graph minted with it.
+ * Dispatches on the draft's own contentType: the HTML and plain-text boundary
+ * markers are different things entirely. Used to refuse a whole-body replace
+ * that would drop the quote (2026-07-23 bug report).
+ */
+declare const bodyCarriesQuote: (contentType: string, content: string) => boolean;
 /** The refusal copy for `commentCarriesQuoteBoundary`, named for the flag that carried it. */
 declare const boundaryMarkerRefusal: (flagName: string) => string;
 declare const insertCommentAboveQuote: (html: string, commentHtml: string) => SpliceResult;
 declare const replaceCommentAboveQuote: (html: string, commentHtml: string) => SpliceResult;
 declare const replacePlainTextCommentAboveQuote: (text: string, comment: string) => PlainTextSpliceResult;
-export { boundaryMarkerRefusal, commentCarriesQuoteBoundary, escapeTextAsHtml, findBodyInsertStart, insertCommentAboveQuote, replaceCommentAboveQuote, replacePlainTextCommentAboveQuote, };
+export { bodyCarriesQuote, boundaryMarkerRefusal, commentCarriesQuoteBoundary, escapeTextAsHtml, findBodyInsertStart, insertCommentAboveQuote, replaceCommentAboveQuote, replacePlainTextCommentAboveQuote, };

package/dist/use-cases/commands/list-mail-folder-messages-delta.d.ts

@@ -1,4 +1,12 @@
-import type { CommandMeta } from './command-types.js';
-declare const execute: import("./command-types.js").CommandExecute, schema: import("./command-types.js").CommandSchema;
+import { z } from 'zod';
+import type { Command, CommandMeta } from './command-types.js';
+declare const schema: z.ZodObject<{
+    mailFolderId: z.ZodString;
+    filter: z.ZodOptional<z.ZodString>;
+    select: z.ZodOptional<z.ZodString>;
+    top: z.ZodOptional<z.ZodString>;
+    expand: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const execute: Command['execute'];
 declare const meta: CommandMeta;
 export { execute, meta, schema };

package/dist/use-cases/commands/reject-unknown-params.d.ts

@@ -0,0 +1,16 @@
+import type { Result } from '../../domain/result.js';
+import type { GraphError } from '../../infra/graph-client.js';
+import type { Command } from './command-types.js';
+/**
+ * Returns the rejection for any param key the command does not declare, or
+ * `undefined` when every key is known. Exported for the registry wrapper.
+ */
+declare const rejectUnknownParams: (schema: Command["schema"], params: Record<string, string>) => Result<never, GraphError> | undefined;
+/**
+ * Wraps a command so `execute` / `executeLocal` refuse unknown params before
+ * running. Applied at registry assembly, which is the single choke point every
+ * surface passes through — including a library caller that never touches
+ * composition.
+ */
+declare const withUnknownParamRejection: (command: Command) => Command;
+export { rejectUnknownParams, withUnknownParamRejection };

package/dist/use-cases/commands/resolve-command.d.ts

@@ -1,17 +1,15 @@
 import type { Result } from '../../domain/result.js';
 import type { Command } from './command-types.js';
 /**
- * Name -> command lookup that also honours `meta.commandAliases`.
+ * Name -> command lookup shared by every non-commander front end.
  *
- * The CLI gets alias resolution for free from commander (`commandDef.alias(...)`
- * in `cli.ts`), so nothing needed this until a second front end appeared. The
- * MCP gateway has no commander, and its three command-taking tools
- * (`get-command-docs`, `run-command`, `run-write-command`) each need the same
- * lookup — Rule of Three, so it lives here rather than inline.
+ * The MCP gateway's three command-taking tools (`get-command-docs`,
+ * `run-command`, `run-write-command`) each need the same lookup — Rule of
+ * Three, so it lives here rather than inline.
  *
- * Returns the CANONICAL name alongside the command so every downstream concern
- * (docs rendering, the `mutates` read/write gate, error messages) keys off one
- * spelling regardless of which one the caller used.
+ * 2026-07-24: one name per command. Deprecated-name resolution
+ * (`meta.commandAliases`) was removed with the alias system; an old name gets
+ * the unknown-command rejection with the full list, same as any typo.
  */
 export type ResolveCommandError = {
     readonly type: 'unknown_command';

package/dist/use-cases/commands/search-onenote-pages.d.ts

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import type { Command, CommandMeta } from './command-types.js';
 declare const schema: z.ZodObject<{
-    titleSubstring: z.ZodString;
+    query: z.ZodString;
     select: z.ZodOptional<z.ZodString>;
     top: z.ZodOptional<z.ZodString>;
     skip: z.ZodOptional<z.ZodString>;

package/dist/use-cases/commands/update-mail-draft.d.ts

@@ -5,6 +5,10 @@ declare const schema: z.ZodObject<{
     subject: z.ZodOptional<z.ZodString>;
     bodyContent: z.ZodOptional<z.ZodString>;
     comment: z.ZodOptional<z.ZodString>;
+    replaceQuotedHistory: z.ZodOptional<z.ZodEnum<{
+        true: "true";
+        false: "false";
+    }>>;
     bodyContentType: z.ZodOptional<z.ZodEnum<{
         Text: "Text";
         HTML: "HTML";

package/docs/COMMANDS.md

@@ -36,12 +36,12 @@ For everything else:
 | `download-drive-item-version` | Download a *non-current* historical version of a OneDrive / SharePoint file. `--format original` (default) returns the raw bytes — Graph refuses to serve the current version through this endpoint with "You cannot get the content of the current version"; for the current version use `download-drive-item-content`. `--format pdf` runs Graph `?format=pdf` for Office docs; plain-text and `pdf` sources short-circuit to raw bytes with `passthrough: true` + a note (Graph rejects `pdf → pdf` with InputFormatNotSupported). `--format markdown` runs the local conversion pipeline (mammoth for docx, sheetjs for xlsx, csv → table, odt/ods/odp via content.xml, plain-text passthrough). All three formats use an M365ChatClient-elevated Graph token (captured at login from m365.cloud.microsoft) — the Teams web client token returns 403 logicalPermissionAccessDenied on historical-version stream content. The CLI follows the SharePoint streamContent redirect internally so the LLM never has to fetch an external URL. caveat for `--format pdf`: Graph sometimes silently falls back to raw source bytes for the current version (which Graph occasionally serves through this endpoint) — when the response carries `passthrough: true`, save with the source extension, not `.pdf` (the global output-path flag refuses the mismatch). | `--drive-id`, `--item-id`, `--version-id`, `--format`, `--include-metadata` | `GET /drives/{drive-id}/items/{item-id}/versions/{version-id}/content` |
 | `extract-drive-item-images` | Extract the embedded images from a OneDrive / SharePoint document. For docx / xlsx / pptx (and their macro-enabled / template variants) it reads the OOXML media parts directly (png/jpg/gif/bmp/tiff/webp/svg) — including original full-resolution / un-cropped originals and images on hidden slides the rendered view never shows. For a pdf it walks every page via unpdf and re-encodes each painted image as PNG (note: page-oriented — it captures images as painted on each page, but NOT layer-hidden/unpainted XObjects or the full uncropped original behind a clipped image). Pair with the global output-dir flag to write every image to a folder; otherwise the bytes ride back base64-encoded in the response. svg rides back as its XML source (which carries the diagram text labels); legacy vector (emf/wmf) and audio/video are skipped. For any other format the command returns a 415 pointing at `download-drive-item-content`. | `--drive-id`, `--item-id`, `--tenant-id` | `GET /drives/{drive-id}/items/{item-id}/content` |
 | `extract-sharepoint-links-in-documents` | Find every `*.sharepoint.com` URL embedded in a Word / Excel / PowerPoint or OpenDocument file on OneDrive or SharePoint and resolve each one to its driveItem (driveId, itemId, name, webUrl) so the agent can feed those into `download-drive-item-as-pdf` / `-as-markdown` etc. The document sibling of `extract-sharepoint-links-in-mail`. For OOXML (.docx/.xlsx/.pptx) it reads external hyperlinks from the package’s relationship parts (`_rels/*.rels`, `TargetMode="External"`); for OpenDocument (.odt/.ods/.odp) it reads the inline `xlink:href` links in content.xml / styles.xml — either way it catches links wherever they live (body text, headers/footers, cell formulas, slide shapes). Read-only — no conversion happens here. Capped at 25 unique URLs per call (returns `truncated: true` and `skippedCount` when there are more); duplicates are deduplicated; per-link errors are captured inside each entry instead of failing the whole call. Non-zip inputs (pdf/images) return an api_error. | `--drive-id`, `--item-id` | `GET /drives/{drive-id}/items/{item-id}/content` |
-| `get-drive-delta` | Get the incremental change set (added / modified / deleted items) under a OneDrive / SharePoint folder. Use the `@odata.deltaLink` from a previous response to resume. | `--drive-id`, `--item-id`, `--top`, `--select`, `--filter`, `--orderby`, `--expand` | `GET /drives/{drive-id}/items/{item-id}/delta()` |
+| `get-drive-delta` | Get the incremental change set (added / modified / deleted items) under a OneDrive / SharePoint folder. Use the `@odata.deltaLink` from a previous response to resume. | `--drive-id`, `--item-id`, `--top`, `--select`, `--expand` | `GET /drives/{drive-id}/items/{item-id}/delta()` |
 | `get-drive-item` | Get the metadata (driveItem resource) of a single file or folder in OneDrive / SharePoint. Use `--select` to slim the response — a full driveItem can run >10 KB with all the optional facets. | `--drive-id`, `--item-id`, `--tenant-id`, `--select`, `--expand` | `GET /drives/{drive-id}/items/{item-id}` |
 | `get-drive-item-analytics` | Return view / activity analytics for a OneDrive / SharePoint file — `allTime` totals (views, viewers) and `lastSevenDays` rollup. Useful for ranking files by attention or detecting stale content. **Known empty case**: returns `{ allTime: null, lastSevenDays: null }` on low-traffic items, or when the calling identity (the Teams web client basic token) lacks the analytics scope on the tenant. Do not interpret nulls as "no views" — interpret as "not available for this caller". For active files where you expect data and see nulls, escalate to a token with `Reports.Read.All`. | `--drive-id`, `--item-id` | `GET /drives/{drive-id}/items/{item-id}/analytics` |
 | `get-drive-item-created-by-user` | Return the `user` resource for whoever created a OneDrive / SharePoint file — full profile, not just the truncated `createdBy.user` summary embedded in the parent driveItem. Useful when you need title / department / mail of the author. Use `--select` to fetch only the fields you care about (e.g. `--select id,displayName,jobTitle,department,mail`). | `--drive-id`, `--item-id`, `--select`, `--expand` | `GET /drives/{drive-id}/items/{item-id}/createdByUser` |
 | `get-drive-item-last-modified-by-user` | Return the full `user` resource for whoever last modified a OneDrive / SharePoint file — sibling to `get-drive-item-created-by-user`. Use `--select` to fetch only specific fields. | `--drive-id`, `--item-id`, `--select`, `--expand` | `GET /drives/{drive-id}/items/{item-id}/lastModifiedByUser` |
-| `get-drive-root-delta` | Track incremental changes (added / modified / deleted items) anywhere under the signed-in user's OneDrive root. **Takes zero required arguments** — acts implicitly on the signed-in user's primary OneDrive; use `get-drive-delta` to target a specific drive by ID. The first call returns a snapshot plus `@odata.deltaLink`; subsequent calls with that link return only what has changed since. Cross-folder companion to `get-drive-delta` (which scopes to one specific folder). | `--top`, `--select`, `--filter`, `--orderby`, `--expand` | `GET /me/drive/root/delta()` |
+| `get-drive-root-delta` | Track incremental changes (added / modified / deleted items) anywhere under the signed-in user's OneDrive root. **Takes zero required arguments** — acts implicitly on the signed-in user's primary OneDrive; use `get-drive-delta` to target a specific drive by ID. The first call returns a snapshot plus `@odata.deltaLink`; subsequent calls with that link return only what has changed since. Cross-folder companion to `get-drive-delta` (which scopes to one specific folder). | `--top`, `--select`, `--expand` | `GET /me/drive/root/delta()` |
 | `get-drive-root-item` | Get the root folder (driveItem) of a OneDrive / SharePoint drive. Use `--select` to slim the response (e.g. `--select id,name,folder`). | `--drive-id`, `--select`, `--expand` | `GET /drives/{drive-id}/root` |
 | `get-drive-special-folder` | Resolve a OneDrive well-known folder via `--folder-name` (one of `documents`, `photos`, `cameraroll`, `approot`, `music`, `attachments`) without having to navigate from the root. Returns the folder's driveItem (id, name, parentReference, etc.) ready to feed into `list-folder-files` or `download-drive-item-content`. | `--folder-name`, `--select`, `--expand` | `GET /me/drive/special/{folder-name}` |
 | `list-accessible-drives` | Enumerate every drive (document library) the signed-in user can reach — personal OneDrive(s), Teams libraries, SharePoint M365-group sites, drives behind files shared with the user, private/shared Teams channel sites, drives behind recently-used / followed / trending items (activity signals), AND every NON-default document library of each discovered SharePoint site — by unioning `/me/drives`, `/me/joinedTeams`, `/me/memberOf` (Unified groups → `/groups/{id}/drive`), `/me/drive/sharedWithMe`, per-team `/teams/{id}/channels` → `/channels/{ch}/filesFolder` (private/shared channels only — their files live in their own site, not the team default drive), `/me/drive/recent` + `/me/drive/following` + `/me/insights/{trending,used,shared}`, and a path-addressed `/sites/{host}:/sites/{name}:/drives` per discovered site (catches secondary libraries like "Teams Wiki Data" the default-drive vectors miss). Unlike `search-sharepoint-sites-by-name` (which relies on the tenant search index and misses direct-link-only sites + OneDrives), these vectors surface drives the search index never returns; the index in turn returns sites you can open but are not a member of, so the *union of both commands* is the practical maximum on a delegated token. Each drive is tagged with the `sources[]` that found it (a drive can have several). Per-resource "can't reach this one" failures are dropped silently (404 no drive, 403 access-denied / non-member private channel, 423 admin-locked site, 400 stale/unresolvable id); only actionable failures (auth, throttling, 5xx, network) appear in `partialErrors[]`, so it stays signal-only. Fans out one `/groups/{id}/drive` + one `/teams/{id}/channels` call per joined team + member group, a `filesFolder` call per private/shared channel, five fixed activity calls, and one `/sites/{id}/drives` call per discovered site (all capped by `--max-groups`, default 100; raise carefully — large memberships can hit 429 throttling). `/me/followedSites` is not used — it 403s on this token. | `--max-groups`, `--count-files` | `GET /me/drives + /me/joinedTeams + /me/memberOf + /me/drive/sharedWithMe + per-group /groups/<id>/drive + per-team /teams/<id>/channels/<ch>/filesFolder + /me/drive/recent + /me/drive/following + /me/insights/<trending|used|shared> + per-site /sites/<host>:/sites/<name>:/drives` |
@@ -128,9 +128,9 @@ For everything else:
 | `convert-mail-attachment-to-pdf` | Convert an Outlook mail attachment to PDF on the fly. Polymorphic on the attachment’s `@odata.type`: fileAttachment uploads the bytes to a temp folder under /me/drive (large files use Graph’s chunked upload session — no 4 MB ceiling), runs ?format=pdf, then deletes the temp item; referenceAttachment resolves via /shares/{token}/driveItem and runs ?format=pdf in place; plain-text source extensions and `pdf` sources short-circuit to a raw-bytes envelope on either path (Graph’s `?format=pdf` does not accept `pdf` as an input format — pdf attachments are returned as-is). itemAttachment (embedded mail/event/contact) is unsupported here — Graph rejects those source types — use convert-mail-attachment-to-markdown instead. Worst-case wall-clock for huge attachments is ~22 minutes (1 metadata GET + up-to-20 chunk PUTs + 1 convert GET + 1 cleanup DELETE, each capped at 60s). | `--message-id`, `--attachment-id` | `GET /me/messages/{message-id}/attachments/{attachment-id}` |
 | `convert-mail-attachment-zip-to-markdown` | 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). | `--message-id`, `--attachment-id`, `--include-metadata`, `--keep-quoted` | `GET /me/messages/{message-id}/attachments/{attachment-id}` |
 | `convert-mail-to-markdown` | Render a single Outlook email as markdown — headers (`**Subject:**`, `**From:**`, `**To:**`, `**Cc:**` only when present, `**Date:**`), followed by the body run through turndown. By default NO image bytes are fetched: every inline `cid:` image renders as a readable `[inline image: <name>]` placeholder and the images surface in the file-attachments list, so the output stays close to the text size (an email whose 6 KB body carried 30 KB of signature-image base64 now ships at ~6 KB). Pass `--inline-images true` to embed inline images (`isInline:true` + `image/*` content-type, size ≤ 2 MB) as base64 `data:` URIs for self-contained output (non-image inline attachments are never embedded; oversize inline images keep a placeholder note; a cid whose per-image fetch fails degrades to the placeholder too). File attachments are always listed below the body by name + size + id; their bytes are NOT fetched here — call `convert-mail-attachment-to-pdf` or `get-mail-attachment` with the id when you actually need them. Staged-fetch design: one call for the body, one for the attachments-metadata list (only if `hasAttachments:true`), and with `--inline-images true` one per small inline image — replaces the old `?$expand=attachments` which timed out / truncated on messages with multi-MB attachments. | `--message-id`, `--inline-images`, `--keep-quoted` | `GET /me/messages/{message-id}` |
-| `create-forward-draft` | Create an UNSENT forward draft of an existing message. POST /me/messages/{id}/createForward mints the draft (FW: subject, quoted original) with your comment placed above the quote and the recipients set, in one call. Redirects a thread to the right owner without leaving the CLI. The draft is saved in Drafts and can be reviewed, edited, and sent from any Outlook client; the CLI still cannot send. | `--forward-message-id`, `--to-recipients`, `--cc-recipients`, `--body-content`, `--subject`, `--body-content-type` | `POST /me/messages/{forward-message-id}/createForward (+ optional body-free PATCH for cc / subject)` |
+| `create-forward-draft` | Create an UNSENT forward draft of an existing message. POST /me/messages/{id}/createForward mints the draft (FW: subject, quoted original) with your comment placed above the quote and the recipients set, in one call. Redirects a thread to the right owner without leaving the CLI. The draft is saved in Drafts and can be reviewed, edited, and sent from any Outlook client; the CLI still cannot send. | `--forward-message-id`, `--to-recipients`, `--cc-recipients`, `--comment`, `--subject`, `--body-content-type` | `POST /me/messages/{forward-message-id}/createForward (+ optional body-free PATCH for cc / subject)` |
 | `create-mail-draft` | Create a new mail draft. POST /me/messages (or /me/mailFolders/{id}/messages when --mail-folder-id is set). The draft is saved in the Drafts folder (or the specified folder) and can be sent later via the Outlook client or Graph sendMail. Recipients are comma-separated email addresses. Returns a slim confirmation (id, subject, recipients, importance, bodyPreview, …) - NOT the body you just wrote; read the full draft back with get-mail-message if you need it. Use the returned id with update-mail-draft to modify before sending. | `--subject`, `--body-content`, `--body-content-type`, `--to-recipients`, `--cc-recipients`, `--bcc-recipients`, `--importance`, `--mail-folder-id` | `POST /me/messages (or /me/mailFolders/{mail-folder-id}/messages)` |
-| `create-reply-draft` | Create an UNSENT reply draft threaded on an existing message. POST /me/messages/{id}/createReplyAll mints the draft (inherited recipients, RE: subject, quoted history) with your reply text placed above the quote, in one call. Reply-all by default - dropping recipients is a deliberate act, so pass --reply-all false to reply to the sender only, which switches the action to createReply. The draft is saved in Drafts and can be reviewed, edited, and sent from any Outlook client; the CLI still cannot send. | `--reply-to-message-id`, `--body-content`, `--body-content-type`, `--subject`, `--reply-all` | `POST /me/messages/{reply-to-message-id}/createReplyAll, or /createReply when {reply-all} is false (+ optional body-free PATCH for subject)` |
+| `create-reply-draft` | Create an UNSENT reply draft threaded on an existing message. POST /me/messages/{id}/createReplyAll mints the draft (inherited recipients, RE: subject, quoted history) with your reply text placed above the quote, in one call. Reply-all by default - dropping recipients is a deliberate act, so pass --reply-all false to reply to the sender only, which switches the action to createReply. The draft is saved in Drafts and can be reviewed, edited, and sent from any Outlook client; the CLI still cannot send. | `--reply-to-message-id`, `--comment`, `--body-content-type`, `--subject`, `--reply-all` | `POST /me/messages/{reply-to-message-id}/createReplyAll, or /createReply when {reply-all} is false (+ optional body-free PATCH for subject)` |
 | `extract-mail-attachment-images` | Extract the embedded images from an Outlook mail attachment that is a pdf or a docx / xlsx / pptx (and their macro-enabled / template variants). OOXML reads the media parts directly (png/jpg/gif/bmp/tiff/webp/svg), including full-resolution / un-cropped originals and images on hidden slides; pdf walks every page via unpdf and re-encodes each painted image as PNG (page-oriented — not layer-hidden/unpainted/uncropped originals). fileAttachment decodes the inline bytes; referenceAttachment resolves via /shares/{token}/driveItem and fetches the content. Pair with the global output-dir flag to write every image to a folder; otherwise the bytes ride back base64-encoded. svg rides back as its XML source (which carries the diagram text labels); legacy vector (emf/wmf) and audio/video are skipped. itemAttachment and unsupported formats return a 415. | `--message-id`, `--attachment-id` | `GET /me/messages/{message-id}/attachments/{attachment-id}` |
 | `extract-sharepoint-links-in-mail` | Find every `*.sharepoint.com` URL in the body of a single Outlook email and resolve each one to its driveItem (driveId, itemId, name, webUrl) so the agent can feed those into `download-drive-item-as-pdf` / `-as-markdown` etc. Read-only — no conversion happens here. Capped at 25 unique URLs per call to bound fan-out (returns `truncated: true` and `skippedCount` when the body has more); duplicate URLs are deduplicated. Per-link errors are captured inside each entry instead of failing the whole call. | `--message-id` | `GET /me/messages/{message-id}` |
 | `find-mail-drafts` | Find existing drafts on a mail thread WITHOUT trusting a conversationId $filter. Reply and forward drafts do not always inherit the inbound message conversationId (a thread can split across several), and Graph $filter on the Drafts folder is not read-your-writes consistent, so filtering Drafts by conversationId misses drafts. This command instead scans the 50 most recently modified drafts and matches them client-side on a normalized subject (stripping RE:/FW: and localized reply/forward prefixes) plus, optionally, a shared recipient. Use it before create-reply-draft to avoid creating a duplicate: if a match comes back, revise it with update-mail-draft instead of making a new one. Read-only. | `--subject`, `--to-recipients` | `GET /me/mailFolders/drafts/messages?$top=50&$orderby=lastModifiedDateTime desc&$select=id,subject,toRecipients,ccRecipients,conversationId,lastModifiedDateTime,webLink (a read-only scan of the 50 most recently modified drafts; each is matched CLIENT-SIDE on a normalized {subject} and, when given, a shared {to-recipients} address, so neither value is sent to Graph)` |
@@ -148,7 +148,7 @@ For everything else:
 | `list-mail-attachments` | List the attachments (file, item, reference) on a single Outlook message. The CLI ships an opinionated default `--select=id,name,contentType,size,isInline` so an LLM that doesn't slim the response itself doesn't accidentally pull multi-MB `contentBytes` for every attachment (a single 1.5 MB image attachment would otherwise blow the context window). The `@odata.type` discriminator is always returned by Graph regardless of `$select` (and Graph rejects asking for it explicitly). To fetch the actual bytes, call `get-mail-attachment` for the one you need (or override `--select` if you really want the raw inline payload). | `--message-id`, `--top`, `--skip`, `--select`, `--filter`, `--orderby`, `--expand` | `GET /me/messages/{message-id}/attachments` |
 | `list-mail-child-folders` | List the subfolders of a single Outlook mail folder (e.g. subfolders of Inbox). | `--mail-folder-id`, `--top`, `--skip`, `--select`, `--filter`, `--orderby`, `--expand` | `GET /me/mailFolders/{mail-folder-id}/childFolders` |
 | `list-mail-folder-messages` | List the messages inside a specific Outlook mail folder (Inbox, custom folder, etc.). | `--mail-folder-id`, `--top`, `--skip`, `--select`, `--filter`, `--orderby`, `--expand` | `GET /me/mailFolders/{mail-folder-id}/messages` |
-| `list-mail-folder-messages-delta` | 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. | `--mail-folder-id`, `--top`, `--skip`, `--select`, `--filter`, `--orderby`, `--expand` | `GET /me/mailFolders/{mail-folder-id}/messages/delta()` |
+| `list-mail-folder-messages-delta` | 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`. | `--mail-folder-id`, `--top`, `--select`, `--filter`, `--expand` | `GET /me/mailFolders/{mail-folder-id}/messages/delta()` |
 | `list-mail-folders` | List the top-level mail folders in the signed-in user’s Outlook mailbox (Inbox, Sent Items, etc.). | `--top`, `--skip`, `--select`, `--filter`, `--orderby`, `--expand` | `GET /me/mailFolders` |
 | `list-mail-folders-delta` | Track incremental changes to the mail-folder tree itself (folders added / renamed / deleted). The first call returns the current snapshot plus a `@odata.deltaLink`; subsequent calls with that link return only what has changed. Companion to `list-mail-folder-messages-delta` which tracks message changes inside one folder. Note: Graph explicitly rejects `$top`, `$filter`, `$orderby`, and `$search` on this delta endpoint (`ErrorInvalidUrlQuery: not supported with change tracking over the 'Folders' resource`), so the OData passthrough is intentionally NOT exposed here. | _(none)_ | `GET /me/mailFolders/delta()` |
 | `list-mail-messages` | List the most recent messages from across the signed-in user's entire Outlook mailbox (every folder including Sent, Archive, Junk; default sort `receivedDateTime` desc). The CLI ships a slim default `--select=id,subject,from,toRecipients,ccRecipients,receivedDateTime,hasAttachments,isRead,importance,bodyPreview,conversationId` (`conversationId` groups messages into a thread and can be handed to `list-conversation-messages`) so a page of 25 messages stays ~30-60 KB instead of ~1 MB. Pass `--select id,subject,body` (or any other comma-separated field list) to override. Use `list-mail-folder-messages` to scope to a single folder such as Inbox. | `--top`, `--skip`, `--select`, `--filter`, `--orderby`, `--expand` | `GET /me/messages` |
@@ -159,7 +159,7 @@ For everything else:
 | `read-mail-attachment` | Read an Outlook mail attachment whatever it is — one command that auto-routes by file type, preferring the content-type when the filename extension is misleading (a real `.jpg` that is actually a spreadsheet still converts), so a caller never has to choose between the convert-mail-attachment-* siblings. A `.zip` fileAttachment is unpacked and every entry converted (mirrors `convert-mail-attachment-zip-to-markdown`, returning the `{ count, files }` envelope; legacy GBK/CP437 names decoded). Any other attachment — docx/xlsx/pptx/odt/ods/odp + macro/template variants → markdown, csv → table, pdf → text layer (with `pageCount`), legacy .xls/.doc extracted, an inner Outlook .msg rendered recursively (quoted chain stripped unless `--keep-quoted true`), plain text passed through, referenceAttachment resolved via `/shares`, and itemAttachment (embedded mail/event/contact) rendered — goes through the same dispatch as `convert-mail-attachment-to-markdown` (returning its `{ contentType, size, text }` envelope). Images, scanned/image-only PDFs, and legacy .ppt return an actionable 415 pointing at `convert-mail-attachment-to-pdf` + a vision model or `get-mail-attachment` for the raw bytes. Pass `--include-metadata true` to append Office side-channel metadata. Use the explicit `convert-mail-attachment-to-markdown` / `-to-pdf` / `-zip` siblings only when you need to force a specific output format. | `--message-id`, `--attachment-id`, `--include-metadata`, `--keep-quoted` | `GET /me/messages/{message-id}/attachments/{attachment-id}` |
 | `resolve-mail-link` | Parse a Microsoft Outlook web mail link (the URL emitted by the "Copy link" / address-bar share of an email) into its `messageId`. Pure transformation — no Graph call. Pipe the result into `get-mail-message` to fetch the body, or `convert-mail-to-markdown` to render it. For Outlook calendar links use `resolve-calendar-link` instead — this command rejects them with a pointer. | `--url` | `GET {url}` |
 | `search-mail-messages` | Search the signed-in user's entire Outlook mailbox using KQL or free text. Results are ranked by Graph relevance. The CLI ships a slim default `--select=id,subject,from,toRecipients,ccRecipients,receivedDateTime,hasAttachments,isRead,importance,bodyPreview,conversationId` (same as `list-mail-messages`; `conversationId` is included so you can group hits into a thread or feed one to `list-conversation-messages`) so a 3-result page stays ~3 KB instead of ~30 KB. Pass `--select id,subject,body` to widen, or override entirely. Note: Graph does not allow `$search` and `$filter` together — the CLI rejects `--filter` client-side with a pointer to `list-mail-messages` (which supports OData filtering). For sorting, server-side `$orderby` is also not allowed with `$search`; use the relevance ranking Graph returns. **Exact-phrase search works**: `--query '"budget allocation"'` and embedded field phrases like `--query 'subject:"Contoso A2 & B7 timeline"'` are supported — the CLI escapes your double quotes into KQL phrase quotes, wraps the whole expression in the `"…"` Graph requires, and percent-encodes the value so `&`, `#`, and `+` are wire-safe. Pass raw KQL otherwise, e.g. `--query 'subject:invoice from:alice'`. | `--query`, `--top`, `--skip`, `--select`, `--filter`, `--orderby`, `--expand` | `GET /me/messages?$search="{query}"` |
-| `update-mail-draft` | 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. | `--message-id`, `--subject`, `--body-content`, `--comment`, `--body-content-type`, `--to-recipients`, `--cc-recipients`, `--bcc-recipients`, `--importance` | `PATCH /me/messages/{message-id} (+ a GET of body,isDraft first when {comment} is used)` |
+| `update-mail-draft` | 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. | `--message-id`, `--subject`, `--body-content`, `--comment`, `--replace-quoted-history`, `--body-content-type`, `--to-recipients`, `--cc-recipients`, `--bcc-recipients`, `--importance` | `PATCH /me/messages/{message-id} (+ a GET of body,isDraft first when {comment} is used, or when {body-content} is used without {replace-quoted-history})` |
 
 ### Notes (OneNote)
 
@@ -175,7 +175,7 @@ For everything else:
 | `list-sharepoint-site-onenote-notebook-sections` | List sections inside one OneNote notebook attached to a SharePoint site. | `--site-id`, `--notebook-id`, `--top`, `--skip`, `--select`, `--filter`, `--orderby`, `--expand` | `GET /sites/{site-id}/onenote/notebooks/{notebook-id}/sections` |
 | `list-sharepoint-site-onenote-notebooks` | List OneNote notebooks attached to a SharePoint site (separate from the personal `list-onenote-notebooks` which targets `/me`). | `--site-id`, `--top`, `--skip`, `--select`, `--filter`, `--orderby`, `--expand` | `GET /sites/{site-id}/onenote/notebooks` |
 | `list-sharepoint-site-onenote-section-pages` | List pages inside one section of a SharePoint-site OneNote notebook. | `--site-id`, `--onenote-section-id`, `--top`, `--skip`, `--select`, `--filter`, `--orderby`, `--expand` | `GET /sites/{site-id}/onenote/sections/{onenote-section-id}/pages` |
-| `search-onenote-pages` | 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. | `--title-substring`, `--top`, `--skip`, `--select`, `--orderby`, `--expand` | `GET /me/onenote/pages?$filter=contains(title,'{title-substring}')` |
+| `search-onenote-pages` | 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. | `--query`, `--top`, `--skip`, `--select`, `--orderby`, `--expand` | `GET /me/onenote/pages?$filter=contains(title,'{query}')` |
 
 ### User
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ask-marcel-office-cli",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Microsoft Graph CLI + library \u2014 typed Bun/TypeScript wrapper around 150+ Graph operations (read + on-the-fly PDF/markdown conversion + federated Microsoft Search) reachable from a Teams browser-OAuth token.",
   "license": "MIT",
   "author": "Vincent Delacourt <vincent.delacourt@adama-development.com>",