ask-marcel-office-cli 2.3.0 → 2.4.0

package/dist/infra/auth.d.ts

@@ -39,7 +39,9 @@ type AuthManager = {
      * `logicalPermissions` allow-list. Falls through cache → re-capture
      * via headless Playwright. Used by the 3 historical-version commands.
      */
-    getElevatedAccessToken: () => Promise<Result<AccessToken, AuthError>>;
+    getElevatedAccessToken: (options?: {
+        readonly awaitSignIn?: boolean;
+    }) => Promise<Result<AccessToken, AuthError>>;
     /**
      * Returns a Graph token issued by a PARTNER tenant's authority, for a user
      * who is a guest there. Without it, every call against that tenant's
@@ -54,7 +56,9 @@ type AuthManager = {
      * through cache → re-capture via headless Playwright. Used by the
      * `list-teams-chats-with-messages` family of commands.
      */
-    getChatsvcaggAccessToken: () => Promise<Result<AccessToken, AuthError>>;
+    getChatsvcaggAccessToken: (options?: {
+        readonly ignoreCache?: boolean;
+    }) => Promise<Result<AccessToken, AuthError>>;
     /**
      * Returns the regional segment used to construct chatsvcagg substrate
      * URLs (`teams.microsoft.com/api/csa/<region>/api/...`). Captured at
@@ -71,7 +75,17 @@ type AuthManager = {
      * via headless Playwright. Used by `list-teams-chat-history` to walk
      * paginated chat-message history beyond the 200-message chatsvcagg cap.
      */
-    getIc3AccessToken: () => Promise<Result<AccessToken, AuthError>>;
+    getIc3AccessToken: (options?: {
+        readonly ignoreCache?: boolean;
+    }) => Promise<Result<AccessToken, AuthError>>;
+    /**
+     * Redeem the shared refresh token for any COLD substrate tier, over HTTP, with
+     * no browser on any path. `login` calls this so a warm-cache sign-in leaves all
+     * four tiers usable; without it the two substrate tiers stay cold until some
+     * Teams-chat command pays for them, and `login` reports them missing while
+     * having done nothing about it.
+     */
+    warmSubstrateTokens?: () => Promise<void>;
     logout: () => Promise<Result<void, AuthError>>;
     /**
      * Inspect the elevated-capture outcome from the most recent
@@ -95,6 +109,16 @@ type AuthManager = {
      * Optional: only the real manager implements it; a minimal fake omits it
      * and callers treat that as unavailable. Never captures or refreshes.
      */
+    /**
+     * The cached BASIC token, decoded by `scopes-check` and never acquired: no
+     * refresh, no browser. The acquiring getter heals a dead session by opening
+     * a browser and, when the persistent profile is already signed in, wiping it
+     * so the grant re-fires (2026-09-02: a diagnostic did exactly that). A stale
+     * token comes back as-is so its expiry can be reported; no cache at all is
+     * `undefined`. Optional: a bring-your-own-token manager omits it and callers
+     * fall back to `getAccessToken`, which is then the caller's own function.
+     */
+    getCachedBasicToken?: () => Promise<AccessToken | undefined>;
     getCachedElevatedInfo?: () => Promise<CachedTierInfo>;
     /**
      * Same decode-only preflight as `getCachedElevatedInfo`, for the chatsvcagg /
@@ -120,7 +144,8 @@ type SecondaryTokenCommands = {
     readonly chatsvcagg: ReadonlyArray<string>;
     readonly ic3: ReadonlyArray<string>;
 };
-declare const createAuthManagerFromApi: (browserAuth: BrowserAuth, cachePath: string, browserProfileDir: string, logger: Logger, fs: FileSystem, recaptureSecondaryViaBrowser?: boolean, secondaryTokenCommands?: SecondaryTokenCommands, acquireBasicViaBrowser?: boolean) => AuthManager;
+type FetchFn = (url: string, init?: RequestInit) => Promise<Response>;
+declare const createAuthManagerFromApi: (browserAuth: BrowserAuth, cachePath: string, browserProfileDir: string, logger: Logger, fs: FileSystem, recaptureSecondaryViaBrowser?: boolean, secondaryTokenCommands?: SecondaryTokenCommands, acquireBasicViaBrowser?: boolean, recaptureElevatedViaBrowser?: boolean, fetchFn?: FetchFn) => AuthManager;
 /**
  * Probe the token cache for a fresh access token. Handed to the browser
  * capture so its poll loop can short-circuit the multi-minute dance
@@ -138,6 +163,7 @@ declare const createAuthManager: (deps: {
     recaptureSecondaryViaBrowser?: boolean;
     secondaryTokenCommands?: SecondaryTokenCommands;
     acquireBasicViaBrowser?: boolean;
+    recaptureElevatedViaBrowser?: boolean;
 }) => AuthManager;
 export { createAuthManager, createAuthManagerFromApi, createFreshCachedTokenProbe, stderrProgress };
 export type { AuthError, AuthManager, CachedTierInfo, ElevatedOutcome, SecondaryTokenCommands };

package/dist/infra/browser-auth.d.ts

@@ -115,8 +115,16 @@ type BrowserAuth = {
      * cached elevated token expires and the Teams session is already in
      * the cache (no fresh sign-in needed). On `login`, use
      * `acquireBothTokens` instead so the user sees only one browser.
+     *
+     * `awaitSignIn` says a human asked for this and is watching, so the capture
+     * gets the interactive `pollDeadlineMs` rather than the short silent cap:
+     * long enough for a slow redirect chain, and long enough to fill in a
+     * sign-in form if one appears. Without it the short cap applies and the
+     * capture fails fast, which is what a background command needs.
      */
-    acquireElevatedToken: () => Promise<ElevatedTokenResult>;
+    acquireElevatedToken: (options?: {
+        readonly awaitSignIn?: boolean;
+    }) => Promise<ElevatedTokenResult>;
     /**
      * Capture a chatsvcagg-audience bearer (Teams basic identity, but the
      * `chatsvcagg.teams.microsoft.com` resource instead of Graph) by
@@ -223,6 +231,12 @@ type BrowserAuthConfig = {
     readonly initialSettleMs?: number;
     readonly postReloginSettleMs?: number;
     readonly pollIntervalMs?: number;
+    /**
+     * How long to keep listening for the PREFERRED elevated identity after an
+     * acceptable-but-weaker one has already been captured. See
+     * `PREFERRED_ELEVATED_APP_ID`.
+     */
+    readonly elevatedPreferenceGraceMs?: number;
     readonly pollDeadlineMs?: number;
     readonly navigationTimeoutMs?: number;
     /**
@@ -234,6 +248,12 @@ type BrowserAuthConfig = {
      * the LLM tool-call window. With a tight cap, the flow either yields
      * a token quickly or fails with `auth_failed: elevated token capture
      * timed out — run `ask-marcel-office login` to refresh.`
+     *
+     * The cap applies only when nobody is waiting. A caller passing
+     * `awaitSignIn` (today just `login`) gets `pollDeadlineMs` instead, because
+     * a silent capture that merely runs SLOW would otherwise fail here and send
+     * `login` into the forced dance, whose cookie wipe costs the 90-day sign-in
+     * session and guarantees the next run prompts.
      */
     readonly elevatedRecaptureTimeoutMs?: number;
     /**

package/dist/presenter/output-text.d.ts

@@ -1,2 +1,2 @@
-declare const renderTextOutput: (data: unknown) => string;
+declare const renderTextOutput: (data: unknown, tenantId?: string) => string;
 export { renderTextOutput };

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, SizeHintContext } from './render-to-string.js';
-declare const render: (data: unknown, logger: Logger, format: OutputFormat, context?: SizeHintContext) => void;
+import type { OutputFormat, RenderContext } from './render-to-string.js';
+declare const render: (data: unknown, logger: Logger, format: OutputFormat, context?: RenderContext) => 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

@@ -9,9 +9,10 @@ type OutputFormat = 'text' | 'json';
 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.
+ * use, and to render a follow-up command the caller can actually run. Built in
+ * composition (which owns the command manifest AND the invoked params); 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,
@@ -20,13 +21,20 @@ type RenderSurface = 'cli' | 'mcp';
  * banner named was a dead end there, and an agentic caller following it burned
  * a call to find out.
  */
-type SizeHintContext = {
+type RenderContext = {
     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;
+    /**
+     * The `--tenant-id` the call was made with, when it carried one. Unlike every
+     * field above it comes from the INVOCATION, not the manifest: a Graph cursor
+     * carries no tenant, so the footer is the only place the next call can learn
+     * which identity signed this page.
+     */
+    readonly tenantId?: string;
 };
 /**
  * Render a use-case success value to its final string, newline included.
@@ -36,7 +44,7 @@ type SizeHintContext = {
  * 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, context?: SizeHintContext) => string;
+declare const renderToString: (data: unknown, format: OutputFormat, context?: RenderContext) => 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
@@ -44,4 +52,4 @@ declare const renderToString: (data: unknown, format: OutputFormat, context?: Si
  */
 declare const renderErrorToString: (message: string, format: OutputFormat, errorCode?: string, explicitSource?: ErrorSource, retryAfterSeconds?: number) => string;
 export { renderErrorToString, renderToString };
-export type { OutputFormat, RenderSurface, SizeHintContext };
+export type { OutputFormat, RenderContext, RenderSurface };

package/dist/use-cases/commands/docx-metadata.d.ts

@@ -4,7 +4,9 @@ import type { CustomProp, ExternalRel } from './ooxml-metadata.js';
 /**
  * Pulls the side-channel content out of a .docx zip — every text-bearing
  * surface mammoth drops on the floor: core / app / custom doc properties,
- * people registry, external hyperlinks, comments, tracked changes (ins + del),
+ * people registry, external hyperlinks, comments, tracked changes (replacements,
+ * the insertions and deletions that pair with nothing, moves, and run /
+ * paragraph formatting changes),
  * hidden text (w:vanish), text-box / shape text (w:txbxContent), header/footer
  * body prose, field instructions (MERGEFIELD / HYPERLINK / DOCVARIABLE), bookmarks.
  *
@@ -36,6 +38,28 @@ type TrackedChange = {
     readonly date: string;
     readonly text: string;
 };
+type Replacement = {
+    readonly deletionId: string;
+    readonly insertionId: string;
+    readonly author: string;
+    readonly date: string;
+    readonly before: string;
+    readonly after: string;
+};
+type Move = {
+    readonly name: string;
+    readonly author: string;
+    readonly date: string;
+    readonly text: string;
+    readonly halves: 'both' | 'from-only' | 'to-only';
+};
+type FormatChange = {
+    readonly scope: 'run' | 'paragraph';
+    readonly author: string;
+    readonly date: string;
+    readonly text: string;
+    readonly properties: ReadonlyArray<string>;
+};
 type Field = {
     readonly source: string;
     readonly instruction: string;
@@ -57,6 +81,12 @@ type DocxMetadata = {
     readonly comments: ReadonlyArray<Comment>;
     readonly insertions: ReadonlyArray<TrackedChange>;
     readonly deletions: ReadonlyArray<TrackedChange>;
+    /** A deletion and the insertion beside it, reported as the one edit they are. */
+    readonly replacements: ReadonlyArray<Replacement>;
+    /** Text moved elsewhere, joined by the range name that brackets both halves. */
+    readonly moves: ReadonlyArray<Move>;
+    /** Run or paragraph properties changed under revision marking. */
+    readonly formatChanges: ReadonlyArray<FormatChange>;
     readonly hiddenText: ReadonlyArray<string>;
     readonly textBoxes: ReadonlyArray<string>;
     readonly headersFooters: ReadonlyArray<HeaderFooter>;
@@ -66,4 +96,4 @@ type DocxMetadata = {
 };
 declare const extractDocxMetadata: (bytes: Uint8Array) => Promise<Result<DocxMetadata, GraphError>>;
 export { extractDocxMetadata };
-export type { Bookmark, Comment, CustomProp, DocxMetadata, ExternalRel, Field, HeaderFooter, Person, TrackedChange };
+export type { Bookmark, Comment, CustomProp, DocxMetadata, ExternalRel, Field, FormatChange, HeaderFooter, Move, Person, Replacement, TrackedChange };

package/dist/use-cases/commands/include-hidden-folders.d.ts

@@ -0,0 +1,2 @@
+import type { CommandOptionMeta } from './command-types.js';
+export declare const INCLUDE_HIDDEN_FOLDERS_OPTION: CommandOptionMeta;

package/dist/use-cases/commands/list-shared-mailbox-child-folders.d.ts

@@ -0,0 +1,4 @@
+import type { CommandMeta } from './command-types.js';
+declare const execute: import("./command-types.js").CommandExecute, schema: import("./command-types.js").CommandSchema;
+declare const meta: CommandMeta;
+export { execute, meta, schema };

package/dist/use-cases/commands/list-shared-mailbox-folders.d.ts

@@ -0,0 +1,4 @@
+import type { CommandMeta } from './command-types.js';
+declare const execute: import("./command-types.js").CommandExecute, schema: import("./command-types.js").CommandSchema;
+declare const meta: CommandMeta;
+export { execute, meta, schema };

package/dist/use-cases/commands/login-status.d.ts

@@ -1,6 +1,8 @@
 type LoginSummary = {
     status: 'authenticated';
     available: ReadonlyArray<string>;
+    unlocked: Readonly<Record<string, string>>;
+    missing: Readonly<Record<string, string>>;
     hint: string;
 };
 type LoginSummaryInput = {

package/dist/use-cases/commands/login.d.ts

@@ -13,15 +13,25 @@ declare const schema: z.ZodObject<{}, z.core.$strict>;
  * loop with no exit: the command that needs elevated says "run login", login
  * says "authenticated", the command fails identically, forever.
  *
- * When elevated is confirmed missing we escalate through the SAME
- * `{ force: true }` rung the `--force` flag uses. That matters: the browser
- * adapter has its own `freshCachedToken` probe that short-circuits the dance
- * when a valid token is on disk, and only the forced path suppresses it — a
- * hand-rolled re-capture here would silently no-op (LESSONS 2026-07-13).
+ * When elevated is confirmed missing we try `getElevatedAccessToken` FIRST. It
+ * drives a silent SSO against the persistent browser profile and leaves cookies
+ * untouched, so the tenant's 90-day ESTSAUTHPERSISTENT session survives and the
+ * user sees a window flash rather than a sign-in page. The `{ force: true }`
+ * dance calls `context.clearCookies()` to make the OAuth grant re-fire for the
+ * BASIC token, and that wipe deletes ESTSAUTHPERSISTENT — which is why routing
+ * every elevated expiry through it produced a credential prompt each time, and
+ * then destroyed the very session the prompt had just established.
  *
- * Supersedes the 2026-07-13 decision that `login` is a slim confirmation and
- * `--force` the only re-capture mechanism: correct about the mechanism, but it
- * left the signpost pointing at a command that could not do the job.
+ * The silent route is not always available (expired profile cookies, a failed
+ * launch, a blocked navigation), so any failure falls back to the forced dance:
+ * it can prompt, but it polls for five minutes and a human can finish it.
+ *
+ * Supersedes the 2026-07-16 decision to escalate straight to `{ force: true }`.
+ * That entry feared a hand-rolled re-capture would no-op against the browser
+ * adapter's `freshCachedToken` probe; the probe lives in `acquireBothTokens`,
+ * not in `acquireElevatedToken`, and elevated freshness is decided upstream by
+ * `freshElevatedToken`. Verified live 2026-08-30: silent capture in 17s with no
+ * prompt, and the same call failing against a profile a forced login had wiped.
  */
 declare const execute: (auth: AuthManager, options?: {
     force?: boolean;

package/dist/use-cases/commands/next-page.d.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import type { Command, CommandMeta } from './command-types.js';
 declare const schema: z.ZodObject<{
+    tenantId: z.ZodOptional<z.ZodString>;
     url: z.ZodString;
 }, z.core.$strip>;
 declare const execute: Command['execute'];

package/dist/use-cases/commands/ooxml-xml-walker.d.ts

@@ -17,6 +17,7 @@
 type XmlObject = Record<string, unknown>;
 declare const parseXml: (xml: string | undefined) => unknown;
 declare const findAll: (root: unknown, tagName: string) => ReadonlyArray<XmlObject>;
+declare const findAllLocal: (root: unknown, localName: string) => ReadonlyArray<XmlObject>;
 declare const textOf: (node: unknown) => string;
 declare const attrOf: (node: XmlObject, name: string) => string;
 /**
@@ -26,11 +27,35 @@ declare const attrOf: (node: XmlObject, name: string) => string;
  * flattens every match into a single string for "the visible text of this run".
  */
 declare const findAllTexts: (root: unknown, tagName: string) => ReadonlyArray<string>;
+declare const collectText: (node: unknown, tagName: string) => string;
+declare const collectTextLocal: (node: unknown, localName: string) => string;
 /**
- * Concatenate the text content of every element matching `tagName` inside `node`,
- * regardless of nesting depth. Used to flatten a `<w:p>` (or `<w:ins>` / `<w:comment>`)
- * down to its visible text by gathering every `<w:t>` (or `<w:delText>`) descendant.
+ * One element in the `preserveOrder` shape: its tag name, and the node itself
+ * (whose `[tag]` holds the ordered children and whose `:@` holds attributes).
  */
-declare const collectText: (node: unknown, tagName: string) => string;
-export { attrOf, collectText, findAll, findAllTexts, parseXml, textOf };
-export type { XmlObject };
+type OrderedNode = {
+    readonly tag: string;
+    readonly node: XmlObject;
+};
+declare const parseXmlOrdered: (xml: string | undefined) => unknown;
+/**
+ * Every sibling list in the tree, each in document order, elements only.
+ *
+ * Sibling lists rather than one flat stream: adjacency only means anything
+ * WITHIN a parent. A deletion ending one paragraph and an insertion opening the
+ * next are consecutive in a flat walk and unrelated in the document.
+ */
+declare const orderedSiblingGroups: (root: unknown) => ReadonlyArray<ReadonlyArray<OrderedNode>>;
+/**
+ * Every element in true document order, pre-order (an element, then what it
+ * contains). Unlike `orderedSiblingGroups`, which reports a whole sibling level
+ * before descending, this is the order the start tags appear in the file, which
+ * is what reading flat range markers requires: `<w:moveFromRangeStart>` opens a
+ * span that a later element sits inside without being its child.
+ */
+declare const orderedElements: (root: unknown) => ReadonlyArray<OrderedNode>;
+declare const orderedAttrOf: (node: XmlObject, name: string) => string;
+/** The `collectText` of the ordered shape: flatten every `tagName` descendant to one string. */
+declare const collectOrderedText: (node: XmlObject, tagName: string) => string;
+export { attrOf, collectOrderedText, collectText, collectTextLocal, findAll, findAllLocal, findAllTexts, orderedAttrOf, orderedElements, orderedSiblingGroups, parseXml, parseXmlOrdered, textOf, };
+export type { OrderedNode, XmlObject };

package/dist/use-cases/commands/pptx-comments.d.ts

@@ -1,16 +1,19 @@
 import type { OoxmlZip } from '../../infra/ooxml-zip-adapter.js';
 /**
  * PowerPoint comments come in two formats: legacy (`ppt/commentAuthors.xml`
- * authors by integer id + `ppt/comments/comment*.xml` `<p:cm authorId dt>`
- * with `<p:text>` body) and modern (`ppt/authors.xml` authors by GUID +
- * `ppt/comments/*.xml` `<p188:cm authorId created>` with DrawingML `<a:t>`
- * body). Both are scanned; authors are resolved by id in either scheme.
- * Modern-comment support is best-effort against the p188 (2018/8) schema.
+ * authors by integer id + `ppt/comments/comment*.xml` `<cm authorId dt>` with a
+ * `<text>` body) and modern (`ppt/authors.xml` authors by GUID +
+ * `ppt/comments/*.xml` `<cm authorId created>` with a DrawingML `<t>` body).
+ * Elements are matched by local name, so the prefixes a writer happens to bind
+ * (`p:` / `p188:` / `a:` from PowerPoint, anything else from a third-party tool)
+ * never decide whether a comment is found. Both generations share the local name
+ * `cm`, so one pass reads them all; authors are resolved by id in either scheme.
  */
 type CommentAuthor = {
     readonly id: string;
     readonly name: string;
     readonly initials: string;
+    readonly email: string;
 };
 type PptxComment = {
     readonly author: string;

package/dist/use-cases/commands/token-tier-capability.d.ts

@@ -0,0 +1,5 @@
+declare const TIER_CAPABILITY: Readonly<Record<string, string>>;
+declare const OPTIONAL_TIERS: readonly ["elevated", "chatsvcagg", "ic3"];
+type OptionalTier = (typeof OPTIONAL_TIERS)[number];
+export { OPTIONAL_TIERS, TIER_CAPABILITY };
+export type { OptionalTier };

package/docs/COMMANDS.md

@@ -1,6 +1,6 @@
 # Command reference
 
-All 184 commands across 11 categories, grouped by category. Each row shows the command name, a one-line summary, the required parameters, and the underlying Microsoft Graph endpoint. The six lifecycle commands (`login`, `logout`, `update`, `docs`, `help-json`, `mcp`) are listed separately in the **Authentication & lifecycle** section below — `help-json` counts them in its manifest total (190), so a 184-vs-190 gap is those six, not a drift.
+All 186 commands across 11 categories, grouped by category. Each row shows the command name, a one-line summary, the required parameters, and the underlying Microsoft Graph endpoint. The six lifecycle commands (`login`, `logout`, `update`, `docs`, `help-json`, `mcp`) are listed separately in the **Authentication & lifecycle** section below — `help-json` counts them in its manifest total (192), so a 186-vs-192 gap is those six, not a drift.
 
 The auto-generated tables below are rebuilt from the live command registry on every `bun run docs:gen` / `bun run build` — they cannot drift from the actual surface.
 
@@ -146,15 +146,17 @@ For everything else:
 | `list-group-conversations` | List conversations in a unified (Microsoft 365) group inbox. Each conversation aggregates one or more threads. Only Microsoft 365 groups have a mailbox — security and distribution groups return `MailboxNotEnabledForRESTAPI`. Verify the group is unified before calling. | `--group-id`, `--top`, `--skip`, `--select`, `--filter`, `--orderby`, `--expand` | `GET /groups/{group-id}/conversations` |
 | `list-group-threads` | List threads in a unified (Microsoft 365) group inbox. Threads are flatter than conversations — one per topic, useful when conversation-level grouping isn't needed. Only Microsoft 365 groups have a mailbox — security and distribution groups return `MailboxNotEnabledForRESTAPI`. | `--group-id`, `--top`, `--skip`, `--select`, `--filter`, `--orderby`, `--expand` | `GET /groups/{group-id}/threads` |
 | `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-child-folders` | List the subfolders of a single Outlook mail folder (e.g. subfolders of Inbox). | `--mail-folder-id`, `--include-hidden-folders`, `--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. `--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` | List the top-level mail folders in the signed-in user’s Outlook mailbox (Inbox, Sent Items, etc.). | `--include-hidden-folders`, `--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` |
 | `list-mail-rules` | List the message rules on the Outlook Inbox. Microsoft Graph only supports message rules on the Inbox folder; passing any other folder ID (drafts, sentitems, archive, a custom folder) returns `MailFolderNotSupportedError` from Graph. `--mail-folder-id` defaults to `inbox` because that is the only value Graph accepts; the flag is kept (optional) for callers that want to pass a resolved Inbox ID explicitly. Note: Graph silently ignores every OData passthrough on this endpoint, so the CLI does NOT expose them — the full rule set is always returned. | `--mail-folder-id` | `GET /me/mailFolders/{mail-folder-id}/messageRules` |
 | `list-outlook-categories` | List the signed-in user's Outlook color categories — the named tags that can be applied to mail, calendar items, and contacts. Each entry has `displayName` and a `color` from Outlook's preset palette. Note: Graph silently ignores every OData passthrough on this endpoint (`$top`, `$skip`, `$select`, `$filter`, `$orderby`, `$expand`), so the CLI does not expose any of those flags — the full collection is always returned. Slice client-side. | _(none)_ | `GET /me/outlook/masterCategories` |
+| `list-shared-mailbox-child-folders` | 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. | `--user-id`, `--mail-folder-id`, `--include-hidden-folders`, `--top`, `--skip`, `--select`, `--filter`, `--orderby`, `--expand` | `GET /users/{user-id}/mailFolders/{mail-folder-id}/childFolders` |
 | `list-shared-mailbox-folder-messages` | List messages in a single folder of a shared / delegated mailbox. | `--user-id`, `--mail-folder-id`, `--top`, `--skip`, `--select`, `--filter`, `--orderby`, `--expand` | `GET /users/{user-id}/mailFolders/{mail-folder-id}/messages` |
+| `list-shared-mailbox-folders` | 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. | `--user-id`, `--include-hidden-folders`, `--top`, `--skip`, `--select`, `--filter`, `--orderby`, `--expand` | `GET /users/{user-id}/mailFolders` |
 | `list-shared-mailbox-messages` | 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. | `--user-id`, `--top`, `--skip`, `--select`, `--filter`, `--orderby`, `--expand` | `GET /users/{user-id}/messages` |
 | `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}` |
@@ -186,7 +188,7 @@ For everything else:
 | `get-my-manager` | Return the signed-in user's manager (a single `user` resource). When no manager is set in the directory, Graph returns 404 `Request_ResourceNotFound`; this command maps that one specific 404 to `{ ok: true, data: { manager: null, note: '...' } }` so an LLM can distinguish 'no manager' from a permission failure without parsing prose. Use `--select` to slim the response (e.g. `--select id,displayName,mail`). | `--select`, `--expand` | `GET /me/manager` |
 | `get-my-profile-photo` | Download the signed-in user's profile photo (largest available size), inlined. The CLI follows the Graph 302 → CDN redirect internally so the LLM never has to fetch an external URL. | _(none)_ | `GET /me/photo/$value` |
 | `get-organization` | Return the tenant's organization metadata — display name, country, verified domains, business phones, technical / security notification contacts, assigned Microsoft 365 SKUs / licensing. Graph wraps the single organization resource under `value[]` (— even though only one tenant exists, the endpoint returns a collection). The full resource is ~57 KB; use `--select` to slim it (e.g. `--select id,displayName,verifiedDomains`). | `--select`, `--expand` | `GET /organization` |
-| `get-user` | 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. | `--user-id`, `--select`, `--expand` | `GET /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)` |
+| `get-user` | 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. | `--user-id`, `--select`, `--expand` | `GET /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)` |
 | `get-user-manager` | Return a specific user's manager (a single `user` resource). When the user has no manager set in the directory, Graph returns 404 `Request_ResourceNotFound`; this command maps that one specific 404 to `{ ok: true, data: { manager: null, note: '...' } }` (same shape as `get-my-manager`) so an LLM can distinguish 'no manager' from 'unknown user' with a single discriminator across both commands. Use `--select` to slim the response. | `--user-id`, `--select`, `--expand` | `GET /users/{user-id}/manager` |
 | `list-group-members` | List members of an Azure AD / Microsoft 365 group. Returns users, groups, and other directoryObjects depending on the group's membership. | `--group-id`, `--top`, `--skip`, `--select`, `--filter`, `--orderby`, `--expand` | `GET /groups/{group-id}/members` |
 | `list-group-owners` | List the owners of an Azure AD / Microsoft 365 group. | `--group-id`, `--top`, `--skip`, `--select`, `--filter`, `--orderby`, `--expand` | `GET /groups/{group-id}/owners` |
@@ -261,7 +263,7 @@ For everything else:
 | `extract-local-file-images` | Extract the embedded images from a file ON DISK — the local sibling of `extract-drive-item-images`, and like `convert-local-file-to-markdown` it never calls Microsoft Graph (works offline, no login). Same per-extension dispatch: docx / xlsx / pptx (and their macro-enabled / template variants) have their OOXML media parts read directly (png/jpg/gif/bmp/tiff/webp/svg — full-resolution originals, including images on hidden slides); a pdf is walked page by page via unpdf with each painted image re-encoded as PNG. Two flows only this command completes: a Graph-rendered PDF saved locally (legacy `.ppt` → `download-drive-item-as-pdf` with the global output-path flag → this command pulls the slide images for OCR), and Office files unpacked from a local archive. Pair with the global output-dir flag to write every image to a folder; otherwise the bytes ride back base64-encoded. Any other extension returns a 415 naming the local ways out. | `--path` | `GET (local) reads {path} from the local filesystem; not a Graph endpoint` |
 | `microsoft-search-query` | Run a federated KQL search across the signed-in user's mail, files, list items, sites, calendar events, and people. Microsoft Graph v1.0 rejects multi-entity search bodies on most tenants (`Multiple entity search is not supported in v1.0`), so this command issues SIX parallel POSTs — one per entityType — and merges the per-entity `searchHits` containers into a single `value[]`. Each container is identifiable by the resource type inside `hits[].resource`. If a sub-request fails (e.g. tenant lacks the scope for one entity), the others still return; failures show up in `partialErrors[]`. Page size is fixed at 25 per sub-request and `top` is NOT exposed (Graph rejects $top in /search/query bodies). `chatMessage` is excluded since `Chat.Read*` is unavailable. To find Microsoft Loop pages (`.loop`) for markdown conversion, query `filetype:loop`: each `driveItem` hit carries `resource.id` plus `resource.parentReference.driveId`, the exact pair `download-drive-item-as-markdown` needs to render the page via Graph `?format=html`. (`filetype:fluid` returns nothing on this corpus; Loop pages index as `.loop`.) | `--query` | `POST /search/query` |
 | `my-quick-context` | One-shot discovery for the IDs every other command needs, plus the user's job title and tenant timezone / locale / working-hours. Issues 9 Graph calls in parallel and returns what each succeeded for. Partial-result mode: only `/me` is load-bearing — if any other sub-call fails (missing license, scope, or tenant policy) the corresponding field is `undefined` but the rest are still returned. Replaces the audit's 5-call discovery chain — feed the IDs straight into `list-mail-folder-messages`, `list-folder-files`, `list-planner-tasks`, `list-onenote-notebook-sections`, etc. For Microsoft To Do lists call `list-todo-task-lists` on demand (intentionally dropped from this command's fan-out — the array of {id, displayName, wellknownListName} entries crowded the envelope with IDs an LLM rarely needs on first contact). `tenantTimeZone` lets an LLM stop treating every datetime as UTC on first contact. | _(none)_ | `GET (meta) parallel: /me, /me/drive, /me/mailFolders/inbox, /me/calendar, /me/planner/plans, /me/onenote/notebooks, /me/joinedTeams, /me/drive/recent, /me/mailboxSettings` |
-| `next-page` | 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. | `--url` | `GET {url}` |
-| `scopes-check` | 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. | _(none)_ | `GET (meta) cached-token introspection — no Graph endpoint` |
+| `next-page` | 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`. | `--url`, `--tenant-id` | `GET {url}` |
+| `scopes-check` | 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. | _(none)_ | `GET (meta) cached-token introspection — no Graph endpoint` |
 
 <!-- AUTO-GENERATED-COMMANDS:END -->

package/docs/USAGE.md

@@ -18,7 +18,7 @@ bun add -g ask-marcel-office-cli
 ask-marcel-office login
 
 # the rest is discoverable
-ask-marcel-office --help                                # ~38 KB, one-sentence summaries
+ask-marcel-office --help                                # ~34 KB, one-sentence summaries
 ask-marcel-office help-json --terse --category mail     # ~6 KB JSON for one category
 ask-marcel-office docs list-mail-messages               # full per-command Markdown
 ```
@@ -306,7 +306,7 @@ Environment variables read at composition time:
 ## Quality gates (atelier four-check loop)
 
 ```bash
-bun test           # full suite (4800+ tests)
+bun test           # full suite (4,700+ tests)
 bun run lint       # ESLint (0 warnings, 0 errors)
 bun run typecheck  # tsc --noEmit
 bun run coverage   # per-tier gates (100% on every tier: domain, use-cases, infra, composition, presenter)

package/package.json

@@ -1,17 +1,17 @@
 {
   "name": "ask-marcel-office-cli",
-  "version": "2.3.0",
+  "version": "2.4.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>",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/vdelacou/ask-marcel-office-cli.git"
+    "url": "git+https://github.com/ask-marcel/ask-marcel-office-cli.git"
   },
   "bugs": {
-    "url": "https://github.com/vdelacou/ask-marcel-office-cli/issues"
+    "url": "https://github.com/ask-marcel/ask-marcel-office-cli/issues"
   },
-  "homepage": "https://github.com/vdelacou/ask-marcel-office-cli#readme",
+  "homepage": "https://github.com/ask-marcel/ask-marcel-office-cli#readme",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -44,19 +44,35 @@
   },
   "keywords": [
     "microsoft-graph",
+    "microsoft-365",
     "office-365",
+    "m365",
     "cli",
-    "bun",
-    "typescript",
-    "graph-api",
+    "mcp",
+    "mcp-server",
+    "llm",
+    "ai-agent",
+    "ai-agents",
+    "claude",
+    "claude-code",
+    "cursor",
+    "markdown",
     "outlook",
     "teams",
     "onedrive",
-    "sharepoint"
+    "sharepoint",
+    "calendar",
+    "excel",
+    "onenote",
+    "planner",
+    "graph-api",
+    "typescript",
+    "bun"
   ],
   "scripts": {
     "start": "bun run src/main.ts",
     "lint": "eslint --cache --max-warnings=0",
+    "lint:staged": "bash scripts/lint-staged.sh",
     "lint:strict": "LINT_STRICT=1 eslint --max-warnings=0",
     "typecheck": "bun --bun x tsc --noEmit",
     "coverage": "bun run scripts/check-coverage.ts",
@@ -99,7 +115,7 @@
     "update-notifier": "^7.3.1",
     "winston": "^3.19.0",
     "word-extractor": "^1.0.4",
-    "xlsx": "^0.18.5",
+    "xlsx": "https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz",
     "zod": "^4.3.6"
   }
 }