ask-marcel-office-cli 0.5.5 → 1.4.0

package/CHANGELOG.md

@@ -0,0 +1,92 @@
+# Changelog
+
+All notable changes to `ask-marcel-office-cli` are documented here.
+
+## 1.0.0
+
+The first stable release. Two breaking changes consolidate the public output
+contract; the rest is additive.
+
+### Breaking — output contract
+
+- **Errors emit on stdout**, not stderr. `process.exitCode = 1` still
+  distinguishes failure, so shell scripts that branch on the exit code keep
+  working — but anything that read errors from stderr (`cmd 2>err.json`) needs
+  to merge streams or read stdout instead. An LLM piping `ask-marcel <cmd>
+  | jq` no longer needs `2>&1`.
+- **Every command output is wrapped in the v1 envelope**:
+  - Success: `{ ok: true, data: <payload>, nextLink?: string, count?: number }`
+  - Error: `{ ok: false, error: "<message>" }`
+
+  `@odata.nextLink` and `@odata.count` from the underlying Graph payload are
+  lifted to the top of the envelope and removed from `data`. Consumers who
+  parsed `value[0]` as the first item now read `data.value[0]`.
+
+### Added — OData query passthrough on every list/search command
+
+Every `list-*` / `search-*` / `get-*-delta` command now accepts the six
+standard OData query parameters as optional flags, so an LLM can shrink large
+responses on the fly:
+
+```
+--top <n>       maximum items per page
+--skip <n>      offset
+--select <csv>  comma-separated field list (huge payload-size win)
+--filter <kql>  server-side predicate
+--orderby <kql> sort expression
+--expand <nav>  inline navigation properties
+```
+
+Four commands keep `buildCommand` because their hard-coded `$filter` would
+collide with a user-supplied `--filter`: `list-conversation-messages`,
+`list-incomplete-todo-tasks`, `list-incomplete-planner-tasks`,
+`search-onenote-pages`.
+
+### Added — `my-quick-context`
+
+New meta command that issues five Graph calls in parallel (`/me`, `/me/drive`,
+`/me/mailFolders/inbox`, `/me/todo/lists`, `/me/calendar`) and returns
+`{ user, primaryDriveId, inboxId, todoLists, primaryCalendarId }` in one
+round trip. Replaces the audit's 5-call discovery chain.
+
+### Fixed
+
+- `microsoft-search-query` no longer 400s. Splits `entityTypes` into two
+  `requests[]` entries so Graph stops rejecting `person` mixed with
+  file/mail/event types.
+- `list-conversation-messages` no longer trips Graph's `InefficientFilter`.
+  Drops the `$orderby=receivedDateTime` from the OData query.
+- `list-sharepoint-site-items` is removed. Microsoft Graph has no list-less
+  site/items collection endpoint; `get-sharepoint-site-item`'s docstring now
+  points at the two-step discovery chain
+  (`list-sharepoint-site-lists` → `list-sharepoint-site-list-items`) that
+  Graph actually supports.
+- `list-groups` summary no longer advertises a `--top` flag it didn't
+  register. Project-wide invariant added so every `--flag` mentioned in any
+  command summary must be a real option or alias on that command.
+- `next-page` routes nextLinks under `/me/chats` and `/chats/...` via the
+  elevated M365ChatClient token. Chat pagination no longer 403s.
+- `search-onenote-pages` accepts `--query` as an alias for
+  `--title-substring`, matching the convention used by every other search
+  command.
+
+### Added — flag aliases
+
+- `--todo-list-id` is now accepted by every command that takes
+  `--todo-task-list-id` (`--task-list-id` alias preserved).
+- `get-sharepoint-site-item` accepts `--list-item-id` (alias for `--item-id`).
+  `get-sharepoint-site-list-item` accepts `--item-id` (alias for
+  `--list-item-id`). LLMs that write either spelling from memory now hit the
+  right flag.
+
+### Quality
+
+- Bun `JSON.stringify` already escapes every U+0000–U+001F control character
+  and U+2028 / U+2029 separator. The audit's "raw control chars" claim in
+  the four insight commands does not reproduce against the actual code path;
+  regression-guard tests pin the contract.
+
+## Older
+
+Earlier history is in the git log. See `git log --oneline` for individual
+commits up to and including v0.11.0.

package/README.md

@@ -1,265 +1,191 @@
 # ask-marcel-office-cli
 
