ask-marcel-office-cli 1.0.0 → 1.5.0

package/dist/presenter/error-hints.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Translate Graph / substrate / CLI / validation errors into actionable hints.
+ *
+ * Audit Jane-session §2: bare `error: ErrorInvalidIdMalformed: Id is
+ * malformed.` had no remedy for the LLM — it had to guess where the bad ID
+ * came from. This module is the centralised "what should I do about this"
+ * lookup: pattern-match the error code (or, as a fallback, a substring of
+ * the message) and surface a one-line hint plus a `source` classifier so
+ * the LLM can branch on whether the failure is server-side, substrate-side,
+ * CLI-side, or a Zod validation rejection. Surfaced through the standard
+ * error envelope in both `--output json` (as `hint` / `source` fields) and
+ * `--output text` (as `hint:` / `source:` lines under the existing `error:`
+ * line).
+ *
+ * Audit Jane-session §2 follow-up: the four error-envelope variants are
+ *   - `graph`      — public Microsoft Graph API at /v1.0/
+ *   - `substrate`  — Microsoft-internal chat substrates (chatsvcagg / IC3).
+ *                    Tagged at the infra layer with `substrateHttp{N}_{name}`.
+ *   - `cli`        — CLI itself (Commander parser, CLI rewrites of Graph
+ *                    errors via `cli_rewrite_*` and `cli_reject_*` codes)
+ *   - `validation` — Zod schema validation from use-cases (no `code` — pure
+ *                    message-pattern fallback)
+ *
+ * Rule precedence: specific code matchers run FIRST, then message-pattern
+ * fallbacks. The generic-validation rule sits LAST so it never overrides a
+ * code-based remedy.
+ *
+ * The table is intentionally small and biased toward HIGH-FREQUENCY errors
+ * an LLM actually hits. Adding more entries is cheap; the lookup is O(n)
+ * on a tiny n.
+ */
+export type ErrorSource = 'graph' | 'substrate' | 'cli' | 'validation';
+export type ErrorHint = {
+    readonly hint: string;
+    readonly source: ErrorSource;
+};
+/**
+ * First matching rule wins. Returns `undefined` when nothing in the table
+ * matches — caller renders the bare error (the historical shape).
+ */
+export declare const findErrorHint: (message: string, code: string | undefined) => ErrorHint | undefined;

package/dist/presenter/output.d.ts

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

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

@@ -1,10 +1,23 @@
 import type { z } from 'zod';
 import type { Command } from './command-types.js';
 import { type ODataKey } from './odata-query.js';
+/**
+ * Options accepted by every builder that knows about `$select` (i.e. every
+ * builder except `buildCommand` / `buildElevatedCommand`, which take no OData
+ * passthroughs at all). `defaultSelect`, when set and the user did NOT pass
+ * `--select`, is injected into the OData query string so default invocations
+ * return a slim projection instead of a 50 KB resource. User-supplied
+ * `--select` always wins. Audit Jane-session §A: pairs the `list-mail-attachments`
+ * pattern with the builder layer so the 6 heaviest endpoints stop returning
+ * the full Graph resource by default.
+ */
+type SelectDefaults = {
+    readonly defaultSelect?: string;
+};
 declare const buildCommand: (pathFn: (params: Record<string, string>) => string, schema: z.ZodType) => Pick<Command, "schema" | "execute">;
 declare const buildElevatedCommand: (pathFn: (params: Record<string, string>) => string, schema: z.ZodType) => Pick<Command, "schema" | "execute">;
