ask-marcel-office-cli 2.3.0 → 2.5.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/convert-group-post-attachment-to-markdown.d.ts

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+import type { Result } from '../../domain/result.js';
+import type { GraphClient, GraphError } from '../../infra/graph-client.js';
+import type { CommandMeta } from './command-types.js';
+declare const schema: z.ZodObject<{
+    groupId: z.ZodString;
+    threadId: z.ZodString;
+    postId: z.ZodString;
+    attachmentId: z.ZodString;
+    includeMetadata: z.ZodOptional<z.ZodEnum<{
+        true: "true";
+        false: "false";
+    }>>;
+    keepQuoted: z.ZodOptional<z.ZodEnum<{
+        true: "true";
+        false: "false";
+    }>>;
+}, z.core.$strip>;
+declare const execute: (graph: GraphClient, params: Record<string, string>) => Promise<Result<unknown, GraphError>>;
+declare const meta: CommandMeta;
+export { execute, meta, schema };

package/dist/use-cases/commands/convert-group-post-to-markdown.d.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+import type { Result } from '../../domain/result.js';
+import type { GraphClient, GraphError } from '../../infra/graph-client.js';
+import type { CommandMeta } from './command-types.js';
+declare const schema: z.ZodObject<{
+    groupId: z.ZodString;
+    threadId: z.ZodString;
+    postId: z.ZodString;
+    inlineImages: z.ZodOptional<z.ZodEnum<{
+        true: "true";
+        false: "false";
+    }>>;
+    keepQuoted: z.ZodOptional<z.ZodEnum<{
+        true: "true";
+        false: "false";
+    }>>;
+}, z.core.$strip>;
+declare const execute: (graph: GraphClient, params: Record<string, string>) => Promise<Result<unknown, GraphError>>;
+declare const meta: CommandMeta;
+export { execute, meta, schema };

package/dist/use-cases/commands/convert-mail-attachment-to-markdown.d.ts

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import type { Result } from '../../domain/result.js';
 import type { GraphClient, GraphError } from '../../infra/graph-client.js';
 import type { CommandMeta } from './command-types.js';
+import type { ConversionHints } from './markdown-dispatch.js';
 declare const schema: z.ZodObject<{
     messageId: z.ZodString;
     attachmentId: z.ZodString;
@@ -18,8 +19,10 @@ type ConvertOptions = {
     readonly includeMetadata: boolean;
     readonly keepQuoted: boolean;
 };
-declare const convertFetchedAttachment: (graph: GraphClient, a: Record<string, unknown>, opts: ConvertOptions) => Promise<Result<unknown, GraphError>> | Result<unknown, GraphError>;
-declare const convertAttachmentToMarkdown: (graph: GraphClient, attachmentPath: string, opts: ConvertOptions) => Promise<Result<unknown, GraphError>>;
+declare const MAIL_HINTS: ConversionHints;
+declare const convertFetchedAttachment: (graph: GraphClient, a: Record<string, unknown>, opts: ConvertOptions, hints: ConversionHints) => Promise<Result<unknown, GraphError>> | Result<unknown, GraphError>;
+declare const convertAttachmentToMarkdown: (graph: GraphClient, attachmentPath: string, opts: ConvertOptions, hints: ConversionHints) => Promise<Result<unknown, GraphError>>;
 declare const execute: (graph: GraphClient, params: Record<string, string>) => Promise<Result<unknown, GraphError>>;
 declare const meta: CommandMeta;
-export { convertAttachmentToMarkdown, convertFetchedAttachment, execute, meta, schema };
+export { convertAttachmentToMarkdown, convertFetchedAttachment, execute, MAIL_HINTS, meta, schema };
+export type { ConvertOptions };

package/dist/use-cases/commands/convert-mail-to-markdown.d.ts

@@ -15,6 +15,30 @@ declare const schema: z.ZodObject<{
     }>>;
 }, z.core.$strip>;
 declare const ATTACHMENT_METADATA_SELECT = "$select=id,name,contentType,size,isInline,microsoft.graph.fileAttachment/contentId";