-Microsoft Graph CLI — designed for LLM consumption via skills. Explicit commands, compact JSON output, zero interactive prompts beyond auth.
-
-## Commands
-
-### Authentication
-
-| Command | Description |
-|---------|-------------|
-| `login` | Authenticate (cached → refresh → browser fallback) |
-| `logout` | Clear cached tokens |
-| `update` | Update ask-marcel to the latest version on npm (auto-detects npm vs bun) |
-| `docs <cmd>` | Print Markdown docs for a single command (full machine-readable manifest at [`docs/commands.json`](docs/commands.json) or via `import manifest from 'ask-marcel-office-cli/commands.json'`) |
-
-<!-- AUTO-GENERATED-COMMANDS:BEGIN -->
-
-### OneDrive Files
-
-| Command | Description | Required params | Graph endpoint |
-|---------|-------------|-----------------|----------------|
-| `download-drive-item-version-content` | Download the binary content of a specific *non-current* historical version of a OneDrive / SharePoint file. Graph refuses to serve the current version through this endpoint with "You cannot get the content of the current version" — for the current version use `download-onedrive-file-content` instead. Same envelope as that command (302 → downloadUrl, or base64 bytes). | `--drive-id`, `--item-id`, `--version-id` | `GET /drives/{drive-id}/items/{item-id}/versions/{version-id}/content` |
-| `download-onedrive-file-content` | Download the binary content of a file stored in OneDrive / SharePoint. Graph normally returns a 302 redirect to a pre-signed CDN URL, surfaced as `@microsoft.graph.downloadUrl`; if it returns bytes directly they are base64-encoded for safe JSON output. | `--drive-id`, `--item-id` | `GET /drives/{drive-id}/items/{item-id}/content` |
-| `get-drive-delta` | Get the incremental change set (added / modified / deleted items) under a OneDrive / SharePoint folder. Use the `@odata.deltaLink` from a previous response to resume. | `--drive-id`, `--item-id` | `GET /drives/{drive-id}/items/{item-id}/delta()` |
-| `get-drive-item` | Get the metadata (driveItem resource) of a single file or folder in OneDrive / SharePoint. | `--drive-id`, `--item-id` | `GET /drives/{drive-id}/items/{item-id}` |
-| `get-drive-root-item` | Get the root folder (driveItem) of a OneDrive / SharePoint drive. | `--drive-id` | `GET /drives/{drive-id}/root` |
-| `list-drive-item-permissions` | List the sharing permissions on a OneDrive / SharePoint file or folder. | `--drive-id`, `--item-id` | `GET /drives/{drive-id}/items/{item-id}/permissions` |
-| `list-drive-item-versions` | List the historical versions of a OneDrive / SharePoint file (each save creates a new version). | `--drive-id`, `--item-id` | `GET /drives/{drive-id}/items/{item-id}/versions` |
-| `list-drives` | List all OneDrive / SharePoint drives the signed-in user has access to. | _(none)_ | `GET /me/drives` |
-| `list-folder-files` | List the children (files and subfolders) of a folder in OneDrive / SharePoint. | `--drive-id`, `--item-id` | `GET /drives/{drive-id}/items/{item-id}/children` |
-| `search-my-documents` | Search the signed-in user’s default OneDrive for documents matching a free-text query (filename, content, metadata). | `--query` | `GET /me/drive/search(q='{query}')` |
-| `search-onedrive-files` | Search a single OneDrive / SharePoint drive for files and folders matching a free-text query. | `--drive-id`, `--query` | `GET /drives/{drive-id}/search(q='{query}')` |
-
-### Excel (workbook files)
-
-| Command | Description | Required params | Graph endpoint |
-|---------|-------------|-----------------|----------------|
-| `get-excel-range` | Get the cell values, formulas, and formats of a specific Excel range (e.g. `A1:C10`). | `--drive-id`, `--item-id`, `--worksheet-id`, `--address` | `GET /drives/{drive-id}/items/{item-id}/workbook/worksheets/{worksheet-id}/range(address='{address}')` |
-| `get-excel-table` | Get the metadata (style, header row, total row) of a single named Excel table. | `--drive-id`, `--item-id`, `--table-id` | `GET /drives/{drive-id}/items/{item-id}/workbook/tables/{table-id}` |
-| `list-excel-table-rows` | List the data rows of a named Excel table (excluding the header row). | `--drive-id`, `--item-id`, `--table-id` | `GET /drives/{drive-id}/items/{item-id}/workbook/tables/{table-id}/rows` |
-| `list-excel-tables` | List the named tables across every worksheet in an Excel workbook. | `--drive-id`, `--item-id` | `GET /drives/{drive-id}/items/{item-id}/workbook/tables` |
-| `list-excel-worksheets` | List the worksheets (tabs) inside an Excel workbook stored in OneDrive / SharePoint. | `--drive-id`, `--item-id` | `GET /drives/{drive-id}/items/{item-id}/workbook/worksheets` |
-
-### SharePoint Sites
-
-| Command | Description | Required params | Graph endpoint |
-|---------|-------------|-----------------|----------------|
-| `get-sharepoint-site` | Get the metadata of a single SharePoint site by its site ID. | `--site-id` | `GET /sites/{site-id}` |
-| `get-sharepoint-site-by-path` | Resolve a SharePoint site by its hostname + server-relative path. Use this when you have a SharePoint URL (e.g. `https://contoso.sharepoint.com/sites/Marketing`) but no site ID. | `--hostname`, `--path` | `GET /sites/{hostname}:{path}` |
-| `get-sharepoint-site-drive-by-id` | Get the metadata of a single document library (drive) on a SharePoint site by drive ID. | `--site-id`, `--drive-id` | `GET /sites/{site-id}/drives/{drive-id}` |
-| `get-sharepoint-site-list` | Get the metadata (display name, template, columns) of a single SharePoint list. | `--site-id`, `--list-id` | `GET /sites/{site-id}/lists/{list-id}` |
-| `get-sharepoint-site-list-item` | Get a single row (listItem) of a SharePoint list by ID. | `--site-id`, `--list-id`, `--list-item-id` | `GET /sites/{site-id}/lists/{list-id}/items/{list-item-id}` |
-| `list-sharepoint-site-drives` | List the document libraries (drives) attached to a SharePoint site. | `--site-id` | `GET /sites/{site-id}/drives` |
-| `list-sharepoint-site-list-items` | List the rows (listItem resources) of a single SharePoint list. | `--site-id`, `--list-id` | `GET /sites/{site-id}/lists/{list-id}/items` |
-| `list-sharepoint-site-lists` | List all SharePoint lists (custom + built-in document libraries) on a site. | `--site-id` | `GET /sites/{site-id}/lists` |
-| `search-sharepoint-sites` | List the SharePoint sites the signed-in user has access to (returns the followed sites by default). | _(none)_ | `GET /sites` |
-| `search-sharepoint-sites-by-name` | Search the tenant for SharePoint sites whose display name or description matches a free-text query (returns up to 25). | `--query` | `GET /sites?search={query}` |
-
-### Tasks (To Do + Planner)
-
-| Command | Description | Required params | Graph endpoint |
-|---------|-------------|-----------------|----------------|
-| `get-planner-bucket` | Get the metadata of a single Microsoft Planner bucket (column / lane). | `--planner-bucket-id` | `GET /planner/buckets/{planner-bucket-id}` |
-| `get-planner-plan` | Get the metadata of a single Microsoft Planner plan (title, owner group, container). | `--planner-plan-id` | `GET /planner/plans/{planner-plan-id}` |
-| `get-planner-task` | Get the metadata of a single Microsoft Planner task (title, assignees, dates, completion). | `--planner-task-id` | `GET /planner/tasks/{planner-task-id}` |
-| `get-planner-task-details` | Get the rich details (description, checklist, references) of a Microsoft Planner task. | `--planner-task-id` | `GET /planner/tasks/{planner-task-id}/details` |
-| `get-todo-task` | Get a single Microsoft To Do task by its ID and its parent list ID. | `--todo-task-list-id`, `--todo-task-id` | `GET /me/todo/lists/{todo-task-list-id}/tasks/{todo-task-id}` |
-| `list-incomplete-planner-tasks` | List every incomplete Microsoft Planner task assigned to or owned by the signed-in user, across every plan. | _(none)_ | `GET /me/planner/tasks?$filter=percentComplete ne 100` |
-| `list-incomplete-todo-tasks` | List every incomplete Microsoft To Do task in a given list (status not equal to `completed`). | `--todo-task-list-id` | `GET /me/todo/lists/{todo-task-list-id}/tasks?$filter=status ne 'completed'` |
-| `list-plan-buckets` | List the buckets (columns / lanes) of a Microsoft Planner plan. | `--planner-plan-id` | `GET /planner/plans/{planner-plan-id}/buckets` |
-| `list-plan-tasks` | List every task within a Microsoft Planner plan, regardless of completion status (Graph orders by `orderHint`). Use `list-incomplete-planner-tasks` for the across-plans incomplete view. | `--planner-plan-id` | `GET /planner/plans/{planner-plan-id}/tasks` |
-| `list-planner-plans` | List every Microsoft Planner plan the signed-in user has access to (across every group). Use this to discover plan IDs without needing an existing task as the entry point. | _(none)_ | `GET /me/planner/plans` |
-| `list-planner-tasks` | List every Microsoft Planner task assigned to or owned by the signed-in user, across all plans. | _(none)_ | `GET /me/planner/tasks` |
-| `list-todo-linked-resources` | List the linked resources (URLs, emails, files) attached to a Microsoft To Do task. | `--todo-task-list-id`, `--todo-task-id` | `GET /me/todo/lists/{todo-task-list-id}/tasks/{todo-task-id}/linkedResources` |
-| `list-todo-task-lists` | List the signed-in user’s Microsoft To Do task lists (e.g. `Tasks`, `Flagged Emails`, custom lists). | _(none)_ | `GET /me/todo/lists` |
-| `list-todo-tasks` | List every task in a single Microsoft To Do task list, regardless of completion status. Use `list-incomplete-todo-tasks` if you only want the open ones. | `--todo-task-list-id` | `GET /me/todo/lists/{todo-task-list-id}/tasks` |
-
-### Mail
-
-| Command | Description | Required params | Graph endpoint |
-|---------|-------------|-----------------|----------------|
-| `get-mail-attachment` | Get a single attachment on an Outlook message (metadata, plus the base64 `contentBytes` for file attachments). | `--message-id`, `--attachment-id` | `GET /me/messages/{message-id}/attachments/{attachment-id}` |
-| `get-mail-message` | Get a single Outlook message by ID, including subject, sender, body, and flags. | `--message-id` | `GET /me/messages/{message-id}` |
-| `get-mailbox-settings` | Get the signed-in user’s Outlook mailbox settings (timezone, working hours, automatic replies). | _(none)_ | `GET /me/mailboxSettings` |
-| `list-mail-attachments` | List the attachments (file, item, reference) on a single Outlook message. | `--message-id` | `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` | `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` | `GET /me/mailFolders/{mail-folder-id}/messages` |
-| `list-mail-folders` | List the top-level mail folders in the signed-in user’s Outlook mailbox (Inbox, Sent Items, etc.). | _(none)_ | `GET /me/mailFolders` |
-| `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). Use `list-mail-folder-messages` to scope to a single folder such as Inbox. | _(none)_ | `GET /me/messages` |
-| `list-mail-rules` | List the inbox / folder rules attached to a single Outlook mail folder. | `--mail-folder-id` | `GET /me/mailFolders/{mail-folder-id}/messageRules` |
-| `search-mail-messages` | Search the signed-in user’s entire Outlook mailbox using KQL or free text. Results are ranked by Graph relevance. | `--query` | `GET /me/messages?$search="{query}"` |
-
-### Notes (OneNote)
-
-| Command | Description | Required params | Graph endpoint |
-|---------|-------------|-----------------|----------------|
-| `get-onenote-page-content` | Get the HTML body of a single OneNote page. Returned in a JSON envelope so the HTML survives transport. | `--onenote-page-id` | `GET /me/onenote/pages/{onenote-page-id}/content` |
-| `list-all-onenote-sections` | List every OneNote section the signed-in user can see, across all notebooks. | _(none)_ | `GET /me/onenote/sections` |
-| `list-onenote-notebook-sections` | List the top-level sections of a single OneNote notebook (flat — does NOT recurse into section groups; use `list-all-onenote-sections` to flatten every notebook the user has access to). | `--notebook-id` | `GET /me/onenote/notebooks/{notebook-id}/sections` |
-| `list-onenote-notebooks` | List the OneNote notebooks the signed-in user owns or has access to (sorted by `createdDateTime` desc by Graph; soft-deleted notebooks excluded). | _(none)_ | `GET /me/onenote/notebooks` |
-| `list-onenote-section-pages` | List the pages inside a single OneNote section. | `--onenote-section-id` | `GET /me/onenote/sections/{onenote-section-id}/pages` |
-| `search-onenote-pages` | Find OneNote pages whose title contains a substring (case-sensitive — page content is NOT searched). Microsoft removed full-text OneNote `?search=` from v1.0 Graph; only $filter against `title` remains, which is what this command runs. | `--title-substring` | `GET /me/onenote/pages?$filter=contains(title,'{title-substring}')` |
-
-### User
-
-| Command | Description | Required params | Graph endpoint |
-|---------|-------------|-----------------|----------------|
-| `get-current-user` | Return the signed-in user’s Microsoft Graph profile (id, displayName, mail, jobTitle, etc.). | _(none)_ | `GET /me` |
-| `get-my-profile-photo` | Download the signed-in user’s profile photo (largest available size). Returned as a base64 envelope so the binary survives JSON output. | _(none)_ | `GET /me/photo/$value` |
-
-### Calendar
-
-| Command | Description | Required params | Graph endpoint |
-|---------|-------------|-----------------|----------------|
-| `get-calendar-event` | Fetch a single calendar event by ID from the signed-in user’s default calendar. | `--event-id` | `GET /me/events/{event-id}` |
-| `get-calendar-view` | List the signed-in user’s default-calendar events with recurrence expanded into individual occurrences in a date range. Both ISO date-time params are required by Graph. | `--start-date-time`, `--end-date-time` | `GET /me/calendarView?startDateTime={start-date-time}&endDateTime={end-date-time}` |
-| `get-specific-calendar-event` | Fetch a single calendar event by ID from a specific (non-default) calendar. | `--calendar-id`, `--event-id` | `GET /me/calendars/{calendar-id}/events/{event-id}` |
-| `get-specific-calendar-view` | List the events in a specific (non-default) calendar with recurrence expanded into individual occurrences in a date range. Both ISO date-time params are required by Graph. | `--calendar-id`, `--start-date-time`, `--end-date-time` | `GET /me/calendars/{calendar-id}/calendarView?startDateTime={start-date-time}&endDateTime={end-date-time}` |
-| `list-calendar-event-instances` | List the individual occurrences of a recurring calendar event over a date range. Both ISO date-time params are required by Graph. | `--calendar-id`, `--event-id`, `--start-date-time`, `--end-date-time` | `GET /me/calendars/{calendar-id}/events/{event-id}/instances?startDateTime={start-date-time}&endDateTime={end-date-time}` |
-| `list-calendar-events` | List the events in the signed-in user’s default calendar (does not expand recurrences). | _(none)_ | `GET /me/events` |
-| `list-calendar-events-delta` | Get the incremental change set (added / modified / deleted events) for the signed-in user’s default calendar. Use the `@odata.deltaLink` from a previous response to resume. | _(none)_ | `GET /me/events/delta()` |
-| `list-calendar-view-delta` | Get the first page of the incremental change set of expanded calendar-view occurrences over a date range. Subsequent pages: feed the returned `@odata.nextLink` to `next-page`; resume later via the `@odata.deltaLink`. | `--start-date-time`, `--end-date-time` | `GET /me/calendarView/delta()?startDateTime={start-date-time}&endDateTime={end-date-time}` |
-| `list-calendars` | List the calendars in the signed-in user’s mailbox (default + secondary calendars + shared calendars). | _(none)_ | `GET /me/calendars` |
-| `list-specific-calendar-events` | List the events in a specific (non-default) calendar (does not expand recurrences). | `--calendar-id` | `GET /me/calendars/{calendar-id}/events` |
-
-### Chats
-
-| Command | Description | Required params | Graph endpoint |
-|---------|-------------|-----------------|----------------|
-| `list-chat-members` | List the members of a single Microsoft Teams chat. | `--chat-id` | `GET /chats/{chat-id}/members` |
-
-### Teams
-
-| Command | Description | Required params | Graph endpoint |
-|---------|-------------|-----------------|----------------|
-| `get-team` | Get the metadata of a single Microsoft Team (display name, settings, member-settings, owner group). | `--team-id` | `GET /teams/{team-id}` |
-| `get-team-channel` | Get the metadata of a single channel inside a Microsoft Team. | `--team-id`, `--channel-id` | `GET /teams/{team-id}/channels/{channel-id}` |
-| `list-joined-teams` | List the Microsoft Teams the signed-in user is a member of. | _(none)_ | `GET /me/joinedTeams` |
-| `list-team-channels` | List the channels (standard, private, shared) inside a single Microsoft Team. | `--team-id` | `GET /teams/{team-id}/channels` |
-
-### Meta / Pagination
-
-| Command | Description | Required params | Graph endpoint |
-|---------|-------------|-----------------|----------------|
-| `next-page` | Fetch the next page of a paginated Graph response. Pass the `@odata.nextLink` value returned by any list / search / delta command to walk pagination yourself. | `--url` | `GET {url}` |
-
-<!-- AUTO-GENERATED-COMMANDS:END -->
-## Install
-
-Requires Node ≥20 **or** Bun ≥1.0 on the user's machine. Works on Windows, macOS, and Linux.
+**A Microsoft Graph CLI built for LLMs.** 165 read-only commands across Mail, Calendar, OneDrive, SharePoint, Excel, Teams chats, Planner / To-Do, OneNote, and directory. Sign in once with your Microsoft 365 account — no Azure app registration, no admin consent, no client secrets.
 
 ```bash