-declare const buildListCommand: <Shape extends z.ZodRawShape>(pathFn: (params: z.infer<z.ZodObject<Shape>>) => string, schema: z.ZodObject<Shape>) => Pick<Command, "schema" | "execute">;
-declare const buildElevatedListCommand: <Shape extends z.ZodRawShape>(pathFn: (params: z.infer<z.ZodObject<Shape>>) => string, schema: z.ZodObject<Shape>) => Pick<Command, "schema" | "execute">;
+declare const buildListCommand: <Shape extends z.ZodRawShape>(pathFn: (params: z.infer<z.ZodObject<Shape>>) => string, schema: z.ZodObject<Shape>, options?: SelectDefaults) => Pick<Command, "schema" | "execute">;
+declare const buildElevatedListCommand: <Shape extends z.ZodRawShape>(pathFn: (params: z.infer<z.ZodObject<Shape>>) => string, schema: z.ZodObject<Shape>, options?: SelectDefaults) => Pick<Command, "schema" | "execute">;
 /**
  * Single-resource GET that supports the OData `$select` and `$expand` query
  * parameters. Mirrors `buildListCommand` but exposes only the two flags that
@@ -13,14 +26,23 @@ declare const buildElevatedListCommand: <Shape extends z.ZodRawShape>(pathFn: (p
  * the fields it needs (e.g. `--select id,subject`) instead of swallowing a
  * 50 KB resource just to read a subject line.
  */
-declare const buildSelectableCommand: <Shape extends z.ZodRawShape>(pathFn: (params: z.infer<z.ZodObject<Shape>>) => string, schema: z.ZodObject<Shape>) => Pick<Command, "schema" | "execute">;
+declare const buildSelectableCommand: <Shape extends z.ZodRawShape>(pathFn: (params: z.infer<z.ZodObject<Shape>>) => string, schema: z.ZodObject<Shape>, options?: SelectDefaults) => Pick<Command, "schema" | "execute">;
+/**
+ * Elevated-token twin of `buildSelectableCommand`. Use for single-resource
+ * GETs on endpoints that require the M365ChatClient identity (e.g. `/chats/{id}`)
+ * AND benefit from `$select`/`$expand` projection. The basic `buildElevatedCommand`
+ * builder takes no OData passthroughs — use this when the endpoint honours
+ * field projection, so an LLM can avoid pulling the whole resource just to
+ * read a topic or chatType.
+ */
+declare const buildElevatedSelectableCommand: <Shape extends z.ZodRawShape>(pathFn: (params: z.infer<z.ZodObject<Shape>>) => string, schema: z.ZodObject<Shape>, options?: SelectDefaults) => Pick<Command, "schema" | "execute">;
 /**
  * Collection GET that supports ONLY `$filter` and `$select` — for endpoints
  * Microsoft documents as rejecting the other OData passthroughs (`/teams/{id}/channels`
  * is the canonical case: Graph returns BadRequest on `$top`, `$skip`, `$orderby`,
  * `$expand`). Advertising the unsupported flags would be a usability lie.
  */
-declare const buildFilterSelectListCommand: <Shape extends z.ZodRawShape>(pathFn: (params: z.infer<z.ZodObject<Shape>>) => string, schema: z.ZodObject<Shape>) => Pick<Command, "schema" | "execute">;
+declare const buildFilterSelectListCommand: <Shape extends z.ZodRawShape>(pathFn: (params: z.infer<z.ZodObject<Shape>>) => string, schema: z.ZodObject<Shape>, options?: SelectDefaults) => Pick<Command, "schema" | "execute">;
 /**
  * Collection GET on an endpoint that supports the usual OData passthroughs
  * EXCEPT `$skip` (e.g. `/me/drive/recent`, `/sites/{id}/lists`,
@@ -28,7 +50,7 @@ declare const buildFilterSelectListCommand: <Shape extends z.ZodRawShape>(pathFn
  * `invalidRequest: $skip is not supported on this API.`; the CLI mirrors
  * by dropping `--skip` from the advertised flag set.
  */
-declare const buildNoSkipListCommand: <Shape extends z.ZodRawShape>(pathFn: (params: z.infer<z.ZodObject<Shape>>) => string, schema: z.ZodObject<Shape>) => Pick<Command, "schema" | "execute">;
+declare const buildNoSkipListCommand: <Shape extends z.ZodRawShape>(pathFn: (params: z.infer<z.ZodObject<Shape>>) => string, schema: z.ZodObject<Shape>, options?: SelectDefaults) => Pick<Command, "schema" | "execute">;
 /**
  * Collection GET that supports an EXPLICIT subset of OData passthroughs.
  * Use for endpoints where Graph silently drops some flags — passing
@@ -37,12 +59,12 @@ declare const buildNoSkipListCommand: <Shape extends z.ZodRawShape>(pathFn: (par
  * (`buildNoSkipListCommand`, `buildFilterSelectListCommand`) are
  * specializations; this is the generic escape hatch.
  */