+declare const nonEmpty: (v: unknown) => v is string;
+type Recipient = {
+    readonly emailAddress?: {
+        readonly name?: string;
+        readonly address?: string;
+    };
+};
+type MailLikeResource = {
+    readonly subject?: string;
+    readonly from?: Recipient;
+    readonly sender?: Recipient;
+    readonly toRecipients?: ReadonlyArray<Recipient>;
+    readonly ccRecipients?: ReadonlyArray<Recipient>;
+    readonly receivedDateTime?: string;
+    readonly body?: {
+        readonly contentType?: string;
+        readonly content?: string;
+    };
+    readonly hasAttachments?: boolean;
+};
+declare const formatAddress: (a: {
+    readonly name?: string;
+    readonly address?: string;
+} | undefined) => string | undefined;
 declare const attachmentMetaSchema: z.ZodObject<{
     id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -45,8 +69,16 @@ type EmbedFetchResult = {
     readonly inline?: InlineAttachment;
     readonly oversize: boolean;
 };
-declare const fetchInlineImageBytes: (graph: GraphClient, messageId: string, meta: InlineImageCandidate) => Promise<EmbedFetchResult>;
+declare const fetchInlineImageBytes: (graph: GraphClient, resourcePath: string, meta: InlineImageCandidate) => Promise<EmbedFetchResult>;
+type MarkdownRenderOptions = {
+    readonly inlineImages: boolean;
+    readonly keepQuoted: boolean;
+    /** Closing line of the attachments list, naming the command that fetches their bytes. */
+    readonly attachmentHint: string;
+    readonly renderHeaders: (m: MailLikeResource) => string;
+};
+declare const renderMessageAsMarkdown: (graph: GraphClient, resourcePath: string, options: MarkdownRenderOptions) => Promise<Result<unknown, GraphError>>;
 declare const execute: (graph: GraphClient, params: Record<string, string>) => Promise<Result<unknown, GraphError>>;
 declare const meta: CommandMeta;
-export { ATTACHMENT_METADATA_SELECT, attachmentsListSchema, execute, fetchInlineImageBytes, formatBytes, isInlineImage, meta, schema };
-export type { AttachmentMeta, InlineImageCandidate };
+export { ATTACHMENT_METADATA_SELECT, attachmentsListSchema, execute, fetchInlineImageBytes, formatAddress, formatBytes, isInlineImage, meta, nonEmpty, renderMessageAsMarkdown, schema, };
+export type { AttachmentMeta, InlineImageCandidate, MailLikeResource, MarkdownRenderOptions };

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, table, row and cell 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,29 @@ 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 FormatChangeScope = 'run' | 'paragraph' | 'table' | 'row' | 'cell';
+type FormatChange = {
+    readonly scope: FormatChangeScope;
+    readonly author: string;
+    readonly date: string;
+    readonly text: string;
+    readonly properties: ReadonlyArray<string>;
+};
 type Field = {
     readonly source: string;
     readonly instruction: string;
@@ -57,6 +82,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, paragraph, table, row or cell properties changed under revision marking. */
+    readonly formatChanges: ReadonlyArray<FormatChange>;
     readonly hiddenText: ReadonlyArray<string>;
     readonly textBoxes: ReadonlyArray<string>;
     readonly headersFooters: ReadonlyArray<HeaderFooter>;
@@ -66,4 +97,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/get-group-post-attachment.d.ts

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+import type { Command, CommandMeta } from './command-types.js';
+declare const schema: z.ZodObject<{
+    groupId: z.ZodString;
+    threadId: z.ZodString;
+    postId: z.ZodString;
+    attachmentId: z.ZodString;
+    select: 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/get-group-post.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/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-group-post-attachments.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-group-thread-posts.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-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 };