-npm i -g ask-marcel-office-cli      # any platform with Node
-# — or —
-bun add -g ask-marcel-office-cli    # any platform with Bun
+npm i -g ask-marcel-office-cli
+ask-marcel login                 # browser opens once, token cached
+ask-marcel my-quick-context      # who am I + my IDs, in one round trip
+ask-marcel list-mail-messages --top 5
 ```
 
-The first launch prints a one-time notice if a newer version is on npm; update with the same command above plus `@latest`.
+---
 
-## Usage (CLI)
+## Why it exists
+
+LLM tool-loops keep hitting the same three walls with Microsoft Graph:
+
+1. **Auth is a project.** Register an app, get tenant-admin consent, manage secrets, refresh tokens — before the first API call.
+2. **Default payloads are tuned for backend services, not context windows.** Listing endpoints return every field on every item, used-range Excel calls return four redundant 2D arrays, attachment endpoints inline base64 by default. An agent that reads "what's in my inbox" without trimming burns its budget on metadata it never needed.
+3. **Errors are opaque.** `BadRequest: Invalid filter clause` doesn't tell a model what to fix.
+
+`ask-marcel` fixes all three at the CLI layer, so the model just calls commands and reads back-pressure-friendly responses.
+
+## What you get
+
+### Read-only by design
+
+**This is the most important property.** 164 GET endpoints + 1 POST (search). No `send-mail`, no `create-event`, no `upload-file`, no `delete-anything`. A hallucinated command can't break anything — the worst case is a 404. Safe default for autonomous agents, MCP servers, and "let Claude poke around my mailbox" sessions where you can't fully review every tool call.
+
+### One call gets the full email context
+
+A typical "read this email" loop in raw Graph: GET the message → GET the attachments list → GET each attachment's bytes → scan the body HTML for `sharepoint.com` URLs → resolve each URL to a driveItem → GET each driveItem. Six round-trips minimum, plus HTML-to-text conversion the LLM has to do itself.
+
+`convert-mail-to-markdown` collapses that into one call:
+
+- Body rendered as markdown (turndown pipeline)
+- Inline images embedded as base64 `data:` URIs (size-capped per image — opt out with `--inline-images false` to keep raw `cid:` refs)
+- File attachments listed below the body with id + name + size, ready for follow-up calls
+- Pair with `extract-sharepoint-links-in-mail` to resolve every SharePoint URL in the body to its driveItem in parallel (capped at 25 unique URLs per call)
+
+### Office docs → markdown or PDF on the fly
+
+Feed any Office-shaped file (docx, xlsx, pptx, csv, rtf, odt, …) into the local conversion pipeline OR through Graph's `?format=pdf` when slide layout and images matter:
+
+- `download-drive-item-as-markdown` — docx via mammoth (with inline images as data URIs), xlsx as one markdown table per sheet, csv as a table, plain-text passthrough
+- `download-drive-item-as-pdf` — Graph PDF conversion for anything it supports (preserves slide layout, images, charts — the right call for pptx and image-heavy docs)
+- `convert-mail-attachment-to-markdown` / `convert-mail-attachment-to-pdf` — same pipelines but starting from an email attachment
+
+The CLI follows any SharePoint media-transform redirect internally, so the LLM never has to fetch an external URL.
+
+### Browser-OAuth at first launch
+
+No Azure app, no tenant admin. The CLI captures the same token the Teams web client uses — works for any Microsoft 365 account, personal or enterprise.
+
+### Stable error envelope with actionable hints
+
+Every failure — Graph, CLI parser, Zod validation, substrate — comes back as `{ok: false, error, errorCode?, hint?, source}`. The `hint` field tells the model *what to do next* (e.g. "string literals MUST use single quotes; embed one by doubling it") and `source` tells it where the failure came from. Curated rules for 20+ recurring Graph errors plus cross-resolver pointers (passed a Teams URL to `resolve-mail-link`? Hint says "re-run with `resolve-teams-link`").
+
+### Lean responses
+
+Listings ship with hand-tuned `--select` defaults — a mail listing returns id, subject, from, to, cc, dates, read-state, importance, bodyPreview rather than every field on every message. `get-excel-used-range` returns the `values` array instead of the four 2D arrays Graph emits. Opt out per call with `--full true`, or override with your own `--select id,subject,body`.
+
+### Saves big binaries to disk so they never hit the model's context
+
+A typical conversion command returns multi-MB PDF bytes. Sending 5 MB of base64 through stdout would blow most context windows AND quadruple the token bill.
+
+Two flag patterns avoid the round-trip:
+
+- **`--output-path /path/to/file.pdf`** — the CLI decodes the bytes, writes them to disk, and replaces `base64: "..."` in the envelope with `savedTo: "/path/to/file.pdf"`. The LLM sees a 3-line confirmation instead of a 7-million-character payload. Works on every command that returns binary or text content; rejected with a clear error on plain-JSON commands so a misapplied flag is never silent.
+- **No flag, text mode** — binary commands print a one-line summary (`binary: application/pdf, 4837291 bytes — use --output-path to save`) instead of spilling base64 to stdout. The LLM sees a hint without ever pulling the bytes.
+
+### Relative dates on calendar windows
+
+`--start-date-time "start-of-week" --end-date-time "+7d"`. No timestamp math before answering "what's on my calendar this week".
+
+## 30-second quickstart
 
 ```bash