-declare const buildPickODataListCommand: <Shape extends z.ZodRawShape, K extends ODataKey>(pathFn: (params: z.infer<z.ZodObject<Shape>>) => string, schema: z.ZodObject<Shape>, keys: ReadonlyArray<K>) => Pick<Command, "schema" | "execute">;
+declare const buildPickODataListCommand: <Shape extends z.ZodRawShape, K extends ODataKey>(pathFn: (params: z.infer<z.ZodObject<Shape>>) => string, schema: z.ZodObject<Shape>, keys: ReadonlyArray<K>, options?: SelectDefaults) => Pick<Command, "schema" | "execute">;
 /**
  * Elevated-token twin of `buildPickODataListCommand`. Use for endpoints that
  * require the M365ChatClient identity (e.g. `/me/chats`, `/chats/{}/members`)
  * AND honour only a subset of OData passthroughs — the chats family rejects
  * `$orderby` / `$expand` with `BadRequest`, so the picker is the right tool.
  */
-declare const buildElevatedPickODataListCommand: <Shape extends z.ZodRawShape, K extends ODataKey>(pathFn: (params: z.infer<z.ZodObject<Shape>>) => string, schema: z.ZodObject<Shape>, keys: ReadonlyArray<K>) => Pick<Command, "schema" | "execute">;
-export { buildCommand, buildElevatedCommand, buildElevatedListCommand, buildElevatedPickODataListCommand, buildFilterSelectListCommand, buildListCommand, buildNoSkipListCommand, buildPickODataListCommand, buildSelectableCommand, };
+declare const buildElevatedPickODataListCommand: <Shape extends z.ZodRawShape, K extends ODataKey>(pathFn: (params: z.infer<z.ZodObject<Shape>>) => string, schema: z.ZodObject<Shape>, keys: ReadonlyArray<K>, options?: SelectDefaults) => Pick<Command, "schema" | "execute">;
+export { buildCommand, buildElevatedCommand, buildElevatedListCommand, buildElevatedPickODataListCommand, buildElevatedSelectableCommand, buildFilterSelectListCommand, buildListCommand, buildNoSkipListCommand, buildPickODataListCommand, buildSelectableCommand, };

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

@@ -3,7 +3,7 @@ import type { Result } from '../../domain/result.js';
 import type { GraphClient } from '../../infra/graph-client.js';
 type CommandSchema = z.ZodType;
 type CommandExecute = (graph: GraphClient, params: Record<string, string>) => Promise<Result<unknown, import('../../infra/graph-client.js').GraphError>>;