+# install (Bun ≥1.0 or Node ≥20)
+npm i -g ask-marcel-office-cli
+
 # authenticate (cached → refresh → browser fallback)
 ask-marcel login
 
-# list drives
+# everything else is read-only and discoverable from --help
 ask-marcel list-drives
+ask-marcel search-onedrive-files --drive-id "b!abc..." --query "Q3 budget"
+ask-marcel convert-mail-to-markdown --message-id "AAMkAD..."
+ask-marcel list-calendar-view --start-date-time today --end-date-time +7d
+ask-marcel convert-mail-attachment-to-pdf \
+  --message-id "AAMkAD..." --attachment-id "AAMkAD...attach1" \
+  --output-path /tmp/deck.pdf
+```
 
-# search for files
-ask-marcel search-onedrive-files --drive-id abc123 --query "report"
+## Asking the CLI what it can do
 
-# get Excel table data
-ask-marcel list-excel-table-rows --drive-id abc123 --item-id xyz789 --table-id table1
+Five discovery surfaces, each tuned for a different audience and token budget:
 
-# search SharePoint sites
-ask-marcel search-sharepoint-sites
+| When you want | Run | Returns |
+|---|---|---|
+| Help with a single command | `ask-marcel <command> --help` | Required flags, optional flags, an example, pagination notes |
+| A scan of every command | `ask-marcel --help` | One-sentence summary per command, grouped by category |
+| The slim LLM-friendly index | `ask-marcel help-json --terse` | JSON manifest with heavy fields (options, response shape) stripped — best first-call for an agent meeting the CLI for the first time |
+| The slim index for one domain | `ask-marcel help-json --terse --category mail` | Same as above, filtered to one of 12 categories — keeps the response tiny when the agent already knows the domain |
+| Rich docs for one command | `ask-marcel docs <command>` | Full Markdown to stdout (response shape, examples, the underlying Graph endpoint, Microsoft Learn link) |
 
-# list SharePoint site lists
-ask-marcel list-sharepoint-site-lists --site-id contoso.sharepoint.com,1234-5678
+Pair `help-json --terse --category <name>` with `docs <command>` for the canonical agent loop: scan the category, pick a command, fetch its full docs, then call it.
 
-# update to the latest version (auto-detects npm vs bun)
-ask-marcel update
+## Use it from Claude Code, Cursor, Cline, or any tool-calling LLM
 
-# clear tokens
-ask-marcel logout
+Most agents already know how to read JSON from stdout. Two patterns work:
 
-# see all commands
-ask-marcel --help
-```
+**1. Drop in as a shell tool** — the agent learns the manifest, then runs `ask-marcel <command> --output json`. The slim defaults + structured error hints mean it can self-recover from typos.
 
-`ask-marcel update` auto-detects whether the CLI was installed via npm or bun (based on the bin path) and reinstalls globally with the matching tool. You can still run the install manually: `npm i -g ask-marcel-office-cli@latest` or `bun add -g ask-marcel-office-cli@latest`.
+**2. Embed as a library** — every command is exported. Compose it inside your own MCP server, Claude Agent, or LangChain tool:
 
-During development from a clone you can keep using `bun run src/main.ts <command>`.
+```ts
+import { commands, buildDeps } from 'ask-marcel-office-cli';
+
+const { graph } = buildDeps();
+const result = await commands['list-mail-messages'].execute(graph, { top: '10' });
+if (result.ok) {
+  // result.value is the Graph payload — typed Result<unknown, GraphError>
+}
+```
 
-## Usage (library)
+### Auth — two paths
 
-The package exports a typed library API for embedding inside your own CLI, agent, or service.
+**Most users — use the built-in browser-OAuth ladder:**
 
 ```ts
-import { commands, createGraphClient, buildDeps, type Result } from 'ask-marcel-office-cli';
+import { buildDeps } from 'ask-marcel-office-cli';
 
-// option 1 — full ladder with built-in OAuth and file cache
 const { graph } = buildDeps();
-const result = await commands['list-drives'].execute(graph, {});
-if (result.ok) console.log(result.value);
-
-// option 2 — bring your own AuthManager / token
-const graph = createGraphClient({
-  getAccessToken: async () => ({ ok: true, value: process.env.MS_GRAPH_TOKEN as never }),
-  logout: async () => ({ ok: true, value: undefined }),
-});
-const me = await commands['get-current-user'].execute(graph, {});
+// First call triggers cache → refresh → headed-Chromium fallback automatically.
+// Tokens cached at ~/.ask-marcel/token-cache.json for subsequent calls.
 ```
 