-type CommandCategory = 'auth' | 'drive' | 'excel' | 'sharepoint' | 'tasks' | 'mail' | 'notes' | 'user' | 'calendar' | 'contacts' | 'chats' | 'teams' | 'meta' | 'lifecycle';
+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;
@@ -80,6 +80,14 @@ 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;
@@ -107,6 +115,14 @@ type CommandMeta = {
      * commands will time out.
      */
     readonly needsElevatedToken?: true;
+    /**
+     * `true` if the command needs a Teams substrate token (chatsvcagg or ic3,
+     * captured at login from `teams.microsoft.com`) — the Teams chat-content
+     * commands. Like `needsElevatedToken`, an LLM should check this before
+     * invoking and warm up an interactive `login`; a headless or stale session
+     * times out on these (the non-interactive silent-SSO limitation, QA-011).
+     */
+    readonly needsSubstrateToken?: true;
     /**
      * `true` if the command returns inlined bytes (`{contentType, size, base64}`
      * or `{contentType, size, text}`) and is therefore a valid target for the
@@ -115,10 +131,46 @@ type CommandMeta = {
      * as a string literal. Audit round-8 Wave E2.
      */
     readonly producesBytes?: true;
+    /**
+     * `true` if the command returns a `media` array (`{ count, media: [{ path,
+     * contentType, sizeBytes, base64 }] }`) and is therefore a valid target for
+     * the global `--output-dir` flag, which writes each image to a directory.
+     * Parallel to `producesBytes` (single-file `--output-path`).
+     */
+    readonly producesMedia?: true;
+    /**
+     * `true` if the command performs a write (mutation) against Microsoft Graph
+     * rather than a read/search. Today only the two mail-draft commands
+     * (`create-mail-draft` = POST, `update-mail-draft` = PATCH) — both produce an
+     * UNSENT draft and cannot send. The CLI composition derives its read-only
+     * top-level `--help` narrative from this flag (mutating commands vs search
+     * POSTs) instead of hardcoding command names, and the manifest/`help-json`
+     * surface it so an LLM can tell at a glance which commands change state.
+     * Audit 2026-06-15 (F-03).
+     */
+    readonly mutates?: true;
+    /**
+     * Stability tier of the command. Omitted from manifest entries when the
+     * command is `'stable'` (the implicit default), surfaced only on
+     * `'experimental'` commands so an LLM can prefer stable siblings when they
+     * exist. `'experimental'` today means the command rides a Microsoft-internal
+     * substrate (chatsvcagg / IC3) that is not in the public Graph API and can
+     * break on a Teams web-client update — the docstring "Best-effort, may break
+     * on Microsoft client updates" warnings now have a structured pair.
+     * Audit Jane-session §6.
+     */
+    readonly stability?: 'experimental';
 };
 type Command = {
     readonly schema: CommandSchema;
     readonly execute: CommandExecute;
     readonly meta: CommandMeta;
+    /**
+     * Present on the rare command whose input is the LOCAL filesystem instead of
+     * Graph (`convert-local-file`). The CLI routes execution here, passing its
+     * composition-selected FileSystem; `execute` stays as the registry-typed
+     * fallback that redirects library consumers to this variant.
+     */
+    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, };

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