-The full export list (registry, factories, `Result`, branded types, ports) is in [src/index.ts](src/index.ts).
+**Agents / CI / MCP servers — bring your own token:**
 
-## Architecture
+```ts
+import { createGraphClient } from 'ask-marcel-office-cli';
 
-```
-src/
-  domain/          — Result<T,E>, branded value-object types (AccessToken, EnvVar), JWT utilities, format-error
-  infra/           — Auth recovery ladder (cache → refresh → Playwright browser), Graph API HTTP client, Winston logger
-  use-cases/       — Commands (schemas + execute functions), ports
-  composition/     — CLI wiring (Commander), dependency graph
-  presenter/       — Compact JSON output formatting
+const graph = createGraphClient({
+  getAccessToken: async () => ({
+    ok: true,
+    value: await fetchTokenFromYourVault(),
+  }),
+  logout: async () => ({ ok: true, value: undefined }),
+});
 ```
 
-- **Auth**: Three-rung recovery ladder — file-based cached JWT → OAuth refresh_token exchange → Playwright browser intercepting Teams login
-- **Client ID**: `5e3ce6c0-2b1f-4285-8d4b-75ee78787346` (Teams Web)
-- **Scopes**: `https://graph.microsoft.com/.default openid profile offline_access`
-- **Token cache**: `~/.ask-marcel/token-cache.json` (overridable via `BuildDepsConfig.cachePath`)
-- **Browser profile**: `~/.ask-marcel/browser-profile` (overridable via `ASKMARCEL_BROWSER_PROFILE`)
-- **Output**: Compact JSON via `JSON.stringify` — no indentation, optimised for LLM token efficiency
+The `AuthManager` interface is two async methods that return `Result<T, AuthError>`. Plug in any token source — Azure Managed Identity, a secrets vault, an on-behalf-of flow, hand-pasted JWTs in tests. The Graph client doesn't care where the token came from.
 
-## Configuration
+## Deep docs
 
-Environment variables read at composition time:
+- **[All 165 commands](docs/COMMANDS.md)** — per-category tables with required params + Graph endpoint
+- **[Usage guide](docs/USAGE.md)** — output formats, OData passthrough, `--output-path`, pagination, library API, architecture, configuration, quality gates
+- **[Machine-readable manifest](docs/commands.json)** — JSON for programmatic discovery (LLM tool-loops, IDE plugins, MCP servers); also importable via `import manifest from 'ask-marcel-office-cli/commands.json'`
 
-| Variable | Used by | Default |
-|---|---|---|
-| `ASKMARCEL_LOG_LEVEL` | Winston logger; all output goes to **stderr** (stdout reserved for command JSON). Namespaced so a generic `LOG_LEVEL` exported by another tool in your shell does not leak into ours. | `error` (use `info` or `debug` for troubleshooting) |
-| `HOME` / `USERPROFILE` | Default cache and browser-profile paths | _(required)_ |
-| `ASKMARCEL_BROWSER_PROFILE` | Override Playwright user-data-dir | _(none)_ |
+## Roadmap
 
-`HTTP_PROXY` / `HTTPS_PROXY` / `http_proxy` / `https_proxy` are stripped from the process environment immediately before launching Playwright (see `src/infra/browser-auth.ts`).
+Read-only stays the default forever. The list below is additive coverage and convenience — concrete next steps, ordered by how often they come up in real LLM workflows:
 