@@ -0,0 +1,15 @@
+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<{
+    eventId: z.ZodString;
+    attachmentId: z.ZodString;
+    includeMetadata: 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/{download-drive-item-version-as-pdf.d.ts → convert-calendar-event-attachment-to-pdf.d.ts}

@@ -3,9 +3,8 @@ 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<{
-    driveId: z.ZodString;
-    itemId: z.ZodString;
-    versionId: z.ZodString;
+    eventId: z.ZodString;
+    attachmentId: z.ZodString;
 }, z.core.$strip>;
 declare const execute: (graph: GraphClient, params: Record<string, string>) => Promise<Result<unknown, GraphError>>;
 declare const meta: CommandMeta;

package/dist/use-cases/commands/convert-drive-item-zip.d.ts

@@ -0,0 +1,26 @@
+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';
+/**
+ * Unzips a `.zip` from a OneDrive / SharePoint item and runs each contained
+ * file through the same local conversion pipelines the `*-as-markdown` commands
+ * use — so an agent reading "the project handover archive" doesn't have to shell
+ * out to `unzip` and convert each file separately. Office files (docx/xlsx/pptx/
+ * odt/ods/odp + variants) become markdown; legacy OLE .xls / .doc are extracted
+ * too (.ppt is noted, no pure-JS path); plain-text entries are decoded inline;
+ * PDFs have their text layer extracted; everything else (images, binaries, nested
+ * archives — plus scanned/image-only PDFs and legacy .ppt) is listed with a note
+ * rather than failing the whole archive.
+ */
+declare const schema: z.ZodObject<{
+    driveId: z.ZodString;
+    itemId: z.ZodString;
+    includeMetadata: 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-local-file.d.ts

@@ -0,0 +1,37 @@
+import { z } from 'zod';
+import type { Result } from '../../domain/result.js';
+import type { GraphClient, GraphError } from '../../infra/graph-client.js';
+import type { FileSystem } from '../ports/filesystem.js';
+import type { CommandMeta } from './command-types.js';
+/**
+ * Convert a file ON DISK to markdown through the same `bytesToMarkdown`
+ * dispatch every Graph-backed markdown command uses — the only command whose
+ * input never touches Microsoft Graph (works offline, no login). The fetch
+ * step was always the Graph-bound part; conversion is pure bytes-in/markdown-out.
+ *
+ * A `.zip` routes through the shared archive core (each entry converted, GBK
+ * entry names decoded); everything else goes through the single-file dispatch.
+ * What it can NOT do locally: `format=pdf` conversions (Graph renders those
+ * server-side) and Loop/Fluid/Whiteboard (`format=html`, same reason).
+ *
+ * This is the one registry command executed via `executeLocal(fs, params)` —
+ * the CLI wires its FileSystem in automatically (see `cli.ts`). The Graph-shaped
+ * `execute` exists because the public `commands` registry type requires it; it
+ * redirects library consumers to `executeLocal`.
+ */
+declare const schema: z.ZodObject<{
+    path: z.ZodString;
+    includeMetadata: z.ZodOptional<z.ZodEnum<{
+        true: "true";
+        false: "false";
+    }>>;
+    inlineImages: z.ZodOptional<z.ZodEnum<{
+        true: "true";
+        false: "false";
+    }>>;
+    maxCells: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const executeLocal: (fs: FileSystem, params: Record<string, string>) => Promise<Result<unknown, GraphError>>;
+declare const execute: (_graph: GraphClient, _params: Record<string, string>) => Promise<Result<unknown, GraphError>>;
+declare const meta: CommandMeta;
+export { execute, executeLocal, meta, schema };

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

@@ -5,7 +5,13 @@ import type { CommandMeta } from './command-types.js';
 declare const schema: z.ZodObject<{
     messageId: z.ZodString;
     attachmentId: z.ZodString;
+    includeMetadata: z.ZodOptional<z.ZodEnum<{
+        true: "true";
+        false: "false";
+    }>>;
 }, z.core.$strip>;
+declare const convertFetchedAttachment: (graph: GraphClient, a: Record<string, unknown>, includeMetadata: boolean) => Promise<Result<unknown, GraphError>> | Result<unknown, GraphError>;
+declare const convertAttachmentToMarkdown: (graph: GraphClient, attachmentPath: string, includeMetadata: boolean) => Promise<Result<unknown, GraphError>>;
 declare const execute: (graph: GraphClient, params: Record<string, string>) => Promise<Result<unknown, GraphError>>;
 declare const meta: CommandMeta;
-export { execute, meta, schema };
+export { convertAttachmentToMarkdown, convertFetchedAttachment, execute, meta, schema };

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

@@ -6,6 +6,7 @@ declare const schema: z.ZodObject<{
     messageId: z.ZodString;
     attachmentId: z.ZodString;
 }, z.core.$strip>;
+declare const convertAttachmentToPdf: (graph: GraphClient, attachmentPath: string) => Promise<Result<unknown, GraphError>>;
 declare const execute: (graph: GraphClient, params: Record<string, string>) => Promise<Result<unknown, GraphError>>;
 declare const meta: CommandMeta;
-export { execute, meta, schema };
+export { convertAttachmentToPdf, execute, meta, schema };

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

@@ -0,0 +1,24 @@
+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';
+/**
+ * Unzips a `.zip` Outlook mail attachment and converts every contained file in one
+ * call — the mail-side mirror of `convert-drive-item-zip`. Without it, reading a
+ * zipped vendor deck meant: `get-mail-attachment --output-path x.zip` → manual
+ * `unzip` (with `-O GBK` for Chinese names) → convert each file. This collapses all
+ * of that into one command: it pulls the fileAttachment bytes, unzips them (legacy
+ * GBK / CP437 entry names are decoded, not mojibaked, in the shared zip reader), and
+ * runs each entry through the same conversion dispatch the markdown commands use.
+ */
+declare const schema: z.ZodObject<{
+    messageId: z.ZodString;
+    attachmentId: z.ZodString;
+    includeMetadata: 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-to-markdown.d.ts

@@ -4,6 +4,14 @@ import type { GraphClient, GraphError } from '../../infra/graph-client.js';
 import type { CommandMeta } from './command-types.js';
 declare const schema: z.ZodObject<{
     messageId: 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;

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

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+import type { Command, CommandMeta } from './command-types.js';
+declare const schema: z.ZodObject<{
+    subject: z.ZodString;
+    bodyContent: z.ZodString;
+    bodyContentType: z.ZodOptional<z.ZodEnum<{
+        Text: "Text";
+        HTML: "HTML";
+    }>>;
+    toRecipients: z.ZodString;
+    ccRecipients: z.ZodOptional<z.ZodString>;
+    bccRecipients: z.ZodOptional<z.ZodString>;
+    importance: z.ZodOptional<z.ZodEnum<{
+        Low: "Low";
+        Normal: "Normal";
+        High: "High";
+    }>>;
+    mailFolderId: 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/doc-to-markdown.d.ts

@@ -0,0 +1,14 @@
+import type { Result } from '../../domain/result.js';
+import type { GraphError } from '../../infra/graph-client.js';
+type DocTextEnvelope = {
+    readonly contentType: 'text/plain';
+    readonly size: number;
+    readonly text: string;
+};
+/**
+ * Convert a legacy Word .doc to a plain-text envelope by extracting its body text
+ * (via word-extractor). Output is text/plain, not markdown — legacy .doc carries
+ * no structure this CLI recovers. A parse failure propagates as the infra api_error.
+ */
+declare const docToMarkdown: (bytes: Uint8Array) => Promise<Result<DocTextEnvelope, GraphError>>;
+export { docToMarkdown };

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

@@ -1,8 +1,9 @@
-import type { CommandCategory, CommandMeta } from './command-types.js';
+import type { CommandCategory, CommandMeta, PaginationStrategy } from './command-types.js';
 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;
@@ -16,8 +17,12 @@ export type CommandManifestEntry = {
     readonly scopesRequired?: CommandMeta['scopesRequired'];
     readonly needsElevatedToken?: CommandMeta['needsElevatedToken'];
     readonly producesBytes?: CommandMeta['producesBytes'];
+    readonly producesMedia?: CommandMeta['producesMedia'];
+    readonly mutates?: CommandMeta['mutates'];
+    readonly stability?: CommandMeta['stability'];
 };
-export declare const PAGINATION_HINT = "Paginated by Microsoft Graph. The CLI hoists `@odata.nextLink` out of `data` to the **top-level `nextLink`** field of the response envelope (and `@odata.deltaLink` to top-level `deltaLink` for delta commands). Pass that URL to `next-page --url <link>` and repeat until the field is absent. Do NOT look for `data[\"@odata.nextLink\"]` \u2014 the presenter strips it from `data` so the cursor is always at envelope level.";
+export declare const paginationHintFor: (strategy: PaginationStrategy | undefined) => string;
+export declare const PAGINATION_HINT = "Paginated by Microsoft Graph. The CLI hoists `@odata.nextLink` out of `data` to the **top-level `nextLink`** field of the response envelope. Pass that URL to `next-page --url <link>` and repeat until the field is absent. Do NOT look for `data[\"@odata.nextLink\"]` \u2014 the presenter strips it from `data` so the cursor is always at envelope level.";
 export type CommandManifest = {
     readonly package: string;
     readonly version: string;

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

@@ -1,10 +1,53 @@
 import type { Result } from '../../domain/result.js';
-import type { Command } from './command-types.js';
+import type { CommandCategory, Command, CommandMeta } from './command-types.js';
 import type { CommandManifest } from './docs-render.js';
 export type DocsError = {
     type: 'unknown_command';
     readonly name: string;
     readonly available: ReadonlyArray<string>;
 };
+/**
+ * Terse manifest entry — only the fields an LLM needs to *discover* a command
+ * (i.e. "does this CLI do X?"). Drops `options`, `example`, `graphPathTemplate`,
+ * `graphDocsUrl`, `responseShape`, `bodyTemplate`, `paginationStrategy`,
+ * `scopesRequired` — everything the LLM only needs once it's already decided
+ * to invoke. `stability` is kept (it's a discovery-time concern: LLMs prefer
+ * stable siblings when they exist, so they need to see the tag at discovery
+ * time, not after a second full-manifest fetch). Audit Jane-session §B/§6.
+ */
+export type TerseManifestEntry = {
+    readonly name: string;
+    readonly summary: string;
+    readonly category: CommandCategory;
+    readonly stability?: CommandMeta['stability'];
+};
+export type TerseManifest = {
+    readonly package: string;
+    readonly version: string;
+    readonly generatedAt: string;
+    readonly commands: ReadonlyArray<TerseManifestEntry>;
+};
+export type ManifestFilterError = {
+    readonly type: 'unknown_category';
+    readonly category: string;
+    readonly available: ReadonlyArray<string>;
+};
 export declare const buildManifest: (registry: Readonly<Record<string, Command>>, packageName: string, version: string, now?: () => Date) => CommandManifest;
+/**
+ * Terse manifest — `{ name, summary, category }` per command. Roughly 95%
+ * smaller than the full manifest (no options/example/Graph endpoint per entry).
+ * Use `help-json --terse` to surface this to an LLM as the discovery view.
+ */
+export declare const buildTerseManifest: (registry: Readonly<Record<string, Command>>, packageName: string, version: string, now?: () => Date) => TerseManifest;
+/**
+ * Filter a `CommandManifest` (or terse variant) down to a single category.
+ * Returns `err({ type: 'unknown_category', ... })` if the requested category
+ * isn't a known one — the CLI surfaces this through the standard error
+ * envelope rather than silently returning an empty list.
+ */
+export declare const filterManifestByCategory: <M extends {
+    readonly commands: ReadonlyArray<{
+        readonly category: CommandCategory;
+    }>;
+}>(manifest: M, category: string) => Result<M, ManifestFilterError>;
 export declare const renderSingleCommand: (registry: Readonly<Record<string, Command>>, name: string) => Result<string, DocsError>;

package/dist/use-cases/commands/docx-comment-anchors.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Correlates each docx comment to the body text it annotates. In
+ * `word/document.xml` a comment's anchored span is bracketed by empty marker
+ * elements `<w:commentRangeStart w:id="N"/> …runs… <w:commentRangeEnd w:id="N"/>`,
+ * keyed by the same `w:id` the comment in `word/comments.xml` carries. mammoth
+ * strips those markers from its HTML, so to fold the comment's context into the
+ * markdown we read document.xml directly.
+ *
+ * The shared walker (ooxml-xml-walker) groups same-named siblings and loses
+ * cross-element order, which would scramble which runs fall inside a range. So,
+ * like odf-content-to-markdown, this parses with `preserveOrder` and walks the
+ * ordered tree, tracking the set of currently-open comment ids and appending
+ * each `<w:t>` run's text to every open range. Handles overlapping / nested
+ * ranges (more than one open at once). Pure (string → Map); no IO.
+ */
+type Node = Record<string, unknown>;
+declare const tagOf: (node: Node) => string | undefined;
+declare const attr: (node: Node, name: string) => string;
+declare const leafText: (children: ReadonlyArray<Node>) => string;
+declare const clamp: (span: string) => string;
+declare const extractCommentAnchors: (documentXml: string | undefined) => ReadonlyMap<string, string>;
+export { attr, clamp, extractCommentAnchors, leafText, tagOf };

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

@@ -0,0 +1,3 @@
+import type { DocxMetadata } from './docx-metadata.js';
+declare const formatDocxMetadata: (meta: DocxMetadata) => string;
+export { formatDocxMetadata };

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

@@ -0,0 +1,69 @@
+import type { Result } from '../../domain/result.js';
+import type { GraphError } from '../../infra/graph-client.js';
+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),
+ * hidden text (w:vanish), text-box / shape text (w:txbxContent), header/footer
+ * body prose, field instructions (MERGEFIELD / HYPERLINK / DOCVARIABLE), bookmarks.
+ *
+ * The package-level parts (docProps/*, every *.rels) come from the shared
+ * ooxml-metadata module; this file owns only the docx-body-specific parts.
+ *
+ * Pure use-case logic — no IO. The zip is opened upstream via the infra
+ * adapter; this module just walks parsed XML trees. Try/catch lives in
+ * the infra adapter, not here.
+ */
+type CoreProps = Readonly<Record<string, string>>;
+type AppProps = Readonly<Record<string, string>>;
+type Person = {
+    readonly author: string;
+    readonly providerId: string;
+    readonly userId: string;
+};
+type Comment = {
+    readonly id: string;
+    readonly author: string;
+    readonly initials: string;
+    readonly date: string;
+    readonly text: string;
+    readonly anchor?: string;
+};
+type TrackedChange = {
+    readonly id: string;
+    readonly author: string;
+    readonly date: string;
+    readonly text: string;
+};
+type Field = {
+    readonly source: string;
+    readonly instruction: string;
+};
+type Bookmark = {
+    readonly id: string;
+    readonly name: string;
+};
+type HeaderFooter = {
+    readonly part: string;
+    readonly text: string;
+};
+type DocxMetadata = {
+    readonly core: CoreProps;
+    readonly app: AppProps;
+    readonly custom: ReadonlyArray<CustomProp>;
+    readonly people: ReadonlyArray<Person>;
+    readonly externalRels: ReadonlyArray<ExternalRel>;
+    readonly comments: ReadonlyArray<Comment>;
+    readonly insertions: ReadonlyArray<TrackedChange>;
+    readonly deletions: ReadonlyArray<TrackedChange>;
+    readonly hiddenText: ReadonlyArray<string>;
+    readonly textBoxes: ReadonlyArray<string>;
+    readonly headersFooters: ReadonlyArray<HeaderFooter>;
+    readonly fields: ReadonlyArray<Field>;
+    readonly bookmarks: ReadonlyArray<Bookmark>;
+    readonly macros: ReadonlyArray<string>;
+};
+declare const extractDocxMetadata: (bytes: Uint8Array) => Promise<Result<DocxMetadata, GraphError>>;
+export { extractDocxMetadata };
+export type { Bookmark, Comment, CustomProp, DocxMetadata, ExternalRel, Field, HeaderFooter, Person, TrackedChange };

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

@@ -5,7 +5,12 @@ type MarkdownEnvelope = {
     readonly size: number;
     readonly text: string;
 };
+type DocxToMarkdownOptions = {
+    readonly includeMetadata?: boolean;
+    readonly inlineImages?: boolean;
+};
+declare const stripInlineImages: (markdown: string) => string;
 declare const promoteFirstRowToThead: (html: string) => string;
-declare const docxToMarkdown: (bytes: Uint8Array) => Promise<Result<MarkdownEnvelope, GraphError>>;
-export { docxToMarkdown, promoteFirstRowToThead };
-export type { MarkdownEnvelope };
+declare const docxToMarkdown: (bytes: Uint8Array, opts?: DocxToMarkdownOptions) => Promise<Result<MarkdownEnvelope, GraphError>>;
+export { docxToMarkdown, promoteFirstRowToThead, stripInlineImages };
+export type { DocxToMarkdownOptions, MarkdownEnvelope };

package/dist/use-cases/commands/download-drive-item-as-markdown.d.ts

@@ -5,6 +5,15 @@ import type { CommandMeta } from './command-types.js';
 declare const schema: z.ZodObject<{
     driveId: z.ZodString;
     itemId: z.ZodString;
+    includeMetadata: z.ZodOptional<z.ZodEnum<{
+        true: "true";
+        false: "false";
+    }>>;
+    inlineImages: z.ZodOptional<z.ZodEnum<{
+        true: "true";
+        false: "false";
+    }>>;
+    maxCells: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 declare const execute: (graph: GraphClient, params: Record<string, string>) => Promise<Result<unknown, GraphError>>;
 declare const meta: CommandMeta;