-## Quality gates (atelier four-check loop)
+- **Zip archive support** — extract a `.zip` from an email attachment or OneDrive item and run every contained file through the right conversion pipeline (markdown or PDF), so an agent reading "the project handover archive" doesn't have to shell out to `unzip`.
+- **SharePoint links inside documents** — today `extract-sharepoint-links-in-mail` finds and resolves every `sharepoint.com` URL in an email body; the same pass for inline links in docx/xlsx/pptx would close the loop on "follow every reference in this document".
+- **Bulk folder conversion** — `convert-folder --drive-id … --item-id <folder> --format markdown` walks a folder and converts every Office file in one call, returning the combined markdown (or writing per-file outputs to a directory via `--output-path`).
+- **OneNote end-to-end markdown** — OneNote page reads currently return raw HTML; chaining the turndown pipeline (same one `convert-mail-to-markdown` uses) would give parity with the docx route.
+- **PowerPoint as slide images** — for vision-capable LLMs, render each pptx slide as a PNG alongside the existing PDF route so the model can reason about layout + diagrams without going through PDF parsing.
+- **Calendar meeting attachments** — `/events/{id}/attachments` isn't exposed yet; would pair with the existing `convert-mail-attachment-to-*` shape so "summarize the deck attached to my 3pm" is a single call.
+- **Multi-tenant auth profiles** — `ask-marcel login --profile work` / `--profile personal` with separate token caches at `~/.ask-marcel/<profile>/`, for consultants and contractors who routinely switch tenants.
+- **Streaming pagination output** — write each page to stdout as it arrives instead of accumulating, so long delta walks don't hold gigabytes in memory and an agent can start processing page 1 while page 2 is in flight.
+- **Excel charts as PNG** — `list-excel-worksheet-charts` already returns chart metadata; add `get-excel-chart-image` that renders the chart as a base64 PNG via Graph's `.../charts/{id}/image()` endpoint so vision-capable models can read the chart, not just its title.
+- **Yammer / Viva Engage** — community posts, threads, and replies. Currently unscoped on the Teams web-client token, so this would need a scope investigation first.
+- **Federated tenant search expansion** — `microsoft-search-query` exists but covers a narrow entity set; expanding to people, sites, lists, and chat messages would unify discovery across all of M365 behind one search call.
+- **Quoted-text stripping in `convert-mail-to-markdown`** — collapse "On Tuesday Alice wrote..." reply chains so long threads stop blowing the context budget on duplicated quoted content.
+- **`--diff` flag on `download-drive-item-version` markdown** — render the markdown diff between two historical versions of the same file (e.g. "what changed in the spec last week"), so an agent can answer revision questions without manually comparing two long markdown blobs.
+- **Full-fidelity document context** — extract every piece of written information in a document: reviewer comments, threaded comments, slide notes, revision marks, descriptions, custom metadata, and sensitivity labels — folded into the markdown output so an LLM reads the whole story of a document, not just its body text.
+- **OCR for images and image-only PDFs** — pipe images (jpg/png attachments, inline email images) and scanned PDFs through a local OCR pass, returning extracted text as markdown. Closes the loop on screenshots, scanned receipts, and image-only attachments that today come back as opaque bytes.
 
-```bash
-bun test           # full suite
-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)
-bun run mutate:changed  # mutation testing on changed domain/use-case files (>90% kill threshold)
-```
+Suggestions, requests, and pull requests welcome — see the [issues page](https://github.com/vdelacou/ask-marcel-office-cli/issues).
 
-### Pre-commit hook (atelier 8 gates)
+## Built with
 
-The repo ships an 8-gate hook at `.githooks/pre-commit` (commit size → package.json → gitleaks → tests → strict lint → typecheck → coverage → mutation). Install once per clone:
+- **Bun + TypeScript** — single binary install, Node ≥20 fallback. `Result<T, E>` at every IO boundary, branded value-object types at trust boundaries, classicist outside-in TDD, zero lint warnings, 100% coverage on every tier.
+- **Microsoft Graph v1.0** — the public API surface, no beta endpoints in production code.
+- **Playwright** — headed Chromium for the first-launch browser-OAuth dance.
 
-```bash
-git config core.hooksPath .githooks
-```
+## License
 
-Optional but recommended: install [gitleaks](https://github.com/gitleaks/gitleaks) (`brew install gitleaks`) to enable gate 3. The hook degrades gracefully if it's missing.
+MIT © Vincent Delacourt