ask-marcel-office-cli 0.1.0 → 0.5.5

package/dist/cli.js

@@ -12003,8 +12003,8 @@ import updateNotifier from "update-notifier";
 // package.json
 var package_default = {
   name: "ask-marcel-office-cli",
-  version: "0.1.0",
-  description: "Microsoft Graph CLI + library — typed Bun/TypeScript wrapper around 100+ Graph API operations with browser-fallback OAuth.",
+  version: "0.5.5",
+  description: "Microsoft Graph CLI + library — typed Bun/TypeScript wrapper around 70+ read-side Graph operations reachable from a Teams browser-OAuth token.",
   license: "MIT",
   author: "Vincent Delacourt <vincent.delacourt@adama-development.com>",
   repository: {
@@ -12024,6 +12024,7 @@ var package_default = {
       types: "./dist/index.d.ts",
       import: "./dist/index.js"
     },
+    "./commands.json": "./dist/commands.json",
     "./package.json": "./package.json"
   },
   bin: {
@@ -12031,6 +12032,7 @@ var package_default = {
   },
   files: [
     "dist/",
+    "docs/commands.json",
     "README.md",
     "LICENSE"
   ],
@@ -12064,7 +12066,8 @@ var package_default = {
     "mutate:staged": "bash scripts/mutate-staged.sh",
     "build:js": "bun build src/main.ts --target=node --outfile=dist/cli.js --format=esm --external playwright --external update-notifier && bun build src/index.ts --target=node --outfile=dist/index.js --format=esm --external playwright --external update-notifier",
     "build:types": "tsc -p tsconfig.build.json",
-    build: "rm -rf dist && bun run build:js && bun run build:types && bun run scripts/fix-dts-extensions.ts && bun run scripts/add-shebang.ts",
+    "docs:gen": "bun run scripts/gen-docs.ts",
+    build: "rm -rf dist && bun run docs:gen && bun run build:js && bun run build:types && bun run scripts/fix-dts-extensions.ts && bun run scripts/add-shebang.ts && cp docs/commands.json dist/commands.json",
     prepublishOnly: "bun run build && bun test && bun run lint:strict && bun run typecheck && bun run coverage"
   },
   devDependencies: {
@@ -12157,6 +12160,7 @@ var formatError = (err2) => {
 };
 
 // src/infra/filesystem-bun.ts
+var isMissingError = (e) => e instanceof Error && e.code === "ENOENT";
 var createBunFileSystem = () => ({
   readJson: async (path) => {
     const file = Bun.file(path);
@@ -12177,13 +12181,12 @@ var createBunFileSystem = () => ({
     }
   },
   deleteIfExists: async (path) => {
-    const file = Bun.file(path);
-    if (!await file.exists())
-      return ok(undefined);
     try {
-      await file.delete();
+      await Bun.file(path).delete();
       return ok(undefined);
     } catch (e) {
+      if (isMissingError(e))
+        return ok(undefined);
       return err({ type: "io_failed", message: formatError(e) });
     }
   }
@@ -12230,8 +12233,12 @@ var createNodeFileSystem = () => ({
   }
 });
 
+// src/infra/playwright-loader.ts
+var loadPlaywright = async () => import("playwright");
+
 // src/infra/browser-auth.ts
 var TOKEN_HOSTS = ["login.microsoftonline.com", "login.live.com", "login.microsoft.com"];
+var PROXY_ENV_KEYS = ["HTTP_PROXY", "HTTPS_PROXY", "http_proxy", "https_proxy"];
 var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 var defaultProfileDir = () => {
   const envOverride = process.env.ASKMARCEL_BROWSER_PROFILE;
@@ -12245,9 +12252,20 @@ var cleanupSingletonLocks = async (dir, fs) => {
     await fs.deleteIfExists(join(dir, name));
   }
 };
+var stripProxyEnv = () => {
+  for (const k of PROXY_ENV_KEYS)
+    delete process.env[k];
+};
+var createPlaywrightApi = (loader) => ({
+  launchPersistentContext: async (profileDir, options) => {
+    stripProxyEnv();
+    const { chromium } = await loader();
+    return chromium.launchPersistentContext(profileDir, options);
+  }
+});
 var createBrowserAuthFromApi = (api, config) => {
   const { logger, fs } = config;
-  const trace = config.trace ?? ((m) => process.stderr.write(m));
+  const trace = config.trace ?? (() => {});
   const profileDir = config.profileDir ?? defaultProfileDir();
   const initialSettleMs = config.initialSettleMs ?? 5000;
   const postReloginSettleMs = config.postReloginSettleMs ?? 3000;
@@ -12255,6 +12273,21 @@ var createBrowserAuthFromApi = (api, config) => {
   const pollDeadlineMs = config.pollDeadlineMs ?? 5 * 60 * 1000;
   const navigationTimeoutMs = config.navigationTimeoutMs ?? 30000;
   let context = null;
+  let page = null;
+  const cleanup = async () => {
+    if (page) {
+      try {
+        await page.close();
+      } catch {}
+      page = null;
+    }
+    if (context) {
+      try {
+        await context.close();
+      } catch {}
+      context = null;
+    }
+  };
   const launchContext = async () => {
     for (const channel of ["msedge", "chrome"]) {
       try {
@@ -12287,7 +12320,8 @@ var createBrowserAuthFromApi = (api, config) => {
     let capturedAccess = null;
     let capturedRefresh = null;
     context = await launchContext();
-    const page = await context.newPage();
+    page = await context.newPage();
+    const activePage = page;
     const handleResponse = async (response) => {
       if (capturedAccess)
         return;
@@ -12316,14 +12350,14 @@ var createBrowserAuthFromApi = (api, config) => {
 `);
       } catch {}
     };
-    page.on("response", (r) => {
+    activePage.on("response", (r) => {
       handleResponse(r);
     });
     logger.info("browser_navigating", { url: startUrl });
     trace(`[DEBUG] navigating to: ${startUrl}
 `);
     try {
-      await page.goto(startUrl, { waitUntil: "domcontentloaded", timeout: navigationTimeoutMs });
+      await activePage.goto(startUrl, { waitUntil: "domcontentloaded", timeout: navigationTimeoutMs });
       logger.info("browser_navigated", { url: startUrl });
     } catch (navError) {
       const navMsg = navError instanceof Error ? navError.message : String(navError);
@@ -12331,56 +12365,45 @@ var createBrowserAuthFromApi = (api, config) => {
 `);
       logger.info("browser_navigation_error", { message: navMsg });
     }
-    const cleanup = async () => {
-      try {
-        await page.close();
-      } catch {}
-      try {
-        if (context)
-          await context.close();
-      } catch {}
-      context = null;
-    };
-    await sleep(initialSettleMs);
-    if (capturedAccess) {
-      trace(`[DEBUG] token captured during initial settle
+    const tryReturnCaptured = async (label) => {
+      if (!capturedAccess)
+        return null;
+      trace(`[DEBUG] ${label}
 `);
       await cleanup();
       return { accessToken: capturedAccess, refreshToken: capturedRefresh };
-    }
-    const currentUrl = page.url();
+    };
+    await sleep(initialSettleMs);
+    const settleResult = await tryReturnCaptured("token captured during initial settle");
+    if (settleResult)
+      return settleResult;
+    const currentUrl = activePage.url();
     if (!currentUrl.includes("login.microsoftonline.com") && !currentUrl.includes("login.live.com")) {
       trace(`[DEBUG] already signed in — clearing session to force fresh login
 `);
       logger.info("browser_force_relogin", { url: currentUrl });
       await context.clearCookies();
       try {
-        await page.evaluate(() => {
+        await activePage.evaluate(() => {
           localStorage.clear();
           sessionStorage.clear();
         });
       } catch {}
       try {
-        await page.goto(startUrl, { waitUntil: "domcontentloaded", timeout: navigationTimeoutMs });
+        await activePage.goto(startUrl, { waitUntil: "domcontentloaded", timeout: navigationTimeoutMs });
       } catch {}
       await sleep(postReloginSettleMs);
-      if (capturedAccess) {
-        trace(`[DEBUG] token captured after force relogin
-`);
-        await cleanup();
-        return { accessToken: capturedAccess, refreshToken: capturedRefresh };
-      }
+      const reloginResult = await tryReturnCaptured("token captured after force relogin");
+      if (reloginResult)
+        return reloginResult;
     }
     trace(`[DEBUG] complete sign-in in the browser window — waiting up to 5 min
 `);
     const deadline = Date.now() + pollDeadlineMs;
     while (Date.now() < deadline) {
-      if (capturedAccess) {
-        trace(`[DEBUG] token found in polling loop, closing browser
-`);
-        await cleanup();
-        return { accessToken: capturedAccess, refreshToken: capturedRefresh };
-      }
+      const polledResult = await tryReturnCaptured("token found in polling loop, closing browser");
+      if (polledResult)
+        return polledResult;
       await sleep(pollIntervalMs);
     }
     trace(`[DEBUG] polling loop timeout expired, no token captured
@@ -12390,29 +12413,12 @@ var createBrowserAuthFromApi = (api, config) => {
   };
   const close = async () => {
     logger.info("browser_auth_close");
-    if (context) {
-      try {
-        await context.close();
-      } catch {}
-      context = null;
-    }
+    await cleanup();
   };
   return { acquireToken, close };
 };
 var defaultFileSystem = () => typeof globalThis.Bun !== "undefined" ? createBunFileSystem() : createNodeFileSystem();
-var createBrowserAuth = (deps) => {
-  const api = {
-    launchPersistentContext: async (profileDir, options) => {
-      for (const k of ["HTTP_PROXY", "HTTPS_PROXY", "http_proxy", "https_proxy"]) {
-        delete process.env[k];
-      }
-      const { chromium } = await import("playwright");
-      const ctx = await chromium.launchPersistentContext(profileDir, options);
-      return ctx;
-    }
-  };
-  return createBrowserAuthFromApi(api, { logger: deps.logger, fs: deps.fs ?? defaultFileSystem() });
-};
+var createBrowserAuth = (deps) => createBrowserAuthFromApi(createPlaywrightApi(loadPlaywright), { logger: deps.logger, fs: deps.fs ?? defaultFileSystem() });
 
 // src/infra/auth.ts
 var CLIENT_ID = "5e3ce6c0-2b1f-4285-8d4b-75ee78787346";
@@ -12499,39 +12505,97 @@ var defaultFileSystem2 = () => typeof globalThis.Bun !== "undefined" ? createBun
 var createAuthManager = (deps) => createAuthManagerFromApi(createBrowserAuth({ logger: deps.logger, fs: deps.fs ?? defaultFileSystem2() }), deps.cachePath, deps.logger, deps.fs ?? defaultFileSystem2());
 
 // src/infra/graph-client.ts
+var isJson = (contentType) => contentType !== null && contentType.toLowerCase().includes("application/json");
+var isText = (contentType) => {
+  if (contentType === null)
+    return false;
+  const lower = contentType.toLowerCase();
+  return lower.startsWith("text/") || lower.includes("+xml") || lower.includes("application/xml") || lower.includes("application/javascript");
+};
+var toBase64 = (bytes) => {
+  let binary = "";
+  for (const byte of bytes)
+    binary += String.fromCharCode(byte);
+  return btoa(binary);
+};
+var networkErrorMessage = (e) => {
+  if (e instanceof Error)
+    return e.message;
+  if (typeof e === "string")
+    return e;
+  return "network request failed";
+};
 var createGraphClient = (auth, fetchFn = globalThis.fetch) => {
-  const get = async (path) => {
+  const authHeaders = async () => {
     const tokenResult = await auth.getAccessToken();
     if (!tokenResult.ok) {
       const msg = tokenResult.error.type === "auth_cancelled" ? "Auth cancelled" : tokenResult.error.message;
       return err({ type: "auth_failed", message: msg });
     }
+    return ok({ Authorization: `Bearer ${tokenResult.value}` });
+  };
+  const request = async (method, path, body) => {
+    const headers = await authHeaders();
+    if (!headers.ok)
+      return headers;
     try {
       const res = await fetchFn(`https://graph.microsoft.com/v1.0${path}`, {
-        headers: { Authorization: `Bearer ${tokenResult.value}`, "content-type": "application/json" }
+        method,
+        headers: { ...headers.value, "content-type": "application/json" },
+        ...body === undefined ? {} : { body: JSON.stringify(body) }
       });
       if (!res.ok) {
-        const body = await res.json().catch(() => ({}));
-        return err({ type: "api_error", status: res.status, message: body.error?.message ?? res.statusText });
+        const errBody = await res.json().catch(() => ({}));
+        return err({ type: "api_error", status: res.status, message: errBody.error?.message ?? res.statusText });
       }
       return ok(await res.json());
     } catch (e) {
-      let msg;
-      if (e instanceof Error)
-        msg = e.message;
-      else if (typeof e === "string")
-        msg = e;
-      else
-        msg = "network request failed";
-      return err({ type: "network_error", message: msg });
+      return err({ type: "network_error", message: networkErrorMessage(e) });
+    }
+  };
+  const getBinary = async (path) => {
+    const headers = await authHeaders();
+    if (!headers.ok)
+      return headers;
+    try {
+      const res = await fetchFn(`https://graph.microsoft.com/v1.0${path}`, {
+        method: "GET",
+        headers: headers.value,
+        redirect: "manual"
+      });
+      if (res.status >= 300 && res.status < 400) {
+        const location = res.headers.get("location");
+        if (location !== null)
+          return ok({ "@microsoft.graph.downloadUrl": location });
+      }
+      if (!res.ok) {
+        const errBody = await res.json().catch(() => ({}));
+        return err({ type: "api_error", status: res.status, message: errBody.error?.message ?? res.statusText });
+      }
+      const contentType = res.headers.get("content-type");
+      if (isJson(contentType))
+        return ok(await res.json());
+      if (isText(contentType)) {
+        const text = await res.text();
+        return ok({ contentType: contentType ?? "text/plain", size: text.length, text });
+      }
+      const buffer = await res.arrayBuffer();
+      return ok({ contentType: contentType ?? "application/octet-stream", size: buffer.byteLength, base64: toBase64(new Uint8Array(buffer)) });
+    } catch (e) {
+      return err({ type: "network_error", message: networkErrorMessage(e) });
     }
   };
-  return { get };
+  return {
+    get: (path) => request("GET", path),
+    post: (path, body) => request("POST", path, body),
+    getBinary
+  };
 };
 
 // src/infra/logger.ts
 var import_winston = __toESM(require_winston(), 1);
 var REDACTED_KEYS = new Set(["password", "token", "authorization", "apikey", "secret"]);
+var ALL_LEVELS = ["error", "warn", "info", "http", "verbose", "debug", "silly"];
 var redactFormat = import_winston.format((info) => {
   for (const key of Object.keys(info)) {
     if (REDACTED_KEYS.has(key.toLowerCase()))
@@ -12541,9 +12605,9 @@ var redactFormat = import_winston.format((info) => {
 });
 var createWinstonLogger = (config = {}) => {
   const winston = import_winston.createLogger({
-    level: config.logLevel ?? process.env.LOG_LEVEL ?? "info",
+    level: config.logLevel ?? process.env.ASKMARCEL_LOG_LEVEL ?? "error",
     format: import_winston.format.combine(redactFormat(), import_winston.format.json()),
-    transports: [new import_winston.transports.Console]
+    transports: [new import_winston.transports.Console({ stderrLevels: ALL_LEVELS })]
   });
   return {
     info: (event, meta) => winston.info(event, meta),
@@ -12552,18 +12616,47 @@ var createWinstonLogger = (config = {}) => {
   };
 };
 
+// src/infra/process-runner-bun.ts
+var createBunProcessRunner = () => ({
+  runInherit: async (command, args) => {
+    try {
+      const proc = Bun.spawn([command, ...args], { stdio: ["inherit", "inherit", "inherit"] });
+      const exitCode = await proc.exited;
+      return ok({ exitCode });
+    } catch (e) {
+      return err({ type: "spawn_failed", message: formatError(e) });
+    }
+  }
+});
+
+// src/infra/process-runner-node.ts
+import { spawn } from "node:child_process";
+var createNodeProcessRunner = () => ({
+  runInherit: async (command, args) => new Promise((resolve) => {
+    try {
+      const child = spawn(command, [...args], { stdio: "inherit" });
+      child.on("exit", (exitCode) => resolve(ok({ exitCode: exitCode ?? 0 })));
+      child.on("error", (e) => resolve(err({ type: "spawn_failed", message: formatError(e) })));
+    } catch (e) {
+      resolve(err({ type: "spawn_failed", message: formatError(e) }));
+    }
+  })
+});
+
 // src/composition/build-deps.ts
 var defaultCachePath = (home) => join2(home, ".ask-marcel", "token-cache.json");
 var defaultFileSystem3 = () => typeof globalThis.Bun !== "undefined" ? createBunFileSystem() : createNodeFileSystem();
+var defaultProcessRunner = () => typeof globalThis.Bun !== "undefined" ? createBunProcessRunner() : createNodeProcessRunner();
 var buildDeps = (config = {}) => {
   const home = config.home ?? process.env.HOME ?? process.env.USERPROFILE ?? "";
   const cachePath = config.cachePath ?? defaultCachePath(home);
-  const logLevel = config.logLevel ?? process.env.LOG_LEVEL ?? "info";
+  const logLevel = config.logLevel ?? process.env.ASKMARCEL_LOG_LEVEL ?? "error";
   const fs = config.fs ?? defaultFileSystem3();
+  const processRunner = config.processRunner ?? defaultProcessRunner();
   const logger = createWinstonLogger({ logLevel });
   const auth = createAuthManager({ cachePath, logger, fs });
   const graph = createGraphClient(auth);
-  return { logger, auth, graph };
+  return { logger, auth, graph, processRunner };
 };
 
 // node_modules/commander/esm.mjs
@@ -12594,10 +12687,73 @@ var renderError = (message, logger) => {
 `);
 };
 
-// src/use-cases/commands/download-onedrive-file-content.ts
-var exports_download_onedrive_file_content = {};
-__export(exports_download_onedrive_file_content, {
+// src/use-cases/commands/docs-render.ts
+var CATEGORY_LABELS = {
+  auth: "Authentication",
+  drive: "OneDrive Files",
+  excel: "Excel (workbook files)",
+  sharepoint: "SharePoint Sites",
+  tasks: "Tasks (To Do + Planner)",
+  mail: "Mail",
+  notes: "Notes (OneNote)",
+  user: "User",
+  calendar: "Calendar",
+  contacts: "Contacts",
+  chats: "Chats",
+  teams: "Teams",
+  meta: "Meta / Pagination"
+};
+var CATEGORY_ORDER = ["drive", "excel", "sharepoint", "tasks", "mail", "notes", "user", "calendar", "contacts", "chats", "teams", "meta"];
+var renderCommandMarkdown = (entry) => {
+  const lines = [
+    `# \`${entry.name}\``,
+    "",
+    entry.summary,
+    "",
+    `- **Category:** ${CATEGORY_LABELS[entry.category]}`,
+    `- **Graph endpoint:** \`${entry.graphMethod} ${entry.graphPathTemplate}\``,
+    `- **Microsoft Learn:** ${entry.graphDocsUrl}`
+  ];
+  if (entry.responseShape)
+    lines.push(`- **Response:** ${entry.responseShape}`);
+  if (entry.options.length > 0) {
+    lines.push("", "## Options", "");
+    lines.push("| Flag | Description |", "|------|-------------|");
+    for (const o of entry.options)
+      lines.push(`| \`--${o.name}\` | ${o.description} |`);
+  }
+  if (entry.bodyTemplate)
+    lines.push("", "## Request body", "", "```json", entry.bodyTemplate, "```");
+  lines.push("", "## Example", "", "```bash", entry.example, "```");
+  return lines.join(`
+`);
+};
+
+// src/use-cases/commands/docs.ts
+var toEntry = (name, cmd) => ({
+  name,
+  summary: cmd.meta.summary,
+  category: cmd.meta.category,
+  graphMethod: cmd.meta.graphMethod,
+  graphPathTemplate: cmd.meta.graphPathTemplate,
+  graphDocsUrl: cmd.meta.graphDocsUrl,
+  options: cmd.meta.options,
+  example: cmd.meta.example,
+  ...cmd.meta.responseShape ? { responseShape: cmd.meta.responseShape } : {},
+  ...cmd.meta.bodyTemplate ? { bodyTemplate: cmd.meta.bodyTemplate } : {}
+});
+var renderSingleCommand = (registry, name) => {
+  const cmd = registry[name];
+  if (!cmd)
+    return err({ type: "unknown_command", name, available: Object.keys(registry).toSorted((a, b) => a.localeCompare(b)) });
+  return ok(renderCommandMarkdown(toEntry(name, cmd)));
+};
+
+// src/use-cases/commands/download-drive-item-version-content.ts
+var exports_download_drive_item_version_content = {};
+__export(exports_download_drive_item_version_content, {
   schema: () => schema,
+  meta: () => meta3,
   execute: () => execute
 });
 
@@ -26133,798 +26289,1829 @@ function date4(params) {
 
 // node_modules/zod/v4/classic/external.js
 config(en_default());
-// src/use-cases/commands/download-onedrive-file-content.ts
-var schema = exports_external.object({ driveId: exports_external.string().min(1), itemId: exports_external.string().min(1) });
+// src/use-cases/commands/download-drive-item-version-content.ts
+var schema = exports_external.object({
+  driveId: exports_external.string().min(1),
+  itemId: exports_external.string().min(1),
+  versionId: exports_external.string().min(1)
+});
 var execute = async (graph, params) => {
   const parsed = schema.safeParse(params);
   if (!parsed.success)
     throw new Error(`validation failed: ${parsed.error.message}`);
-  return graph.get(`/drives/${parsed.data.driveId}/items/${parsed.data.itemId}/content`);
+  return graph.getBinary(`/drives/${parsed.data.driveId}/items/${parsed.data.itemId}/versions/${parsed.data.versionId}/content`);
+};
+var meta3 = {
+  summary: '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).',
+  category: "drive",
+  graphMethod: "GET",
+  graphPathTemplate: "/drives/{drive-id}/items/{item-id}/versions/{version-id}/content",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/driveitemversion-get-content",
+  options: [
+    {
+      name: "drive-id",
+      key: "driveId",
+      required: true,
+      description: "Microsoft Graph drive ID. Use `ask-marcel list-drives` for the personal OneDrive, " + "or `ask-marcel list-sharepoint-site-drives --site-id <id>` for a SharePoint document library."
+    },
+    { name: "item-id", key: "itemId", required: true, description: "driveItem ID of the file. Returned by `list-folder-files` or `search-onedrive-files`." },
+    {
+      name: "version-id",
+      key: "versionId",
+      required: true,
+      description: "driveItemVersion ID. Returned by `ask-marcel list-drive-item-versions`. Use the `id` field of an entry under `value[]`. " + "Pick a non-current version — the first entry (e.g. `12.0`) is the live file and Graph rejects this endpoint for it; use `value[1]` or older."
+    }
+  ],
+  example: "ask-marcel download-drive-item-version-content --drive-id 'b!1234' --item-id '01ABC' --version-id '4.0'",
+  responseShape: '`{ "@microsoft.graph.downloadUrl": "..." }` for the typical 302 case, or `{ contentType, size, base64 }` when Graph streams bytes directly'
+};
+
+// src/use-cases/commands/download-onedrive-file-content.ts
+var exports_download_onedrive_file_content = {};
+__export(exports_download_onedrive_file_content, {
+  schema: () => schema2,
+  meta: () => meta4,
+  execute: () => execute2
+});
+var schema2 = exports_external.object({ driveId: exports_external.string().min(1), itemId: exports_external.string().min(1) });
+var execute2 = async (graph, params) => {
+  const parsed = schema2.safeParse(params);
+  if (!parsed.success)
+    throw new Error(`validation failed: ${parsed.error.message}`);
+  return graph.getBinary(`/drives/${parsed.data.driveId}/items/${parsed.data.itemId}/content`);
+};
+var meta4 = {
+  summary: "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.",
+  category: "drive",
+  graphMethod: "GET",
+  graphPathTemplate: "/drives/{drive-id}/items/{item-id}/content",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/driveitem-get-content",
+  options: [
+    { name: "drive-id", key: "driveId", required: true, description: "Microsoft Graph drive ID. Returned by `ask-marcel list-drives`." },
+    { name: "item-id", key: "itemId", required: true, description: "driveItem ID of the file to download. Returned by `ask-marcel list-folder-files` or `search-onedrive-files`." }
+  ],
+  example: "ask-marcel download-onedrive-file-content --drive-id 'b!1234' --item-id '01ABC'",
+  responseShape: '`{ "@microsoft.graph.downloadUrl": "..." }` for the typical 302 case, or `{ contentType, size, base64 }` when Graph streams bytes directly'
 };
 
 // src/use-cases/commands/get-calendar-event.ts
 var exports_get_calendar_event = {};
 __export(exports_get_calendar_event, {
-  schema: () => schema2,
-  execute: () => execute2
+  schema: () => schema3,
+  meta: () => meta5,
+  execute: () => execute3
 });
 
 // src/use-cases/commands/build-command.ts
-var buildCommand = (pathFn, schema2) => {
-  const execute2 = async (graph, params) => {
-    const parsed = schema2.safeParse(params);
+var buildCommand = (pathFn, schema3) => {
+  const execute3 = async (graph, params) => {
+    const parsed = schema3.safeParse(params);
     if (!parsed.success)
       throw new Error(`validation failed: ${parsed.error.message}`);
     const path = pathFn(parsed.data);
     return graph.get(path);
   };
-  return { schema: schema2, execute: execute2 };
+  return { schema: schema3, execute: execute3 };
 };
 
 // src/use-cases/commands/get-calendar-event.ts
-var schema2 = exports_external.object({ eventId: exports_external.string().min(1) });
-var { execute: execute2 } = buildCommand((p) => `/me/events/${p.eventId}`, schema2);
+var schema3 = exports_external.object({ eventId: exports_external.string().min(1) });
+var { execute: execute3 } = buildCommand((p) => `/me/events/${p.eventId}`, schema3);
+var meta5 = {
+  summary: "Fetch a single calendar event by ID from the signed-in user’s default calendar.",
+  category: "calendar",
+  graphMethod: "GET",
+  graphPathTemplate: "/me/events/{event-id}",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/event-get",
+  options: [
+    {
+      name: "event-id",
+      key: "eventId",
+      required: true,
+      description: "Microsoft Graph event ID. Returned by `ask-marcel list-calendar-events` in the `id` field of each event."
+    }
+  ],
+  example: "ask-marcel get-calendar-event --event-id 'AAMkAGI2THVS...'",
+  responseShape: "single Microsoft Graph `event` resource"
+};
 
 // src/use-cases/commands/get-calendar-view.ts
 var exports_get_calendar_view = {};
 __export(exports_get_calendar_view, {
-  schema: () => schema3,
-  execute: () => execute3
-});
-var schema3 = exports_external.object({}).strict();
-var { execute: execute3 } = buildCommand(() => "/me/calendarView", schema3);
-
-// src/use-cases/commands/get-channel-files-folder.ts
-var exports_get_channel_files_folder = {};
-__export(exports_get_channel_files_folder, {
   schema: () => schema4,
+  meta: () => meta6,
   execute: () => execute4
 });
-var schema4 = exports_external.object({ teamId: exports_external.string().min(1), channelId: exports_external.string().min(1) });
-var { execute: execute4 } = buildCommand((p) => `/teams/${p.teamId}/channels/${p.channelId}/filesFolder`, schema4);
-
-// src/use-cases/commands/get-channel-message-hosted-content.ts
-var exports_get_channel_message_hosted_content = {};
-__export(exports_get_channel_message_hosted_content, {
-  schema: () => schema5,
-  execute: () => execute5
-});
-var schema5 = exports_external.object({ teamId: exports_external.string().min(1), channelId: exports_external.string().min(1), chatMessageId: exports_external.string().min(1), chatMessageHostedContentId: exports_external.string().min(1) });
-var { execute: execute5 } = buildCommand((p) => `/teams/${p.teamId}/channels/${p.channelId}/messages/${p.chatMessageId}/hostedContents/${p.chatMessageHostedContentId}/$value`, schema5);
-
-// src/use-cases/commands/get-channel-message.ts
-var exports_get_channel_message = {};
-__export(exports_get_channel_message, {
-  schema: () => schema6,
-  execute: () => execute6
-});
-var schema6 = exports_external.object({ teamId: exports_external.string().min(1), channelId: exports_external.string().min(1), chatMessageId: exports_external.string().min(1) });
-var { execute: execute6 } = buildCommand((p) => `/teams/${p.teamId}/channels/${p.channelId}/messages/${p.chatMessageId}`, schema6);
-
-// src/use-cases/commands/get-chat-message-hosted-content.ts
-var exports_get_chat_message_hosted_content = {};
-__export(exports_get_chat_message_hosted_content, {
-  schema: () => schema7,
-  execute: () => execute7
-});
-var schema7 = exports_external.object({ chatId: exports_external.string().min(1), chatMessageId: exports_external.string().min(1), chatMessageHostedContentId: exports_external.string().min(1) });
-var { execute: execute7 } = buildCommand((p) => `/chats/${p.chatId}/messages/${p.chatMessageId}/hostedContents/${p.chatMessageHostedContentId}/$value`, schema7);
-
-// src/use-cases/commands/get-chat-message.ts
-var exports_get_chat_message = {};
-__export(exports_get_chat_message, {
-  schema: () => schema8,
-  execute: () => execute8
-});
-var schema8 = exports_external.object({ chatId: exports_external.string().min(1), chatMessageId: exports_external.string().min(1) });
-var { execute: execute8 } = buildCommand((p) => `/chats/${p.chatId}/messages/${p.chatMessageId}`, schema8);
-
-// src/use-cases/commands/get-chat.ts
-var exports_get_chat = {};
-__export(exports_get_chat, {
-  schema: () => schema9,
-  execute: () => execute9
-});
-var schema9 = exports_external.object({ chatId: exports_external.string().min(1) });
-var { execute: execute9 } = buildCommand((p) => `/chats/${p.chatId}`, schema9);
+var schema4 = exports_external.object({
+  startDateTime: exports_external.string().min(1),
+  endDateTime: exports_external.string().min(1)
+});
+var { execute: execute4 } = buildCommand((p) => `/me/calendarView?startDateTime=${p.startDateTime}&endDateTime=${p.endDateTime}`, schema4);
+var meta6 = {
+  summary: "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.",
+  category: "calendar",
+  graphMethod: "GET",
+  graphPathTemplate: "/me/calendarView?startDateTime={start-date-time}&endDateTime={end-date-time}",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/user-list-calendarview",
+  options: [
+    {
+      name: "start-date-time",
+      key: "startDateTime",
+      required: true,
+      description: "ISO 8601 lower bound (UTC). Example: `2026-04-01T00:00:00Z`. Required by Graph; the request fails without it."
+    },
+    {
+      name: "end-date-time",
+      key: "endDateTime",
+      required: true,
+      description: "ISO 8601 upper bound (UTC). Example: `2026-05-01T00:00:00Z`. Required by Graph; the request fails without it."
+    }
+  ],
+  example: "ask-marcel get-calendar-view --start-date-time '2026-04-01T00:00:00Z' --end-date-time '2026-05-01T00:00:00Z'",
+  responseShape: "collection of Microsoft Graph `event` resources (single occurrences) under `value[]`"
+};
 
 // src/use-cases/commands/get-current-user.ts
 var exports_get_current_user = {};
 __export(exports_get_current_user, {
-  schema: () => schema10,
-  execute: () => execute10
+  schema: () => schema5,
+  meta: () => meta7,
+  execute: () => execute5
 });
-var schema10 = exports_external.object({}).strict();
-var { execute: execute10 } = buildCommand(() => "/me", schema10);
+var schema5 = exports_external.object({}).strict();
+var { execute: execute5 } = buildCommand(() => "/me", schema5);
+var meta7 = {
+  summary: "Return the signed-in user’s Microsoft Graph profile (id, displayName, mail, jobTitle, etc.).",
+  category: "user",
+  graphMethod: "GET",
+  graphPathTemplate: "/me",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/user-get",
+  options: [],
+  example: "ask-marcel get-current-user",
+  responseShape: "single Microsoft Graph `user` resource"
+};
 
 // src/use-cases/commands/get-drive-delta.ts
 var exports_get_drive_delta = {};
 __export(exports_get_drive_delta, {
-  schema: () => schema11,
-  execute: () => execute11
+  schema: () => schema6,
+  meta: () => meta8,
+  execute: () => execute6
 });
-var schema11 = exports_external.object({ driveId: exports_external.string().min(1), itemId: exports_external.string().min(1) });
-var { execute: execute11 } = buildCommand((p) => `/drives/${p.driveId}/items/${p.itemId}/delta()`, schema11);
+var schema6 = exports_external.object({ driveId: exports_external.string().min(1), itemId: exports_external.string().min(1) });
+var { execute: execute6 } = buildCommand((p) => `/drives/${p.driveId}/items/${p.itemId}/delta()`, schema6);
+var meta8 = {
+  summary: "Get the incremental change set (added / modified / deleted items) under a OneDrive / SharePoint folder. Use the `@odata.deltaLink` from a previous response to resume.",
+  category: "drive",
+  graphMethod: "GET",
+  graphPathTemplate: "/drives/{drive-id}/items/{item-id}/delta()",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/driveitem-delta",
+  options: [
+    { name: "drive-id", key: "driveId", required: true, description: "Microsoft Graph drive ID. Returned by `ask-marcel list-drives`." },
+    {
+      name: "item-id",
+      key: "itemId",
+      required: true,
+      description: "driveItem ID of the folder whose subtree to track. Use the root folder ID from `get-drive-root-item` to track the entire drive."
+    }
+  ],
+  example: "ask-marcel get-drive-delta --drive-id 'b!1234' --item-id '01ROOT'",
+  responseShape: "collection of changed Microsoft Graph `driveItem` resources under `value[]` plus an `@odata.deltaLink` token"
+};
 
 // src/use-cases/commands/get-drive-item.ts
 var exports_get_drive_item = {};
 __export(exports_get_drive_item, {
-  schema: () => schema12,
-  execute: () => execute12
+  schema: () => schema7,
+  meta: () => meta9,
+  execute: () => execute7
 });
-var schema12 = exports_external.object({ driveId: exports_external.string().min(1), itemId: exports_external.string().min(1) });
-var { execute: execute12 } = buildCommand((p) => `/drives/${p.driveId}/items/${p.itemId}`, schema12);
+var schema7 = exports_external.object({ driveId: exports_external.string().min(1), itemId: exports_external.string().min(1) });
+var { execute: execute7 } = buildCommand((p) => `/drives/${p.driveId}/items/${p.itemId}`, schema7);
+var meta9 = {
+  summary: "Get the metadata (driveItem resource) of a single file or folder in OneDrive / SharePoint.",
+  category: "drive",
+  graphMethod: "GET",
+  graphPathTemplate: "/drives/{drive-id}/items/{item-id}",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/driveitem-get",
+  options: [
+    { name: "drive-id", key: "driveId", required: true, description: "Microsoft Graph drive ID. Returned by `ask-marcel list-drives`." },
+    { name: "item-id", key: "itemId", required: true, description: "driveItem ID. Returned by `list-folder-files`, `search-onedrive-files`, or `get-drive-root-item`." }
+  ],
+  example: "ask-marcel get-drive-item --drive-id 'b!1234' --item-id '01ABC'",
+  responseShape: "single Microsoft Graph `driveItem` resource"
+};
 
 // src/use-cases/commands/get-drive-root-item.ts
 var exports_get_drive_root_item = {};
 __export(exports_get_drive_root_item, {
-  schema: () => schema13,
-  execute: () => execute13
+  schema: () => schema8,
+  meta: () => meta10,
+  execute: () => execute8
 });
-var schema13 = exports_external.object({ driveId: exports_external.string().min(1) });
-var { execute: execute13 } = buildCommand((p) => `/drives/${p.driveId}/root`, schema13);
+var schema8 = exports_external.object({ driveId: exports_external.string().min(1) });
+var { execute: execute8 } = buildCommand((p) => `/drives/${p.driveId}/root`, schema8);
+var meta10 = {
+  summary: "Get the root folder (driveItem) of a OneDrive / SharePoint drive.",
+  category: "drive",
+  graphMethod: "GET",
+  graphPathTemplate: "/drives/{drive-id}/root",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/driveitem-get",
+  options: [{ name: "drive-id", key: "driveId", required: true, description: "Microsoft Graph drive ID. Returned by `ask-marcel list-drives` in the `id` field." }],
+  example: "ask-marcel get-drive-root-item --drive-id 'b!1234'",
+  responseShape: "single Microsoft Graph `driveItem` resource (the root folder)"
+};
 
 // src/use-cases/commands/get-excel-range.ts
 var exports_get_excel_range = {};
 __export(exports_get_excel_range, {
-  schema: () => schema14,
-  execute: () => execute14
+  schema: () => schema9,
+  meta: () => meta11,
+  execute: () => execute9
 });
-var schema14 = exports_external.object({ driveId: exports_external.string().min(1), itemId: exports_external.string().min(1), worksheetId: exports_external.string().min(1), address: exports_external.string().min(1) });
-var { execute: execute14 } = buildCommand((p) => `/drives/${p.driveId}/items/${p.itemId}/workbook/worksheets/${p.worksheetId}/range(address='${p.address}')`, schema14);
+var schema9 = exports_external.object({ driveId: exports_external.string().min(1), itemId: exports_external.string().min(1), worksheetId: exports_external.string().min(1), address: exports_external.string().min(1) });
+var { execute: execute9 } = buildCommand((p) => `/drives/${p.driveId}/items/${p.itemId}/workbook/worksheets/${p.worksheetId}/range(address='${p.address}')`, schema9);
+var meta11 = {
+  summary: "Get the cell values, formulas, and formats of a specific Excel range (e.g. `A1:C10`).",
+  category: "excel",
+  graphMethod: "GET",
+  graphPathTemplate: "/drives/{drive-id}/items/{item-id}/workbook/worksheets/{worksheet-id}/range(address='{address}')",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/worksheet-range",
+  options: [
+    { name: "drive-id", key: "driveId", required: true, description: "Microsoft Graph drive ID containing the workbook. Returned by `ask-marcel list-drives`." },
+    { name: "item-id", key: "itemId", required: true, description: "driveItem ID of the .xlsx file." },
+    { name: "worksheet-id", key: "worksheetId", required: true, description: "Worksheet ID or worksheet name. Returned by `ask-marcel list-excel-worksheets`." },
+    { name: "address", key: "address", required: true, description: "A1-style range address, e.g. `A1:C10` or a single cell like `B7`." }
+  ],
+  example: "ask-marcel get-excel-range --drive-id 'b!1234' --item-id '01XLSX' --worksheet-id 'Sheet1' --address 'A1:C10'",
+  responseShape: "single Microsoft Graph `workbookRange` resource (values, formulas, format)"
+};
 
 // src/use-cases/commands/get-excel-table.ts
 var exports_get_excel_table = {};
 __export(exports_get_excel_table, {
-  schema: () => schema15,
-  execute: () => execute15
+  schema: () => schema10,
+  meta: () => meta12,
+  execute: () => execute10
 });
-var schema15 = exports_external.object({ driveId: exports_external.string().min(1), itemId: exports_external.string().min(1), tableId: exports_external.string().min(1) });
-var { execute: execute15 } = buildCommand((p) => `/drives/${p.driveId}/items/${p.itemId}/workbook/tables/${p.tableId}`, schema15);
+var schema10 = exports_external.object({ driveId: exports_external.string().min(1), itemId: exports_external.string().min(1), tableId: exports_external.string().min(1) });
+var { execute: execute10 } = buildCommand((p) => `/drives/${p.driveId}/items/${p.itemId}/workbook/tables/${p.tableId}`, schema10);
+var meta12 = {
+  summary: "Get the metadata (style, header row, total row) of a single named Excel table.",
+  category: "excel",
+  graphMethod: "GET",
+  graphPathTemplate: "/drives/{drive-id}/items/{item-id}/workbook/tables/{table-id}",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/workbooktable-get",
+  options: [
+    { name: "drive-id", key: "driveId", required: true, description: "Microsoft Graph drive ID containing the workbook. Returned by `ask-marcel list-drives`." },
+    { name: "item-id", key: "itemId", required: true, description: "driveItem ID of the .xlsx file." },
+    { name: "table-id", key: "tableId", required: true, description: "Workbook table ID or table name. Returned by `ask-marcel list-excel-tables`." }
+  ],
+  example: "ask-marcel get-excel-table --drive-id 'b!1234' --item-id '01XLSX' --table-id 'Table1'",
+  responseShape: "single Microsoft Graph `workbookTable` resource"
+};
 
 // src/use-cases/commands/get-mail-attachment.ts
 var exports_get_mail_attachment = {};
 __export(exports_get_mail_attachment, {
-  schema: () => schema16,
-  execute: () => execute16
+  schema: () => schema11,
+  meta: () => meta13,
+  execute: () => execute11
 });
-var schema16 = exports_external.object({ messageId: exports_external.string().min(1), attachmentId: exports_external.string().min(1) });
-var { execute: execute16 } = buildCommand((p) => `/me/messages/${p.messageId}/attachments/${p.attachmentId}`, schema16);
+var schema11 = exports_external.object({ messageId: exports_external.string().min(1), attachmentId: exports_external.string().min(1) });
+var { execute: execute11 } = buildCommand((p) => `/me/messages/${p.messageId}/attachments/${p.attachmentId}`, schema11);
+var meta13 = {
+  summary: "Get a single attachment on an Outlook message (metadata, plus the base64 `contentBytes` for file attachments).",
+  category: "mail",
+  graphMethod: "GET",
+  graphPathTemplate: "/me/messages/{message-id}/attachments/{attachment-id}",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/attachment-get",
+  options: [
+    { name: "message-id", key: "messageId", required: true, description: "Outlook message ID. Returned by `ask-marcel list-mail-messages`." },
+    { name: "attachment-id", key: "attachmentId", required: true, description: "Attachment ID. Returned by `ask-marcel list-mail-attachments`." }
+  ],
+  example: "ask-marcel get-mail-attachment --message-id 'AAMkAGI2...' --attachment-id 'AAMkABC...'",
+  responseShape: "single Microsoft Graph `attachment` resource"
+};
 
 // src/use-cases/commands/get-mail-message.ts
 var exports_get_mail_message = {};
 __export(exports_get_mail_message, {
-  schema: () => schema17,
-  execute: () => execute17
+  schema: () => schema12,
+  meta: () => meta14,
+  execute: () => execute12
 });
-var schema17 = exports_external.object({ messageId: exports_external.string().min(1) });
-var { execute: execute17 } = buildCommand((p) => `/me/messages/${p.messageId}`, schema17);
+var schema12 = exports_external.object({ messageId: exports_external.string().min(1) });
+var { execute: execute12 } = buildCommand((p) => `/me/messages/${p.messageId}`, schema12);
+var meta14 = {
+  summary: "Get a single Outlook message by ID, including subject, sender, body, and flags.",
+  category: "mail",
+  graphMethod: "GET",
+  graphPathTemplate: "/me/messages/{message-id}",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/message-get",
+  options: [
+    { name: "message-id", key: "messageId", required: true, description: "Outlook message ID. Returned by `ask-marcel list-mail-messages` or `list-mail-folder-messages`." }
+  ],
+  example: "ask-marcel get-mail-message --message-id 'AAMkAGI2...'",
+  responseShape: "single Microsoft Graph `message` resource"
+};
 
 // src/use-cases/commands/get-mailbox-settings.ts
 var exports_get_mailbox_settings = {};
 __export(exports_get_mailbox_settings, {
-  schema: () => schema18,
-  execute: () => execute18
+  schema: () => schema13,
+  meta: () => meta15,
+  execute: () => execute13
 });
-var schema18 = exports_external.object({}).strict();
-var { execute: execute18 } = buildCommand(() => "/me/mailboxSettings", schema18);
+var schema13 = exports_external.object({}).strict();
+var { execute: execute13 } = buildCommand(() => "/me/mailboxSettings", schema13);
+var meta15 = {
+  summary: "Get the signed-in user’s Outlook mailbox settings (timezone, working hours, automatic replies).",
+  category: "mail",
+  graphMethod: "GET",
+  graphPathTemplate: "/me/mailboxSettings",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/user-get-mailboxsettings",
+  options: [],
+  example: "ask-marcel get-mailbox-settings",
+  responseShape: "single Microsoft Graph `mailboxSettings` resource"
+};
 
 // src/use-cases/commands/get-my-profile-photo.ts
 var exports_get_my_profile_photo = {};
 __export(exports_get_my_profile_photo, {
-  schema: () => schema19,
-  execute: () => execute19
+  schema: () => schema14,
+  meta: () => meta16,
+  execute: () => execute14
 });
-var schema19 = exports_external.object({}).strict();
-var { execute: execute19 } = buildCommand(() => "/me/photo/$value", schema19);
+var schema14 = exports_external.object({}).strict();
+var execute14 = async (graph, params) => {
+  const parsed = schema14.safeParse(params);
+  if (!parsed.success)
+    throw new Error(`validation failed: ${parsed.error.message}`);
+  return graph.getBinary("/me/photo/$value");
+};
+var meta16 = {
+  summary: "Download the signed-in user’s profile photo (largest available size). Returned as a base64 envelope so the binary survives JSON output.",
+  category: "user",
+  graphMethod: "GET",
+  graphPathTemplate: "/me/photo/$value",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/profilephoto-get",
+  options: [],
+  example: "ask-marcel get-my-profile-photo",
+  responseShape: '`{ contentType: "image/jpeg", size: <bytes>, base64: "<encoded>" }` (or `{ "@microsoft.graph.downloadUrl": "..." }` when Graph returns a 302 redirect to a CDN URL)'
+};
 
 // src/use-cases/commands/get-onenote-page-content.ts
 var exports_get_onenote_page_content = {};
 __export(exports_get_onenote_page_content, {
-  schema: () => schema20,
-  execute: () => execute20
-});
-var schema20 = exports_external.object({ onenotePageId: exports_external.string().min(1) });
-var { execute: execute20 } = buildCommand((p) => `/me/onenote/pages/${p.onenotePageId}/content`, schema20);
-
-// src/use-cases/commands/get-outlook-contact.ts
-var exports_get_outlook_contact = {};
-__export(exports_get_outlook_contact, {
-  schema: () => schema21,
-  execute: () => execute21
+  schema: () => schema15,
+  meta: () => meta17,
+  execute: () => execute15
 });
-var schema21 = exports_external.object({ contactId: exports_external.string().min(1) });
-var { execute: execute21 } = buildCommand((p) => `/me/contacts/${p.contactId}`, schema21);
+var schema15 = exports_external.object({ onenotePageId: exports_external.string().min(1) });
+var execute15 = async (graph, params) => {
+  const parsed = schema15.safeParse(params);
+  if (!parsed.success)
+    throw new Error(`validation failed: ${parsed.error.message}`);
+  return graph.getBinary(`/me/onenote/pages/${parsed.data.onenotePageId}/content`);
+};
+var meta17 = {
+  summary: "Get the HTML body of a single OneNote page. Returned in a JSON envelope so the HTML survives transport.",
+  category: "notes",
+  graphMethod: "GET",
+  graphPathTemplate: "/me/onenote/pages/{onenote-page-id}/content",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/page-get",
+  options: [{ name: "onenote-page-id", key: "onenotePageId", required: true, description: "OneNote page ID. Returned by `ask-marcel list-onenote-section-pages`." }],
+  example: "ask-marcel get-onenote-page-content --onenote-page-id '1-abc...'",
+  responseShape: '`{ contentType: "text/html", size: <chars>, text: "<html>..." }` — the rendered OneNote page body wrapped in a JSON envelope'
+};
 
 // src/use-cases/commands/get-planner-bucket.ts
 var exports_get_planner_bucket = {};
 __export(exports_get_planner_bucket, {
-  schema: () => schema22,
-  execute: () => execute22
+  schema: () => schema16,
+  meta: () => meta18,
+  execute: () => execute16
 });
-var schema22 = exports_external.object({ plannerBucketId: exports_external.string().min(1) });
-var { execute: execute22 } = buildCommand((p) => `/planner/buckets/${p.plannerBucketId}`, schema22);
+var schema16 = exports_external.object({ plannerBucketId: exports_external.string().min(1) });
+var { execute: execute16 } = buildCommand((p) => `/planner/buckets/${p.plannerBucketId}`, schema16);
+var meta18 = {
+  summary: "Get the metadata of a single Microsoft Planner bucket (column / lane).",
+  category: "tasks",
+  graphMethod: "GET",
+  graphPathTemplate: "/planner/buckets/{planner-bucket-id}",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/plannerbucket-get",
+  options: [{ name: "planner-bucket-id", key: "plannerBucketId", required: true, description: "Planner bucket ID. Returned by `ask-marcel list-plan-buckets`." }],
+  example: "ask-marcel get-planner-bucket --planner-bucket-id 'sFNeQRFu_kqhxpwwAhmA15gAGfoT'",
+  responseShape: "single Microsoft Graph `plannerBucket` resource"
+};
 
 // src/use-cases/commands/get-planner-plan.ts
 var exports_get_planner_plan = {};
 __export(exports_get_planner_plan, {
-  schema: () => schema23,
-  execute: () => execute23
+  schema: () => schema17,
+  meta: () => meta19,
+  execute: () => execute17
 });
-var schema23 = exports_external.object({ plannerPlanId: exports_external.string().min(1) });
-var { execute: execute23 } = buildCommand((p) => `/planner/plans/${p.plannerPlanId}`, schema23);
+var schema17 = exports_external.object({ plannerPlanId: exports_external.string().min(1) });
+var { execute: execute17 } = buildCommand((p) => `/planner/plans/${p.plannerPlanId}`, schema17);
+var meta19 = {
+  summary: "Get the metadata of a single Microsoft Planner plan (title, owner group, container).",
+  category: "tasks",
+  graphMethod: "GET",
+  graphPathTemplate: "/planner/plans/{planner-plan-id}",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/plannerplan-get",
+  options: [
+    {
+      name: "planner-plan-id",
+      key: "plannerPlanId",
+      required: true,
+      description: "Planner plan ID. Returned in the `planId` field of any task from `ask-marcel list-planner-tasks`."
+    }
+  ],
+  example: "ask-marcel get-planner-plan --planner-plan-id 'xqQg5FS2LkCp935s-FIFm5gAB6'",
+  responseShape: "single Microsoft Graph `plannerPlan` resource"
+};
 
 // src/use-cases/commands/get-planner-task-details.ts
 var exports_get_planner_task_details = {};
 __export(exports_get_planner_task_details, {
-  schema: () => schema24,
-  execute: () => execute24
+  schema: () => schema18,
+  meta: () => meta20,
+  execute: () => execute18
 });
-var schema24 = exports_external.object({ plannerTaskId: exports_external.string().min(1) });
-var { execute: execute24 } = buildCommand((p) => `/planner/tasks/${p.plannerTaskId}/details`, schema24);
+var schema18 = exports_external.object({ plannerTaskId: exports_external.string().min(1) });
+var { execute: execute18 } = buildCommand((p) => `/planner/tasks/${p.plannerTaskId}/details`, schema18);
+var meta20 = {
+  summary: "Get the rich details (description, checklist, references) of a Microsoft Planner task.",
+  category: "tasks",
+  graphMethod: "GET",
+  graphPathTemplate: "/planner/tasks/{planner-task-id}/details",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/plannertaskdetails-get",
+  options: [{ name: "planner-task-id", key: "plannerTaskId", required: true, description: "Planner task ID. Returned by `ask-marcel list-planner-tasks` or `list-plan-tasks`." }],
+  example: "ask-marcel get-planner-task-details --planner-task-id '01tx7Ic7-USXEwt0lvR1cmgAH8gK'",
+  responseShape: "single Microsoft Graph `plannerTaskDetails` resource"
+};
 
 // src/use-cases/commands/get-planner-task.ts
 var exports_get_planner_task = {};
 __export(exports_get_planner_task, {
-  schema: () => schema25,
-  execute: () => execute25
+  schema: () => schema19,
+  meta: () => meta21,
+  execute: () => execute19
 });
-var schema25 = exports_external.object({ plannerTaskId: exports_external.string().min(1) });
-var { execute: execute25 } = buildCommand((p) => `/planner/tasks/${p.plannerTaskId}`, schema25);
+var schema19 = exports_external.object({ plannerTaskId: exports_external.string().min(1) });
+var { execute: execute19 } = buildCommand((p) => `/planner/tasks/${p.plannerTaskId}`, schema19);
+var meta21 = {
+  summary: "Get the metadata of a single Microsoft Planner task (title, assignees, dates, completion).",
+  category: "tasks",
+  graphMethod: "GET",
+  graphPathTemplate: "/planner/tasks/{planner-task-id}",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/plannertask-get",
+  options: [{ name: "planner-task-id", key: "plannerTaskId", required: true, description: "Planner task ID. Returned by `ask-marcel list-planner-tasks` or `list-plan-tasks`." }],
+  example: "ask-marcel get-planner-task --planner-task-id '01tx7Ic7-USXEwt0lvR1cmgAH8gK'",
+  responseShape: "single Microsoft Graph `plannerTask` resource"
+};
 
 // src/use-cases/commands/get-sharepoint-site-by-path.ts
 var exports_get_sharepoint_site_by_path = {};
 __export(exports_get_sharepoint_site_by_path, {
-  schema: () => schema26,
-  execute: () => execute26
+  schema: () => schema20,
+  meta: () => meta22,
+  execute: () => execute20
 });
-var schema26 = exports_external.object({ siteId: exports_external.string().min(1), path: exports_external.string().min(1) });
-var { execute: execute26 } = buildCommand((p) => `/sites/${p.siteId}/getByPath(path='${p.path}')`, schema26);
+var schema20 = exports_external.object({
+  hostname: exports_external.string().min(1),
+  path: exports_external.string().min(1).refine((v) => v.startsWith("/"), { message: "must start with `/` (server-relative path, e.g. /sites/Marketing)" })
+});
+var { execute: execute20 } = buildCommand((p) => `/sites/${p.hostname}:${p.path}`, schema20);
+var meta22 = {
+  summary: "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.",
+  category: "sharepoint",
+  graphMethod: "GET",
+  graphPathTemplate: "/sites/{hostname}:{path}",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/site-get",
+  options: [
+    {
+      name: "hostname",
+      key: "hostname",
+      required: true,
+      description: "SharePoint host, e.g. `contoso.sharepoint.com` (or `contoso-my.sharepoint.com` for personal sites). Take the host portion of your SharePoint URL."
+    },
+    {
+      name: "path",
+      key: "path",
+      required: true,
+      description: "Server-relative path starting with `/`, e.g. `/sites/Marketing` or `/teams/Marketing/Subsite`. Take the URL pathname after the hostname."
+    }
+  ],
+  example: "ask-marcel get-sharepoint-site-by-path --hostname 'contoso.sharepoint.com' --path '/sites/Marketing'",
+  responseShape: "single Microsoft Graph `site` resource"
+};
 
 // src/use-cases/commands/get-sharepoint-site-drive-by-id.ts
 var exports_get_sharepoint_site_drive_by_id = {};
 __export(exports_get_sharepoint_site_drive_by_id, {
-  schema: () => schema27,
-  execute: () => execute27
-});
-var schema27 = exports_external.object({ siteId: exports_external.string().min(1), driveId: exports_external.string().min(1) });
-var { execute: execute27 } = buildCommand((p) => `/sites/${p.siteId}/drives/${p.driveId}`, schema27);
-
-// src/use-cases/commands/get-sharepoint-site-item.ts
-var exports_get_sharepoint_site_item = {};
-__export(exports_get_sharepoint_site_item, {
-  schema: () => schema28,
-  execute: () => execute28
+  schema: () => schema21,
+  meta: () => meta23,
+  execute: () => execute21
 });
-var schema28 = exports_external.object({ siteId: exports_external.string().min(1), baseItemId: exports_external.string().min(1) });
-var { execute: execute28 } = buildCommand((p) => `/sites/${p.siteId}/items/${p.baseItemId}`, schema28);
+var schema21 = exports_external.object({ siteId: exports_external.string().min(1), driveId: exports_external.string().min(1) });
+var { execute: execute21 } = buildCommand((p) => `/sites/${p.siteId}/drives/${p.driveId}`, schema21);
+var meta23 = {
+  summary: "Get the metadata of a single document library (drive) on a SharePoint site by drive ID.",
+  category: "sharepoint",
+  graphMethod: "GET",
+  graphPathTemplate: "/sites/{site-id}/drives/{drive-id}",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/drive-get",
+  options: [
+    { name: "site-id", key: "siteId", required: true, description: "SharePoint site ID. Returned by `ask-marcel search-sharepoint-sites`." },
+    { name: "drive-id", key: "driveId", required: true, description: "Drive (document library) ID on the site. Returned by `ask-marcel list-sharepoint-site-drives`." }
+  ],
+  example: "ask-marcel get-sharepoint-site-drive-by-id --site-id 'contoso.sharepoint.com,1234,5678' --drive-id 'b!abcd'",
+  responseShape: "single Microsoft Graph `drive` resource"
+};
 
 // src/use-cases/commands/get-sharepoint-site-list-item.ts
 var exports_get_sharepoint_site_list_item = {};
 __export(exports_get_sharepoint_site_list_item, {
-  schema: () => schema29,
-  execute: () => execute29
+  schema: () => schema22,
+  meta: () => meta24,
+  execute: () => execute22
 });
-var schema29 = exports_external.object({ siteId: exports_external.string().min(1), listId: exports_external.string().min(1), listItemId: exports_external.string().min(1) });
-var { execute: execute29 } = buildCommand((p) => `/sites/${p.siteId}/lists/${p.listId}/items/${p.listItemId}`, schema29);
+var schema22 = exports_external.object({ siteId: exports_external.string().min(1), listId: exports_external.string().min(1), listItemId: exports_external.string().min(1) });
+var { execute: execute22 } = buildCommand((p) => `/sites/${p.siteId}/lists/${p.listId}/items/${p.listItemId}`, schema22);
+var meta24 = {
+  summary: "Get a single row (listItem) of a SharePoint list by ID.",
+  category: "sharepoint",
+  graphMethod: "GET",
+  graphPathTemplate: "/sites/{site-id}/lists/{list-id}/items/{list-item-id}",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/listitem-get",
+  options: [
+    { name: "site-id", key: "siteId", required: true, description: "SharePoint site ID. Returned by `ask-marcel search-sharepoint-sites`." },
+    { name: "list-id", key: "listId", required: true, description: "SharePoint list ID or display name. Returned by `ask-marcel list-sharepoint-site-lists`." },
+    { name: "list-item-id", key: "listItemId", required: true, description: "listItem ID (typically a small integer). Returned by `ask-marcel list-sharepoint-site-list-items`." }
+  ],
+  example: "ask-marcel get-sharepoint-site-list-item --site-id 'contoso.sharepoint.com,1234,5678' --list-id 'Tasks' --list-item-id '7'",
+  responseShape: "single Microsoft Graph `listItem` resource"
+};
 
 // src/use-cases/commands/get-sharepoint-site-list.ts
 var exports_get_sharepoint_site_list = {};
 __export(exports_get_sharepoint_site_list, {
-  schema: () => schema30,
-  execute: () => execute30
+  schema: () => schema23,
+  meta: () => meta25,
+  execute: () => execute23
 });
-var schema30 = exports_external.object({ siteId: exports_external.string().min(1), listId: exports_external.string().min(1) });
-var { execute: execute30 } = buildCommand((p) => `/sites/${p.siteId}/lists/${p.listId}`, schema30);
+var schema23 = exports_external.object({ siteId: exports_external.string().min(1), listId: exports_external.string().min(1) });
+var { execute: execute23 } = buildCommand((p) => `/sites/${p.siteId}/lists/${p.listId}`, schema23);
+var meta25 = {
+  summary: "Get the metadata (display name, template, columns) of a single SharePoint list.",
+  category: "sharepoint",
+  graphMethod: "GET",
+  graphPathTemplate: "/sites/{site-id}/lists/{list-id}",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/list-get",
+  options: [
+    { name: "site-id", key: "siteId", required: true, description: "SharePoint site ID. Returned by `ask-marcel search-sharepoint-sites`." },
+    { name: "list-id", key: "listId", required: true, description: "SharePoint list ID or display name. Returned by `ask-marcel list-sharepoint-site-lists`." }
+  ],
+  example: "ask-marcel get-sharepoint-site-list --site-id 'contoso.sharepoint.com,1234,5678' --list-id 'Documents'",
+  responseShape: "single Microsoft Graph `list` resource"
+};
 
 // src/use-cases/commands/get-sharepoint-site.ts
 var exports_get_sharepoint_site = {};
 __export(exports_get_sharepoint_site, {
-  schema: () => schema31,
-  execute: () => execute31
-});
-var schema31 = exports_external.object({ siteId: exports_external.string().min(1) });
-var { execute: execute31 } = buildCommand((p) => `/sites/${p.siteId}`, schema31);
-
-// src/use-cases/commands/get-sharepoint-sites-delta.ts
-var exports_get_sharepoint_sites_delta = {};
-__export(exports_get_sharepoint_sites_delta, {
-  schema: () => schema32,
-  execute: () => execute32
+  schema: () => schema24,
+  meta: () => meta26,
+  execute: () => execute24
 });
-var schema32 = exports_external.object({}).strict();
-var { execute: execute32 } = buildCommand(() => "/sites/delta()", schema32);
+var schema24 = exports_external.object({ siteId: exports_external.string().min(1) });
+var { execute: execute24 } = buildCommand((p) => `/sites/${p.siteId}`, schema24);
+var meta26 = {
+  summary: "Get the metadata of a single SharePoint site by its site ID.",
+  category: "sharepoint",
+  graphMethod: "GET",
+  graphPathTemplate: "/sites/{site-id}",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/site-get",
+  options: [
+    {
+      name: "site-id",
+      key: "siteId",
+      required: true,
+      description: "SharePoint site ID. Either the composite ID (`hostname,site-collection-id,site-id`) returned by `ask-marcel search-sharepoint-sites`, or the literal `root` to refer to the tenant root site."
+    }
+  ],
+  example: "ask-marcel get-sharepoint-site --site-id 'contoso.sharepoint.com,1234,5678'",
+  responseShape: "single Microsoft Graph `site` resource"
+};
 
 // src/use-cases/commands/get-specific-calendar-event.ts
 var exports_get_specific_calendar_event = {};
 __export(exports_get_specific_calendar_event, {
-  schema: () => schema33,
-  execute: () => execute33
+  schema: () => schema25,
+  meta: () => meta27,
+  execute: () => execute25
 });
-var schema33 = exports_external.object({ calendarId: exports_external.string().min(1), eventId: exports_external.string().min(1) });
-var { execute: execute33 } = buildCommand((p) => `/me/calendars/${p.calendarId}/events/${p.eventId}`, schema33);
+var schema25 = exports_external.object({ calendarId: exports_external.string().min(1), eventId: exports_external.string().min(1) });
+var { execute: execute25 } = buildCommand((p) => `/me/calendars/${p.calendarId}/events/${p.eventId}`, schema25);
+var meta27 = {
+  summary: "Fetch a single calendar event by ID from a specific (non-default) calendar.",
+  category: "calendar",
+  graphMethod: "GET",
+  graphPathTemplate: "/me/calendars/{calendar-id}/events/{event-id}",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/event-get",
+  options: [
+    { name: "calendar-id", key: "calendarId", required: true, description: "Calendar ID. Returned by `ask-marcel list-calendars`." },
+    { name: "event-id", key: "eventId", required: true, description: "Event ID. Returned by `ask-marcel list-specific-calendar-events`." }
+  ],
+  example: "ask-marcel get-specific-calendar-event --calendar-id 'AAMkAGI2THVS...' --event-id 'AAMkABC...'",
+  responseShape: "single Microsoft Graph `event` resource"
+};
 
 // src/use-cases/commands/get-specific-calendar-view.ts
 var exports_get_specific_calendar_view = {};
 __export(exports_get_specific_calendar_view, {
-  schema: () => schema34,
-  execute: () => execute34
+  schema: () => schema26,
+  meta: () => meta28,
+  execute: () => execute26
 });
-var schema34 = exports_external.object({ calendarId: exports_external.string().min(1) });
-var { execute: execute34 } = buildCommand((p) => `/me/calendars/${p.calendarId}/calendarView`, schema34);
+var schema26 = exports_external.object({
+  calendarId: exports_external.string().min(1),
+  startDateTime: exports_external.string().min(1),
+  endDateTime: exports_external.string().min(1)
+});
+var { execute: execute26 } = buildCommand((p) => `/me/calendars/${p.calendarId}/calendarView?startDateTime=${p.startDateTime}&endDateTime=${p.endDateTime}`, schema26);
+var meta28 = {
+  summary: "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.",
+  category: "calendar",
+  graphMethod: "GET",
+  graphPathTemplate: "/me/calendars/{calendar-id}/calendarView?startDateTime={start-date-time}&endDateTime={end-date-time}",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/calendar-list-calendarview",
+  options: [
+    { name: "calendar-id", key: "calendarId", required: true, description: "Calendar ID. Returned by `ask-marcel list-calendars`." },
+    {
+      name: "start-date-time",
+      key: "startDateTime",
+      required: true,
+      description: "ISO 8601 lower bound (UTC). Example: `2026-04-01T00:00:00Z`. Required by Graph; the request fails without it."
+    },
+    {
+      name: "end-date-time",
+      key: "endDateTime",
+      required: true,
+      description: "ISO 8601 upper bound (UTC). Example: `2026-05-01T00:00:00Z`. Required by Graph; the request fails without it."
+    }
+  ],
+  example: "ask-marcel get-specific-calendar-view --calendar-id 'AAMkAGI2THVS...' --start-date-time '2026-04-01T00:00:00Z' --end-date-time '2026-05-01T00:00:00Z'",
+  responseShape: "collection of Microsoft Graph `event` resources (single occurrences) under `value[]`"
+};
 
 // src/use-cases/commands/get-team-channel.ts
 var exports_get_team_channel = {};
 __export(exports_get_team_channel, {
-  schema: () => schema35,
-  execute: () => execute35
+  schema: () => schema27,
+  meta: () => meta29,
+  execute: () => execute27
 });
-var schema35 = exports_external.object({ teamId: exports_external.string().min(1), channelId: exports_external.string().min(1) });
-var { execute: execute35 } = buildCommand((p) => `/teams/${p.teamId}/channels/${p.channelId}`, schema35);
+var schema27 = exports_external.object({ teamId: exports_external.string().min(1), channelId: exports_external.string().min(1) });
+var { execute: execute27 } = buildCommand((p) => `/teams/${p.teamId}/channels/${p.channelId}`, schema27);
+var meta29 = {
+  summary: "Get the metadata of a single channel inside a Microsoft Team.",
+  category: "teams",
+  graphMethod: "GET",
+  graphPathTemplate: "/teams/{team-id}/channels/{channel-id}",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/channel-get",
+  options: [
+    { name: "team-id", key: "teamId", required: true, description: "Microsoft Teams team ID. Returned by `ask-marcel list-joined-teams`." },
+    { name: "channel-id", key: "channelId", required: true, description: "Channel ID. Returned by `ask-marcel list-team-channels`." }
+  ],
+  example: "ask-marcel get-team-channel --team-id 'abc-1234-...' --channel-id '19:def@thread.tacv2'",
+  responseShape: "single Microsoft Graph `channel` resource"
+};
 
 // src/use-cases/commands/get-team.ts
 var exports_get_team = {};
 __export(exports_get_team, {
-  schema: () => schema36,
-  execute: () => execute36
+  schema: () => schema28,
+  meta: () => meta30,
+  execute: () => execute28
 });
-var schema36 = exports_external.object({ teamId: exports_external.string().min(1) });
-var { execute: execute36 } = buildCommand((p) => `/teams/${p.teamId}`, schema36);
+var schema28 = exports_external.object({ teamId: exports_external.string().min(1) });
+var { execute: execute28 } = buildCommand((p) => `/teams/${p.teamId}`, schema28);
+var meta30 = {
+  summary: "Get the metadata of a single Microsoft Team (display name, settings, member-settings, owner group).",
+  category: "teams",
+  graphMethod: "GET",
+  graphPathTemplate: "/teams/{team-id}",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/team-get",
+  options: [{ name: "team-id", key: "teamId", required: true, description: "Microsoft Teams team ID. Returned by `ask-marcel list-joined-teams`." }],
+  example: "ask-marcel get-team --team-id 'abc-1234-...'",
+  responseShape: "single Microsoft Graph `team` resource"
+};
 
 // src/use-cases/commands/get-todo-task.ts
 var exports_get_todo_task = {};
 __export(exports_get_todo_task, {
-  schema: () => schema37,
-  execute: () => execute37
+  schema: () => schema29,
+  meta: () => meta31,
+  execute: () => execute29
 });
-var schema37 = exports_external.object({ todoTaskListId: exports_external.string().min(1), todoTaskId: exports_external.string().min(1) });
-var { execute: execute37 } = buildCommand((p) => `/me/todo/lists/${p.todoTaskListId}/tasks/${p.todoTaskId}`, schema37);
+var schema29 = exports_external.object({ todoTaskListId: exports_external.string().min(1), todoTaskId: exports_external.string().min(1) });
+var { execute: execute29 } = buildCommand((p) => `/me/todo/lists/${p.todoTaskListId}/tasks/${p.todoTaskId}`, schema29);
+var meta31 = {
+  summary: "Get a single Microsoft To Do task by its ID and its parent list ID.",
+  category: "tasks",
+  graphMethod: "GET",
+  graphPathTemplate: "/me/todo/lists/{todo-task-list-id}/tasks/{todo-task-id}",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/todotask-get",
+  options: [
+    { name: "todo-task-list-id", key: "todoTaskListId", required: true, description: "To Do task list ID. Returned by `ask-marcel list-todo-task-lists`." },
+    { name: "todo-task-id", key: "todoTaskId", required: true, description: "To Do task ID. Returned by `ask-marcel list-todo-tasks`." }
+  ],
+  example: "ask-marcel get-todo-task --todo-task-list-id 'AAMkAGI...' --todo-task-id 'AAMkABC...'",
+  responseShape: "single Microsoft Graph `todoTask` resource"
+};
 
 // src/use-cases/commands/list-all-onenote-sections.ts
 var exports_list_all_onenote_sections = {};
 __export(exports_list_all_onenote_sections, {
-  schema: () => schema38,
-  execute: () => execute38
+  schema: () => schema30,
+  meta: () => meta32,
+  execute: () => execute30
 });
-var schema38 = exports_external.object({}).strict();
-var { execute: execute38 } = buildCommand(() => "/me/onenote/sections", schema38);
+var schema30 = exports_external.object({}).strict();
+var { execute: execute30 } = buildCommand(() => "/me/onenote/sections", schema30);
+var meta32 = {
+  summary: "List every OneNote section the signed-in user can see, across all notebooks.",
+  category: "notes",
+  graphMethod: "GET",
+  graphPathTemplate: "/me/onenote/sections",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/onenote-list-sections",
+  options: [],
+  example: "ask-marcel list-all-onenote-sections",
+  responseShape: "collection of Microsoft Graph `onenoteSection` resources under `value[]`"
+};
 
 // src/use-cases/commands/list-calendar-event-instances.ts
 var exports_list_calendar_event_instances = {};
 __export(exports_list_calendar_event_instances, {
-  schema: () => schema39,
-  execute: () => execute39
+  schema: () => schema31,
+  meta: () => meta33,
+  execute: () => execute31
 });
-var schema39 = exports_external.object({ calendarId: exports_external.string().min(1), eventId: exports_external.string().min(1) });
-var { execute: execute39 } = buildCommand((p) => `/me/calendars/${p.calendarId}/events/${p.eventId}/instances`, schema39);
+var schema31 = exports_external.object({
+  calendarId: exports_external.string().min(1),
+  eventId: exports_external.string().min(1),
+  startDateTime: exports_external.string().min(1),
+  endDateTime: exports_external.string().min(1)
+});
+var { execute: execute31 } = buildCommand((p) => `/me/calendars/${p.calendarId}/events/${p.eventId}/instances?startDateTime=${p.startDateTime}&endDateTime=${p.endDateTime}`, schema31);
+var meta33 = {
+  summary: "List the individual occurrences of a recurring calendar event over a date range. Both ISO date-time params are required by Graph.",
+  category: "calendar",
+  graphMethod: "GET",
+  graphPathTemplate: "/me/calendars/{calendar-id}/events/{event-id}/instances?startDateTime={start-date-time}&endDateTime={end-date-time}",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/event-list-instances",
+  options: [
+    { name: "calendar-id", key: "calendarId", required: true, description: "Calendar ID. Returned by `ask-marcel list-calendars`." },
+    { name: "event-id", key: "eventId", required: true, description: "Recurring event ID. Returned by `ask-marcel list-specific-calendar-events`." },
+    {
+      name: "start-date-time",
+      key: "startDateTime",
+      required: true,
+      description: "ISO 8601 lower bound (UTC). Example: `2026-04-01T00:00:00Z`. Required by Graph; the request fails without it."
+    },
+    {
+      name: "end-date-time",
+      key: "endDateTime",
+      required: true,
+      description: "ISO 8601 upper bound (UTC). Example: `2026-05-01T00:00:00Z`. Required by Graph; the request fails without it."
+    }
+  ],
+  example: "ask-marcel list-calendar-event-instances --calendar-id 'AAMkAGI2THVS...' --event-id 'AAMkABC...' --start-date-time '2026-04-01T00:00:00Z' --end-date-time '2026-05-01T00:00:00Z'",
+  responseShape: "collection of Microsoft Graph `event` resources (single occurrences) under `value[]`"
+};
 
 // src/use-cases/commands/list-calendar-events-delta.ts
 var exports_list_calendar_events_delta = {};
 __export(exports_list_calendar_events_delta, {
-  schema: () => schema40,
-  execute: () => execute40
+  schema: () => schema32,
+  meta: () => meta34,
+  execute: () => execute32
 });
-var schema40 = exports_external.object({}).strict();
-var { execute: execute40 } = buildCommand(() => "/me/events/delta()", schema40);
+var schema32 = exports_external.object({}).strict();
+var { execute: execute32 } = buildCommand(() => "/me/events/delta()", schema32);
+var meta34 = {
+  summary: "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.",
+  category: "calendar",
+  graphMethod: "GET",
+  graphPathTemplate: "/me/events/delta()",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/event-delta",
+  options: [],
+  example: "ask-marcel list-calendar-events-delta",
+  responseShape: "collection of changed Microsoft Graph `event` resources under `value[]` plus an `@odata.deltaLink` token"
+};
 
 // src/use-cases/commands/list-calendar-events.ts
 var exports_list_calendar_events = {};
 __export(exports_list_calendar_events, {
-  schema: () => schema41,
-  execute: () => execute41
+  schema: () => schema33,
+  meta: () => meta35,
+  execute: () => execute33
 });
-var schema41 = exports_external.object({}).strict();
-var { execute: execute41 } = buildCommand(() => "/me/events", schema41);
+var schema33 = exports_external.object({}).strict();
+var { execute: execute33 } = buildCommand(() => "/me/events", schema33);
+var meta35 = {
+  summary: "List the events in the signed-in user’s default calendar (does not expand recurrences).",
+  category: "calendar",
+  graphMethod: "GET",
+  graphPathTemplate: "/me/events",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/user-list-events",
+  options: [],
+  example: "ask-marcel list-calendar-events",
+  responseShape: "collection of Microsoft Graph `event` resources under `value[]`"
+};
 
 // src/use-cases/commands/list-calendar-view-delta.ts
 var exports_list_calendar_view_delta = {};
 __export(exports_list_calendar_view_delta, {
-  schema: () => schema42,
-  execute: () => execute42
+  schema: () => schema34,
+  meta: () => meta36,
+  execute: () => execute34
 });
-var schema42 = exports_external.object({}).strict();
-var { execute: execute42 } = buildCommand(() => "/me/calendarView/delta()", schema42);
+var schema34 = exports_external.object({
+  startDateTime: exports_external.string().min(1),
+  endDateTime: exports_external.string().min(1)
+});
+var { execute: execute34 } = buildCommand((p) => `/me/calendarView/delta()?startDateTime=${p.startDateTime}&endDateTime=${p.endDateTime}`, schema34);
+var meta36 = {
+  summary: "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`.",
+  category: "calendar",
+  graphMethod: "GET",
+  graphPathTemplate: "/me/calendarView/delta()?startDateTime={start-date-time}&endDateTime={end-date-time}",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/event-delta",
+  options: [
+    {
+      name: "start-date-time",
+      key: "startDateTime",
+      required: true,
+      description: "ISO 8601 lower bound (UTC). Required on the first call only — the deltaLink token encodes it for resumes."
+    },
+    {
+      name: "end-date-time",
+      key: "endDateTime",
+      required: true,
+      description: "ISO 8601 upper bound (UTC). Required on the first call only — the deltaLink token encodes it for resumes."
+    }
+  ],
+  example: "ask-marcel list-calendar-view-delta --start-date-time '2026-04-01T00:00:00Z' --end-date-time '2026-05-01T00:00:00Z'",
+  responseShape: "collection of changed Microsoft Graph `event` occurrences under `value[]` plus an `@odata.deltaLink` token"
+};
 
 // src/use-cases/commands/list-calendars.ts
 var exports_list_calendars = {};
 __export(exports_list_calendars, {
-  schema: () => schema43,
-  execute: () => execute43
-});
-var schema43 = exports_external.object({}).strict();
-var { execute: execute43 } = buildCommand(() => "/me/calendars", schema43);
-
-// src/use-cases/commands/list-channel-message-hosted-contents.ts
-var exports_list_channel_message_hosted_contents = {};
-__export(exports_list_channel_message_hosted_contents, {
-  schema: () => schema44,
-  execute: () => execute44
-});
-var schema44 = exports_external.object({ teamId: exports_external.string().min(1), channelId: exports_external.string().min(1), chatMessageId: exports_external.string().min(1) });
-var { execute: execute44 } = buildCommand((p) => `/teams/${p.teamId}/channels/${p.channelId}/messages/${p.chatMessageId}/hostedContents`, schema44);
-
-// src/use-cases/commands/list-channel-message-replies.ts
-var exports_list_channel_message_replies = {};
-__export(exports_list_channel_message_replies, {
-  schema: () => schema45,
-  execute: () => execute45
-});
-var schema45 = exports_external.object({ teamId: exports_external.string().min(1), channelId: exports_external.string().min(1), chatMessageId: exports_external.string().min(1) });
-var { execute: execute45 } = buildCommand((p) => `/teams/${p.teamId}/channels/${p.channelId}/messages/${p.chatMessageId}/replies`, schema45);
-
-// src/use-cases/commands/list-channel-messages.ts
-var exports_list_channel_messages = {};
-__export(exports_list_channel_messages, {
-  schema: () => schema46,
-  execute: () => execute46
-});
-var schema46 = exports_external.object({ teamId: exports_external.string().min(1), channelId: exports_external.string().min(1) });
-var { execute: execute46 } = buildCommand((p) => `/teams/${p.teamId}/channels/${p.channelId}/messages`, schema46);
-
-// src/use-cases/commands/list-channel-tabs.ts
-var exports_list_channel_tabs = {};
-__export(exports_list_channel_tabs, {
-  schema: () => schema47,
-  execute: () => execute47
+  schema: () => schema35,
+  meta: () => meta37,
+  execute: () => execute35
 });
-var schema47 = exports_external.object({ teamId: exports_external.string().min(1), channelId: exports_external.string().min(1) });
-var { execute: execute47 } = buildCommand((p) => `/teams/${p.teamId}/channels/${p.channelId}/tabs`, schema47);
+var schema35 = exports_external.object({}).strict();
+var { execute: execute35 } = buildCommand(() => "/me/calendars", schema35);
+var meta37 = {
+  summary: "List the calendars in the signed-in user’s mailbox (default + secondary calendars + shared calendars).",
+  category: "calendar",
+  graphMethod: "GET",
+  graphPathTemplate: "/me/calendars",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/user-list-calendars",
+  options: [],
+  example: "ask-marcel list-calendars",
+  responseShape: "collection of Microsoft Graph `calendar` resources under `value[]`"
+};
 
 // src/use-cases/commands/list-chat-members.ts
 var exports_list_chat_members = {};
 __export(exports_list_chat_members, {
-  schema: () => schema48,
-  execute: () => execute48
-});
-var schema48 = exports_external.object({ chatId: exports_external.string().min(1) });
-var { execute: execute48 } = buildCommand((p) => `/chats/${p.chatId}/members`, schema48);
-
-// src/use-cases/commands/list-chat-message-hosted-contents.ts
-var exports_list_chat_message_hosted_contents = {};
-__export(exports_list_chat_message_hosted_contents, {
-  schema: () => schema49,
-  execute: () => execute49
-});
-var schema49 = exports_external.object({ chatId: exports_external.string().min(1), chatMessageId: exports_external.string().min(1) });
-var { execute: execute49 } = buildCommand((p) => `/chats/${p.chatId}/messages/${p.chatMessageId}/hostedContents`, schema49);
-
-// src/use-cases/commands/list-chat-message-replies.ts
-var exports_list_chat_message_replies = {};
-__export(exports_list_chat_message_replies, {
-  schema: () => schema50,
-  execute: () => execute50
-});
-var schema50 = exports_external.object({ chatId: exports_external.string().min(1), chatMessageId: exports_external.string().min(1) });
-var { execute: execute50 } = buildCommand((p) => `/chats/${p.chatId}/messages/${p.chatMessageId}/replies`, schema50);
-
-// src/use-cases/commands/list-chat-messages.ts
-var exports_list_chat_messages = {};
-__export(exports_list_chat_messages, {
-  schema: () => schema51,
-  execute: () => execute51
-});
-var schema51 = exports_external.object({ chatId: exports_external.string().min(1) });
-var { execute: execute51 } = buildCommand((p) => `/chats/${p.chatId}/messages`, schema51);
-
-// src/use-cases/commands/list-chats.ts
-var exports_list_chats = {};
-__export(exports_list_chats, {
-  schema: () => schema52,
-  execute: () => execute52
+  schema: () => schema36,
+  meta: () => meta38,
+  execute: () => execute36
 });
-var schema52 = exports_external.object({}).strict();
-var { execute: execute52 } = buildCommand(() => "/me/chats", schema52);
+var schema36 = exports_external.object({ chatId: exports_external.string().min(1) });
+var { execute: execute36 } = buildCommand((p) => `/chats/${p.chatId}/members`, schema36);
+var meta38 = {
+  summary: "List the members of a single Microsoft Teams chat.",
+  category: "chats",
+  graphMethod: "GET",
+  graphPathTemplate: "/chats/{chat-id}/members",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/chat-list-members",
+  options: [
+    {
+      name: "chat-id",
+      key: "chatId",
+      required: true,
+      description: "Microsoft Teams chat ID, e.g. `19:abc...@thread.v2`. " + "This CLI does not list chats (the Teams web client token has no `Chat.Read*` scope), so the chat ID has to come from outside. " + "Easiest source from inside this CLI: pick any Teams meeting from `list-calendar-events` and URL-decode the " + "`19%3ameeting_...%40thread.v2` segment of its `onlineMeeting.joinUrl`. " + "Other sources: the Teams desktop / web client (Open in browser → URL contains the chat thread ID), Microsoft Graph Explorer, or Power Automate."
+    }
+  ],
+  example: "ask-marcel list-chat-members --chat-id '19:abc...@thread.v2'",
+  responseShape: "collection of Microsoft Graph `conversationMember` resources under `value[]`"
+};
 
 // src/use-cases/commands/list-drive-item-permissions.ts
 var exports_list_drive_item_permissions = {};
 __export(exports_list_drive_item_permissions, {
-  schema: () => schema53,
-  execute: () => execute53
+  schema: () => schema37,
+  meta: () => meta39,
+  execute: () => execute37
 });
-var schema53 = exports_external.object({ driveId: exports_external.string().min(1), itemId: exports_external.string().min(1) });
-var { execute: execute53 } = buildCommand((p) => `/drives/${p.driveId}/items/${p.itemId}/permissions`, schema53);
+var schema37 = exports_external.object({ driveId: exports_external.string().min(1), itemId: exports_external.string().min(1) });
+var { execute: execute37 } = buildCommand((p) => `/drives/${p.driveId}/items/${p.itemId}/permissions`, schema37);
+var meta39 = {
+  summary: "List the sharing permissions on a OneDrive / SharePoint file or folder.",
+  category: "drive",
+  graphMethod: "GET",
+  graphPathTemplate: "/drives/{drive-id}/items/{item-id}/permissions",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/driveitem-list-permissions",
+  options: [
+    { name: "drive-id", key: "driveId", required: true, description: "Microsoft Graph drive ID. Returned by `ask-marcel list-drives`." },
+    {
+      name: "item-id",
+      key: "itemId",
+      required: true,
+      description: "driveItem ID of the file or folder. Returned by `list-folder-files`, `search-onedrive-files`, or `get-drive-item`."
+    }
+  ],
+  example: "ask-marcel list-drive-item-permissions --drive-id 'b!1234' --item-id '01ABC'",
+  responseShape: "collection of Microsoft Graph `permission` resources under `value[]`"
+};
 
 // src/use-cases/commands/list-drive-item-versions.ts
 var exports_list_drive_item_versions = {};
 __export(exports_list_drive_item_versions, {
-  schema: () => schema54,
-  execute: () => execute54
+  schema: () => schema38,
+  meta: () => meta40,
+  execute: () => execute38
 });
-var schema54 = exports_external.object({ driveId: exports_external.string().min(1), itemId: exports_external.string().min(1) });
-var { execute: execute54 } = buildCommand((p) => `/drives/${p.driveId}/items/${p.itemId}/versions`, schema54);
+var schema38 = exports_external.object({ driveId: exports_external.string().min(1), itemId: exports_external.string().min(1) });
+var { execute: execute38 } = buildCommand((p) => `/drives/${p.driveId}/items/${p.itemId}/versions`, schema38);
+var meta40 = {
+  summary: "List the historical versions of a OneDrive / SharePoint file (each save creates a new version).",
+  category: "drive",
+  graphMethod: "GET",
+  graphPathTemplate: "/drives/{drive-id}/items/{item-id}/versions",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/driveitem-list-versions",
+  options: [
+    {
+      name: "drive-id",
+      key: "driveId",
+      required: true,
+      description: "Microsoft Graph drive ID. Use `ask-marcel list-drives` for the personal OneDrive, " + "or `ask-marcel list-sharepoint-site-drives --site-id <id>` for a SharePoint document library."
+    },
+    { name: "item-id", key: "itemId", required: true, description: "driveItem ID of the file. Returned by `list-folder-files` or `search-onedrive-files`." }
+  ],
+  example: "ask-marcel list-drive-item-versions --drive-id 'b!1234' --item-id '01ABC'",
+  responseShape: "collection of Microsoft Graph `driveItemVersion` resources under `value[]`"
+};
 
 // src/use-cases/commands/list-drives.ts
 var exports_list_drives = {};
 __export(exports_list_drives, {
-  schema: () => schema55,
-  execute: () => execute55
+  schema: () => schema39,
+  meta: () => meta41,
+  execute: () => execute39
 });
-var schema55 = exports_external.object({}).strict();
-var { execute: execute55 } = buildCommand(() => "/me/drives", schema55);
+var schema39 = exports_external.object({}).strict();
+var { execute: execute39 } = buildCommand(() => "/me/drives", schema39);
+var meta41 = {
+  summary: "List all OneDrive / SharePoint drives the signed-in user has access to.",
+  category: "drive",
+  graphMethod: "GET",
+  graphPathTemplate: "/me/drives",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/drive-list",
+  options: [],
+  example: "ask-marcel list-drives",
+  responseShape: "collection of Microsoft Graph `drive` resources under `value[]`"
+};
 
 // src/use-cases/commands/list-excel-table-rows.ts
 var exports_list_excel_table_rows = {};
 __export(exports_list_excel_table_rows, {
-  schema: () => schema56,
-  execute: () => execute56
+  schema: () => schema40,
+  meta: () => meta42,
+  execute: () => execute40
 });
-var schema56 = exports_external.object({ driveId: exports_external.string().min(1), itemId: exports_external.string().min(1), tableId: exports_external.string().min(1) });
-var { execute: execute56 } = buildCommand((p) => `/drives/${p.driveId}/items/${p.itemId}/workbook/tables/${p.tableId}/rows`, schema56);
+var schema40 = exports_external.object({ driveId: exports_external.string().min(1), itemId: exports_external.string().min(1), tableId: exports_external.string().min(1) });
+var { execute: execute40 } = buildCommand((p) => `/drives/${p.driveId}/items/${p.itemId}/workbook/tables/${p.tableId}/rows`, schema40);
+var meta42 = {
+  summary: "List the data rows of a named Excel table (excluding the header row).",
+  category: "excel",
+  graphMethod: "GET",
+  graphPathTemplate: "/drives/{drive-id}/items/{item-id}/workbook/tables/{table-id}/rows",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/workbooktable-list-rows",
+  options: [
+    { name: "drive-id", key: "driveId", required: true, description: "Microsoft Graph drive ID containing the workbook. Returned by `ask-marcel list-drives`." },
+    { name: "item-id", key: "itemId", required: true, description: "driveItem ID of the .xlsx file." },
+    { name: "table-id", key: "tableId", required: true, description: "Workbook table ID or table name. Returned by `ask-marcel list-excel-tables`." }
+  ],
+  example: "ask-marcel list-excel-table-rows --drive-id 'b!1234' --item-id '01XLSX' --table-id 'Table1'",
+  responseShape: "collection of Microsoft Graph `workbookTableRow` resources (each `values` is a 2D array) under `value[]`"
+};
 
 // src/use-cases/commands/list-excel-tables.ts
 var exports_list_excel_tables = {};
 __export(exports_list_excel_tables, {
-  schema: () => schema57,
-  execute: () => execute57
+  schema: () => schema41,
+  meta: () => meta43,
+  execute: () => execute41
 });
-var schema57 = exports_external.object({ driveId: exports_external.string().min(1), itemId: exports_external.string().min(1) });
-var { execute: execute57 } = buildCommand((p) => `/drives/${p.driveId}/items/${p.itemId}/workbook/tables`, schema57);
+var schema41 = exports_external.object({ driveId: exports_external.string().min(1), itemId: exports_external.string().min(1) });
+var { execute: execute41 } = buildCommand((p) => `/drives/${p.driveId}/items/${p.itemId}/workbook/tables`, schema41);
+var meta43 = {
+  summary: "List the named tables across every worksheet in an Excel workbook.",
+  category: "excel",
+  graphMethod: "GET",
+  graphPathTemplate: "/drives/{drive-id}/items/{item-id}/workbook/tables",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/workbook-list-tables",
+  options: [
+    { name: "drive-id", key: "driveId", required: true, description: "Microsoft Graph drive ID containing the workbook. Returned by `ask-marcel list-drives`." },
+    { name: "item-id", key: "itemId", required: true, description: "driveItem ID of the .xlsx file. Returned by `list-folder-files` or `search-onedrive-files`." }
+  ],
+  example: "ask-marcel list-excel-tables --drive-id 'b!1234' --item-id '01XLSX'",
+  responseShape: "collection of Microsoft Graph `workbookTable` resources under `value[]`"
+};
 
 // src/use-cases/commands/list-excel-worksheets.ts
 var exports_list_excel_worksheets = {};
 __export(exports_list_excel_worksheets, {
-  schema: () => schema58,
-  execute: () => execute58
+  schema: () => schema42,
+  meta: () => meta44,
+  execute: () => execute42
 });
-var schema58 = exports_external.object({ driveId: exports_external.string().min(1), itemId: exports_external.string().min(1) });
-var { execute: execute58 } = buildCommand((p) => `/drives/${p.driveId}/items/${p.itemId}/workbook/worksheets`, schema58);
+var schema42 = exports_external.object({ driveId: exports_external.string().min(1), itemId: exports_external.string().min(1) });
+var { execute: execute42 } = buildCommand((p) => `/drives/${p.driveId}/items/${p.itemId}/workbook/worksheets`, schema42);
+var meta44 = {
+  summary: "List the worksheets (tabs) inside an Excel workbook stored in OneDrive / SharePoint.",
+  category: "excel",
+  graphMethod: "GET",
+  graphPathTemplate: "/drives/{drive-id}/items/{item-id}/workbook/worksheets",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/workbook-list-worksheets",
+  options: [
+    { name: "drive-id", key: "driveId", required: true, description: "Microsoft Graph drive ID containing the workbook. Returned by `ask-marcel list-drives`." },
+    { name: "item-id", key: "itemId", required: true, description: "driveItem ID of the .xlsx file. Returned by `list-folder-files` or `search-onedrive-files`." }
+  ],
+  example: "ask-marcel list-excel-worksheets --drive-id 'b!1234' --item-id '01XLSX'",
+  responseShape: "collection of Microsoft Graph `worksheet` resources under `value[]`"
+};
 
 // src/use-cases/commands/list-folder-files.ts
 var exports_list_folder_files = {};
 __export(exports_list_folder_files, {
-  schema: () => schema59,
-  execute: () => execute59
+  schema: () => schema43,
+  meta: () => meta45,
+  execute: () => execute43
+});
+var schema43 = exports_external.object({ driveId: exports_external.string().min(1), itemId: exports_external.string().min(1) });
+var { execute: execute43 } = buildCommand((p) => `/drives/${p.driveId}/items/${p.itemId}/children`, schema43);
+var meta45 = {
+  summary: "List the children (files and subfolders) of a folder in OneDrive / SharePoint.",
+  category: "drive",
+  graphMethod: "GET",
+  graphPathTemplate: "/drives/{drive-id}/items/{item-id}/children",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/driveitem-list-children",
+  options: [
+    { name: "drive-id", key: "driveId", required: true, description: "Microsoft Graph drive ID. Returned by `ask-marcel list-drives`." },
+    {
+      name: "item-id",
+      key: "itemId",
+      required: true,
+      description: "driveItem ID of the folder. Use the root folder ID from `ask-marcel get-drive-root-item` to list the top of a drive."
+    }
+  ],
+  example: "ask-marcel list-folder-files --drive-id 'b!1234' --item-id '01ROOT'",
+  responseShape: "collection of Microsoft Graph `driveItem` resources under `value[]`"
+};
+
+// src/use-cases/commands/list-incomplete-planner-tasks.ts
+var exports_list_incomplete_planner_tasks = {};
+__export(exports_list_incomplete_planner_tasks, {
+  schema: () => schema44,
+  meta: () => meta46,
+  execute: () => execute44
 });
-var schema59 = exports_external.object({ driveId: exports_external.string().min(1), itemId: exports_external.string().min(1) });
-var { execute: execute59 } = buildCommand((p) => `/drives/${p.driveId}/items/${p.itemId}/children`, schema59);
+var schema44 = exports_external.object({}).strict();
+var { execute: execute44 } = buildCommand(() => "/me/planner/tasks?$filter=percentComplete ne 100", schema44);
+var meta46 = {
+  summary: "List every incomplete Microsoft Planner task assigned to or owned by the signed-in user, across every plan.",
+  category: "tasks",
+  graphMethod: "GET",
+  graphPathTemplate: "/me/planner/tasks?$filter=percentComplete ne 100",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/planneruser-list-tasks",
+  options: [],
+  example: "ask-marcel list-incomplete-planner-tasks",
+  responseShape: "collection of Microsoft Graph `plannerTask` resources under `value[]` where `percentComplete < 100`"
+};
+
+// src/use-cases/commands/list-incomplete-todo-tasks.ts
+var exports_list_incomplete_todo_tasks = {};
+__export(exports_list_incomplete_todo_tasks, {
+  schema: () => schema45,
+  meta: () => meta47,
+  execute: () => execute45
+});
+var schema45 = exports_external.object({ todoTaskListId: exports_external.string().min(1) });
+var { execute: execute45 } = buildCommand((p) => `/me/todo/lists/${p.todoTaskListId}/tasks?$filter=status ne 'completed'`, schema45);
+var meta47 = {
+  summary: "List every incomplete Microsoft To Do task in a given list (status not equal to `completed`).",
+  category: "tasks",
+  graphMethod: "GET",
+  graphPathTemplate: "/me/todo/lists/{todo-task-list-id}/tasks?$filter=status ne 'completed'",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/todotasklist-list-tasks",
+  options: [
+    {
+      name: "todo-task-list-id",
+      key: "todoTaskListId",
+      required: true,
+      description: "todoTaskList ID. Returned by `ask-marcel list-todo-task-lists`. Well-known names also work, e.g. `tasks` for the default list. " + "There is no Graph endpoint that returns incomplete tasks across every list — call this once per list."
+    }
+  ],
+  example: "ask-marcel list-incomplete-todo-tasks --todo-task-list-id 'tasks'",
+  responseShape: 'collection of Microsoft Graph `todoTask` resources under `value[]` where `status != "completed"`'
+};
 
 // src/use-cases/commands/list-joined-teams.ts
 var exports_list_joined_teams = {};
 __export(exports_list_joined_teams, {
-  schema: () => schema60,
-  execute: () => execute60
+  schema: () => schema46,
+  meta: () => meta48,
+  execute: () => execute46
 });
-var schema60 = exports_external.object({}).strict();
-var { execute: execute60 } = buildCommand(() => "/me/joinedTeams", schema60);
+var schema46 = exports_external.object({}).strict();
+var { execute: execute46 } = buildCommand(() => "/me/joinedTeams", schema46);
+var meta48 = {
+  summary: "List the Microsoft Teams the signed-in user is a member of.",
+  category: "teams",
+  graphMethod: "GET",
+  graphPathTemplate: "/me/joinedTeams",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/user-list-joinedteams",
+  options: [],
+  example: "ask-marcel list-joined-teams",
+  responseShape: "collection of Microsoft Graph `team` resources under `value[]`"
+};
 
 // src/use-cases/commands/list-mail-attachments.ts
 var exports_list_mail_attachments = {};
 __export(exports_list_mail_attachments, {
-  schema: () => schema61,
-  execute: () => execute61
+  schema: () => schema47,
+  meta: () => meta49,
+  execute: () => execute47
 });
-var schema61 = exports_external.object({ messageId: exports_external.string().min(1) });
-var { execute: execute61 } = buildCommand((p) => `/me/messages/${p.messageId}/attachments`, schema61);
+var schema47 = exports_external.object({ messageId: exports_external.string().min(1) });
+var { execute: execute47 } = buildCommand((p) => `/me/messages/${p.messageId}/attachments`, schema47);
+var meta49 = {
+  summary: "List the attachments (file, item, reference) on a single Outlook message.",
+  category: "mail",
+  graphMethod: "GET",
+  graphPathTemplate: "/me/messages/{message-id}/attachments",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/message-list-attachments",
+  options: [
+    { name: "message-id", key: "messageId", required: true, description: "Outlook message ID. Returned by `ask-marcel list-mail-messages` or `list-mail-folder-messages`." }
+  ],
+  example: "ask-marcel list-mail-attachments --message-id 'AAMkAGI2...'",
+  responseShape: "collection of Microsoft Graph `attachment` resources under `value[]`"
+};
 
 // src/use-cases/commands/list-mail-child-folders.ts
 var exports_list_mail_child_folders = {};
 __export(exports_list_mail_child_folders, {
-  schema: () => schema62,
-  execute: () => execute62
+  schema: () => schema48,
+  meta: () => meta50,
+  execute: () => execute48
 });
-var schema62 = exports_external.object({ mailFolderId: exports_external.string().min(1) });
-var { execute: execute62 } = buildCommand((p) => `/me/mailFolders/${p.mailFolderId}/childFolders`, schema62);
+var schema48 = exports_external.object({ mailFolderId: exports_external.string().min(1) });
+var { execute: execute48 } = buildCommand((p) => `/me/mailFolders/${p.mailFolderId}/childFolders`, schema48);
+var meta50 = {
+  summary: "List the subfolders of a single Outlook mail folder (e.g. subfolders of Inbox).",
+  category: "mail",
+  graphMethod: "GET",
+  graphPathTemplate: "/me/mailFolders/{mail-folder-id}/childFolders",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/mailfolder-list-childfolders",
+  options: [
+    {
+      name: "mail-folder-id",
+      key: "mailFolderId",
+      required: true,
+      description: "mailFolder ID. Returned by `ask-marcel list-mail-folders`. Well-known names also work, e.g. `inbox`, `sentitems`, `drafts`."
+    }
+  ],
+  example: "ask-marcel list-mail-child-folders --mail-folder-id 'inbox'",
+  responseShape: "collection of Microsoft Graph `mailFolder` resources under `value[]`"
+};
 
 // src/use-cases/commands/list-mail-folder-messages.ts
 var exports_list_mail_folder_messages = {};
 __export(exports_list_mail_folder_messages, {
-  schema: () => schema63,
-  execute: () => execute63
+  schema: () => schema49,
+  meta: () => meta51,
+  execute: () => execute49
 });
-var schema63 = exports_external.object({ mailFolderId: exports_external.string().min(1) });
-var { execute: execute63 } = buildCommand((p) => `/me/mailFolders/${p.mailFolderId}/messages`, schema63);
+var schema49 = exports_external.object({ mailFolderId: exports_external.string().min(1) });
+var { execute: execute49 } = buildCommand((p) => `/me/mailFolders/${p.mailFolderId}/messages`, schema49);
+var meta51 = {
+  summary: "List the messages inside a specific Outlook mail folder (Inbox, custom folder, etc.).",
+  category: "mail",
+  graphMethod: "GET",
+  graphPathTemplate: "/me/mailFolders/{mail-folder-id}/messages",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/mailfolder-list-messages",
+  options: [
+    {
+      name: "mail-folder-id",
+      key: "mailFolderId",
+      required: true,
+      description: "mailFolder ID. Returned by `ask-marcel list-mail-folders`. Well-known names also work, e.g. `inbox`, `sentitems`, `drafts`."
+    }
+  ],
+  example: "ask-marcel list-mail-folder-messages --mail-folder-id 'inbox'",
+  responseShape: "collection of Microsoft Graph `message` resources under `value[]`"
+};
 
 // src/use-cases/commands/list-mail-folders.ts
 var exports_list_mail_folders = {};
 __export(exports_list_mail_folders, {
-  schema: () => schema64,
-  execute: () => execute64
+  schema: () => schema50,
+  meta: () => meta52,
+  execute: () => execute50
 });
-var schema64 = exports_external.object({}).strict();
-var { execute: execute64 } = buildCommand(() => "/me/mailFolders", schema64);
+var schema50 = exports_external.object({}).strict();
+var { execute: execute50 } = buildCommand(() => "/me/mailFolders", schema50);
+var meta52 = {
+  summary: "List the top-level mail folders in the signed-in user’s Outlook mailbox (Inbox, Sent Items, etc.).",
+  category: "mail",
+  graphMethod: "GET",
+  graphPathTemplate: "/me/mailFolders",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/user-list-mailfolders",
+  options: [],
+  example: "ask-marcel list-mail-folders",
+  responseShape: "collection of Microsoft Graph `mailFolder` resources under `value[]`"
+};
 
 // src/use-cases/commands/list-mail-messages.ts
 var exports_list_mail_messages = {};
 __export(exports_list_mail_messages, {
-  schema: () => schema65,
-  execute: () => execute65
+  schema: () => schema51,
+  meta: () => meta53,
+  execute: () => execute51
 });
-var schema65 = exports_external.object({}).strict();
-var { execute: execute65 } = buildCommand(() => "/me/messages", schema65);
+var schema51 = exports_external.object({}).strict();
+var { execute: execute51 } = buildCommand(() => "/me/messages", schema51);
+var meta53 = {
+  summary: "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.",
+  category: "mail",
+  graphMethod: "GET",
+  graphPathTemplate: "/me/messages",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/user-list-messages",
+  options: [],
+  example: "ask-marcel list-mail-messages",
+  responseShape: "collection of Microsoft Graph `message` resources under `value[]`"
+};
 
 // src/use-cases/commands/list-mail-rules.ts
 var exports_list_mail_rules = {};
 __export(exports_list_mail_rules, {
-  schema: () => schema66,
-  execute: () => execute66
+  schema: () => schema52,
+  meta: () => meta54,
+  execute: () => execute52
 });
-var schema66 = exports_external.object({ mailFolderId: exports_external.string().min(1) });
-var { execute: execute66 } = buildCommand((p) => `/me/mailFolders/${p.mailFolderId}/messageRules`, schema66);
+var schema52 = exports_external.object({ mailFolderId: exports_external.string().min(1) });
+var { execute: execute52 } = buildCommand((p) => `/me/mailFolders/${p.mailFolderId}/messageRules`, schema52);
+var meta54 = {
+  summary: "List the inbox / folder rules attached to a single Outlook mail folder.",
+  category: "mail",
+  graphMethod: "GET",
+  graphPathTemplate: "/me/mailFolders/{mail-folder-id}/messageRules",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/mailfolder-list-messagerules",
+  options: [
+    {
+      name: "mail-folder-id",
+      key: "mailFolderId",
+      required: true,
+      description: "mailFolder ID. Returned by `ask-marcel list-mail-folders`. Well-known names also work, e.g. `inbox`."
+    }
+  ],
+  example: "ask-marcel list-mail-rules --mail-folder-id 'inbox'",
+  responseShape: "collection of Microsoft Graph `messageRule` resources under `value[]`"
+};
 
 // src/use-cases/commands/list-onenote-notebook-sections.ts
 var exports_list_onenote_notebook_sections = {};
 __export(exports_list_onenote_notebook_sections, {
-  schema: () => schema67,
-  execute: () => execute67
+  schema: () => schema53,
+  meta: () => meta55,
+  execute: () => execute53
 });
-var schema67 = exports_external.object({ notebookId: exports_external.string().min(1) });
-var { execute: execute67 } = buildCommand((p) => `/me/onenote/notebooks/${p.notebookId}/sections`, schema67);
+var schema53 = exports_external.object({ notebookId: exports_external.string().min(1) });
+var { execute: execute53 } = buildCommand((p) => `/me/onenote/notebooks/${p.notebookId}/sections`, schema53);
+var meta55 = {
+  summary: "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).",
+  category: "notes",
+  graphMethod: "GET",
+  graphPathTemplate: "/me/onenote/notebooks/{notebook-id}/sections",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/notebook-list-sections",
+  options: [{ name: "notebook-id", key: "notebookId", required: true, description: "OneNote notebook ID. Returned by `ask-marcel list-onenote-notebooks`." }],
+  example: "ask-marcel list-onenote-notebook-sections --notebook-id '1-12abc...'",
+  responseShape: "collection of Microsoft Graph `onenoteSection` resources under `value[]`"
+};
 
 // src/use-cases/commands/list-onenote-notebooks.ts
 var exports_list_onenote_notebooks = {};
 __export(exports_list_onenote_notebooks, {
-  schema: () => schema68,
-  execute: () => execute68
+  schema: () => schema54,
+  meta: () => meta56,
+  execute: () => execute54
 });
-var schema68 = exports_external.object({}).strict();
-var { execute: execute68 } = buildCommand(() => "/me/onenote/notebooks", schema68);
+var schema54 = exports_external.object({}).strict();
+var { execute: execute54 } = buildCommand(() => "/me/onenote/notebooks", schema54);
+var meta56 = {
+  summary: "List the OneNote notebooks the signed-in user owns or has access to (sorted by `createdDateTime` desc by Graph; soft-deleted notebooks excluded).",
+  category: "notes",
+  graphMethod: "GET",
+  graphPathTemplate: "/me/onenote/notebooks",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/onenote-list-notebooks",
+  options: [],
+  example: "ask-marcel list-onenote-notebooks",
+  responseShape: "collection of Microsoft Graph `notebook` resources under `value[]`"
+};
 
 // src/use-cases/commands/list-onenote-section-pages.ts
 var exports_list_onenote_section_pages = {};
 __export(exports_list_onenote_section_pages, {
-  schema: () => schema69,
-  execute: () => execute69
-});
-var schema69 = exports_external.object({ onenoteSectionId: exports_external.string().min(1) });
-var { execute: execute69 } = buildCommand((p) => `/me/onenote/sections/${p.onenoteSectionId}/pages`, schema69);
-
-// src/use-cases/commands/list-outlook-contacts.ts
-var exports_list_outlook_contacts = {};
-__export(exports_list_outlook_contacts, {
-  schema: () => schema70,
-  execute: () => execute70
-});
-var schema70 = exports_external.object({}).strict();
-var { execute: execute70 } = buildCommand(() => "/me/contacts", schema70);
-
-// src/use-cases/commands/list-pinned-chat-messages.ts
-var exports_list_pinned_chat_messages = {};
-__export(exports_list_pinned_chat_messages, {
-  schema: () => schema71,
-  execute: () => execute71
+  schema: () => schema55,
+  meta: () => meta57,
+  execute: () => execute55
 });
-var schema71 = exports_external.object({ chatId: exports_external.string().min(1) });
-var { execute: execute71 } = buildCommand((p) => `/chats/${p.chatId}/pinnedMessages`, schema71);
+var schema55 = exports_external.object({ onenoteSectionId: exports_external.string().min(1) });
+var { execute: execute55 } = buildCommand((p) => `/me/onenote/sections/${p.onenoteSectionId}/pages`, schema55);
+var meta57 = {
+  summary: "List the pages inside a single OneNote section.",
+  category: "notes",
+  graphMethod: "GET",
+  graphPathTemplate: "/me/onenote/sections/{onenote-section-id}/pages",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/section-list-pages",
+  options: [
+    {
+      name: "onenote-section-id",
+      key: "onenoteSectionId",
+      required: true,
+      description: "OneNote section ID. Returned by `ask-marcel list-onenote-notebook-sections` or `list-all-onenote-sections`."
+    }
+  ],
+  example: "ask-marcel list-onenote-section-pages --onenote-section-id '1-abc...'",
+  responseShape: "collection of Microsoft Graph `onenotePage` resources under `value[]`"
+};
 
 // src/use-cases/commands/list-plan-buckets.ts
 var exports_list_plan_buckets = {};
 __export(exports_list_plan_buckets, {
-  schema: () => schema72,
-  execute: () => execute72
+  schema: () => schema56,
+  meta: () => meta58,
+  execute: () => execute56
 });
-var schema72 = exports_external.object({ plannerPlanId: exports_external.string().min(1) });
-var { execute: execute72 } = buildCommand((p) => `/planner/plans/${p.plannerPlanId}/buckets`, schema72);
+var schema56 = exports_external.object({ plannerPlanId: exports_external.string().min(1) });
+var { execute: execute56 } = buildCommand((p) => `/planner/plans/${p.plannerPlanId}/buckets`, schema56);
+var meta58 = {
+  summary: "List the buckets (columns / lanes) of a Microsoft Planner plan.",
+  category: "tasks",
+  graphMethod: "GET",
+  graphPathTemplate: "/planner/plans/{planner-plan-id}/buckets",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/plannerplan-list-buckets",
+  options: [
+    {
+      name: "planner-plan-id",
+      key: "plannerPlanId",
+      required: true,
+      description: "Planner plan ID. Returned in the `planId` field of any task from `ask-marcel list-planner-tasks`."
+    }
+  ],
+  example: "ask-marcel list-plan-buckets --planner-plan-id 'xqQg5FS2LkCp935s-FIFm5gAB6'",
+  responseShape: "collection of Microsoft Graph `plannerBucket` resources under `value[]`"
+};
 
 // src/use-cases/commands/list-plan-tasks.ts
 var exports_list_plan_tasks = {};
 __export(exports_list_plan_tasks, {
-  schema: () => schema73,
-  execute: () => execute73
+  schema: () => schema57,
+  meta: () => meta59,
+  execute: () => execute57
 });
-var schema73 = exports_external.object({ plannerPlanId: exports_external.string().min(1) });
-var { execute: execute73 } = buildCommand((p) => `/planner/plans/${p.plannerPlanId}/tasks`, schema73);
+var schema57 = exports_external.object({ plannerPlanId: exports_external.string().min(1) });
+var { execute: execute57 } = buildCommand((p) => `/planner/plans/${p.plannerPlanId}/tasks`, schema57);
+var meta59 = {
+  summary: "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.",
+  category: "tasks",
+  graphMethod: "GET",
+  graphPathTemplate: "/planner/plans/{planner-plan-id}/tasks",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/plannerplan-list-tasks",
+  options: [
+    {
+      name: "planner-plan-id",
+      key: "plannerPlanId",
+      required: true,
+      description: "Planner plan ID. Returned in the `planId` field of any task from `ask-marcel list-planner-tasks`."
+    }
+  ],
+  example: "ask-marcel list-plan-tasks --planner-plan-id 'xqQg5FS2LkCp935s-FIFm5gAB6'",
+  responseShape: "collection of Microsoft Graph `plannerTask` resources under `value[]`"
+};
+
+// src/use-cases/commands/list-planner-plans.ts
+var exports_list_planner_plans = {};
+__export(exports_list_planner_plans, {
+  schema: () => schema58,
+  meta: () => meta60,
+  execute: () => execute58
+});
+var schema58 = exports_external.object({}).strict();
+var { execute: execute58 } = buildCommand(() => "/me/planner/plans", schema58);
+var meta60 = {
+  summary: "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.",
+  category: "tasks",
+  graphMethod: "GET",
+  graphPathTemplate: "/me/planner/plans",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/planneruser-list-plans",
+  options: [],
+  example: "ask-marcel list-planner-plans",
+  responseShape: "collection of Microsoft Graph `plannerPlan` resources under `value[]`"
+};
 
 // src/use-cases/commands/list-planner-tasks.ts
 var exports_list_planner_tasks = {};
 __export(exports_list_planner_tasks, {
-  schema: () => schema74,
-  execute: () => execute74
+  schema: () => schema59,
+  meta: () => meta61,
+  execute: () => execute59
 });
-var schema74 = exports_external.object({}).strict();
-var { execute: execute74 } = buildCommand(() => "/me/planner/tasks", schema74);
+var schema59 = exports_external.object({}).strict();
+var { execute: execute59 } = buildCommand(() => "/me/planner/tasks", schema59);
+var meta61 = {
+  summary: "List every Microsoft Planner task assigned to or owned by the signed-in user, across all plans.",
+  category: "tasks",
+  graphMethod: "GET",
+  graphPathTemplate: "/me/planner/tasks",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/planneruser-list-tasks",
+  options: [],
+  example: "ask-marcel list-planner-tasks",
+  responseShape: "collection of Microsoft Graph `plannerTask` resources under `value[]`"
+};
 
 // src/use-cases/commands/list-sharepoint-site-drives.ts
 var exports_list_sharepoint_site_drives = {};
 __export(exports_list_sharepoint_site_drives, {
-  schema: () => schema75,
-  execute: () => execute75
-});
-var schema75 = exports_external.object({ siteId: exports_external.string().min(1) });
-var { execute: execute75 } = buildCommand((p) => `/sites/${p.siteId}/drives`, schema75);
-
-// src/use-cases/commands/list-sharepoint-site-items.ts
-var exports_list_sharepoint_site_items = {};
-__export(exports_list_sharepoint_site_items, {
-  schema: () => schema76,
-  execute: () => execute76
+  schema: () => schema60,
+  meta: () => meta62,
+  execute: () => execute60
 });
-var schema76 = exports_external.object({ siteId: exports_external.string().min(1) });
-var { execute: execute76 } = buildCommand((p) => `/sites/${p.siteId}/items`, schema76);
+var schema60 = exports_external.object({ siteId: exports_external.string().min(1) });
+var { execute: execute60 } = buildCommand((p) => `/sites/${p.siteId}/drives`, schema60);
+var meta62 = {
+  summary: "List the document libraries (drives) attached to a SharePoint site.",
+  category: "sharepoint",
+  graphMethod: "GET",
+  graphPathTemplate: "/sites/{site-id}/drives",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/drive-list",
+  options: [{ name: "site-id", key: "siteId", required: true, description: "SharePoint site ID. Returned by `ask-marcel search-sharepoint-sites`." }],
+  example: "ask-marcel list-sharepoint-site-drives --site-id 'contoso.sharepoint.com,1234,5678'",
+  responseShape: "collection of Microsoft Graph `drive` resources under `value[]`"
+};
 
 // src/use-cases/commands/list-sharepoint-site-list-items.ts
 var exports_list_sharepoint_site_list_items = {};
 __export(exports_list_sharepoint_site_list_items, {
-  schema: () => schema77,
-  execute: () => execute77
+  schema: () => schema61,
+  meta: () => meta63,
+  execute: () => execute61
 });
-var schema77 = exports_external.object({ siteId: exports_external.string().min(1), listId: exports_external.string().min(1) });
-var { execute: execute77 } = buildCommand((p) => `/sites/${p.siteId}/lists/${p.listId}/items`, schema77);
+var schema61 = exports_external.object({ siteId: exports_external.string().min(1), listId: exports_external.string().min(1) });
+var { execute: execute61 } = buildCommand((p) => `/sites/${p.siteId}/lists/${p.listId}/items`, schema61);
+var meta63 = {
+  summary: "List the rows (listItem resources) of a single SharePoint list.",
+  category: "sharepoint",
+  graphMethod: "GET",
+  graphPathTemplate: "/sites/{site-id}/lists/{list-id}/items",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/listitem-list",
+  options: [
+    { name: "site-id", key: "siteId", required: true, description: "SharePoint site ID. Returned by `ask-marcel search-sharepoint-sites`." },
+    { name: "list-id", key: "listId", required: true, description: "SharePoint list ID or display name. Returned by `ask-marcel list-sharepoint-site-lists`." }
+  ],
+  example: "ask-marcel list-sharepoint-site-list-items --site-id 'contoso.sharepoint.com,1234,5678' --list-id 'Tasks'",
+  responseShape: "collection of Microsoft Graph `listItem` resources under `value[]`"
+};
 
 // src/use-cases/commands/list-sharepoint-site-lists.ts
 var exports_list_sharepoint_site_lists = {};
 __export(exports_list_sharepoint_site_lists, {
-  schema: () => schema78,
-  execute: () => execute78
+  schema: () => schema62,
+  meta: () => meta64,
+  execute: () => execute62
 });
-var schema78 = exports_external.object({ siteId: exports_external.string().min(1) });
-var { execute: execute78 } = buildCommand((p) => `/sites/${p.siteId}/lists`, schema78);
+var schema62 = exports_external.object({ siteId: exports_external.string().min(1) });
+var { execute: execute62 } = buildCommand((p) => `/sites/${p.siteId}/lists`, schema62);
+var meta64 = {
+  summary: "List all SharePoint lists (custom + built-in document libraries) on a site.",
+  category: "sharepoint",
+  graphMethod: "GET",
+  graphPathTemplate: "/sites/{site-id}/lists",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/list-list",
+  options: [{ name: "site-id", key: "siteId", required: true, description: "SharePoint site ID. Returned by `ask-marcel search-sharepoint-sites`." }],
+  example: "ask-marcel list-sharepoint-site-lists --site-id 'contoso.sharepoint.com,1234,5678'",
+  responseShape: "collection of Microsoft Graph `list` resources under `value[]`"
+};
 
 // src/use-cases/commands/list-specific-calendar-events.ts
 var exports_list_specific_calendar_events = {};
 __export(exports_list_specific_calendar_events, {
-  schema: () => schema79,
-  execute: () => execute79
+  schema: () => schema63,
+  meta: () => meta65,
+  execute: () => execute63
 });
-var schema79 = exports_external.object({ calendarId: exports_external.string().min(1) });
-var { execute: execute79 } = buildCommand((p) => `/me/calendars/${p.calendarId}/events`, schema79);
+var schema63 = exports_external.object({ calendarId: exports_external.string().min(1) });
+var { execute: execute63 } = buildCommand((p) => `/me/calendars/${p.calendarId}/events`, schema63);
+var meta65 = {
+  summary: "List the events in a specific (non-default) calendar (does not expand recurrences).",
+  category: "calendar",
+  graphMethod: "GET",
+  graphPathTemplate: "/me/calendars/{calendar-id}/events",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/calendar-list-events",
+  options: [{ name: "calendar-id", key: "calendarId", required: true, description: "Calendar ID. Returned by `ask-marcel list-calendars`." }],
+  example: "ask-marcel list-specific-calendar-events --calendar-id 'AAMkAGI2THVS...'",
+  responseShape: "collection of Microsoft Graph `event` resources under `value[]`"
+};
 
 // src/use-cases/commands/list-team-channels.ts
 var exports_list_team_channels = {};
 __export(exports_list_team_channels, {
-  schema: () => schema80,
-  execute: () => execute80
-});
-var schema80 = exports_external.object({ teamId: exports_external.string().min(1) });
-var { execute: execute80 } = buildCommand((p) => `/teams/${p.teamId}/channels`, schema80);
-
-// src/use-cases/commands/list-team-members.ts
-var exports_list_team_members = {};
-__export(exports_list_team_members, {
-  schema: () => schema81,
-  execute: () => execute81
+  schema: () => schema64,
+  meta: () => meta66,
+  execute: () => execute64
 });
-var schema81 = exports_external.object({ teamId: exports_external.string().min(1) });
-var { execute: execute81 } = buildCommand((p) => `/teams/${p.teamId}/members`, schema81);
+var schema64 = exports_external.object({ teamId: exports_external.string().min(1) });
+var { execute: execute64 } = buildCommand((p) => `/teams/${p.teamId}/channels`, schema64);
+var meta66 = {
+  summary: "List the channels (standard, private, shared) inside a single Microsoft Team.",
+  category: "teams",
+  graphMethod: "GET",
+  graphPathTemplate: "/teams/{team-id}/channels",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/channel-list",
+  options: [{ name: "team-id", key: "teamId", required: true, description: "Microsoft Teams team ID. Returned by `ask-marcel list-joined-teams`." }],
+  example: "ask-marcel list-team-channels --team-id 'abc-1234-...'",
+  responseShape: "collection of Microsoft Graph `channel` resources under `value[]`"
+};
 
 // src/use-cases/commands/list-todo-linked-resources.ts
 var exports_list_todo_linked_resources = {};
 __export(exports_list_todo_linked_resources, {
-  schema: () => schema82,
-  execute: () => execute82
+  schema: () => schema65,
+  meta: () => meta67,
+  execute: () => execute65
 });
-var schema82 = exports_external.object({ todoTaskListId: exports_external.string().min(1), todoTaskId: exports_external.string().min(1) });
-var { execute: execute82 } = buildCommand((p) => `/me/todo/lists/${p.todoTaskListId}/tasks/${p.todoTaskId}/linkedResources`, schema82);
+var schema65 = exports_external.object({ todoTaskListId: exports_external.string().min(1), todoTaskId: exports_external.string().min(1) });
+var { execute: execute65 } = buildCommand((p) => `/me/todo/lists/${p.todoTaskListId}/tasks/${p.todoTaskId}/linkedResources`, schema65);
+var meta67 = {
+  summary: "List the linked resources (URLs, emails, files) attached to a Microsoft To Do task.",
+  category: "tasks",
+  graphMethod: "GET",
+  graphPathTemplate: "/me/todo/lists/{todo-task-list-id}/tasks/{todo-task-id}/linkedResources",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/todotask-list-linkedresources",
+  options: [
+    { name: "todo-task-list-id", key: "todoTaskListId", required: true, description: "To Do task list ID. Returned by `ask-marcel list-todo-task-lists`." },
+    { name: "todo-task-id", key: "todoTaskId", required: true, description: "To Do task ID. Returned by `ask-marcel list-todo-tasks`." }
+  ],
+  example: "ask-marcel list-todo-linked-resources --todo-task-list-id 'AAMkAGI...' --todo-task-id 'AAMkABC...'",
+  responseShape: "collection of Microsoft Graph `linkedResource` resources under `value[]`"
+};
 
 // src/use-cases/commands/list-todo-task-lists.ts
 var exports_list_todo_task_lists = {};
 __export(exports_list_todo_task_lists, {
-  schema: () => schema83,
-  execute: () => execute83
+  schema: () => schema66,
+  meta: () => meta68,
+  execute: () => execute66
 });
-var schema83 = exports_external.object({}).strict();
-var { execute: execute83 } = buildCommand(() => "/me/todo/lists", schema83);
+var schema66 = exports_external.object({}).strict();
+var { execute: execute66 } = buildCommand(() => "/me/todo/lists", schema66);
+var meta68 = {
+  summary: "List the signed-in user’s Microsoft To Do task lists (e.g. `Tasks`, `Flagged Emails`, custom lists).",
+  category: "tasks",
+  graphMethod: "GET",
+  graphPathTemplate: "/me/todo/lists",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/todo-list-lists",
+  options: [],
+  example: "ask-marcel list-todo-task-lists",
+  responseShape: "collection of Microsoft Graph `todoTaskList` resources under `value[]`"
+};
 
 // src/use-cases/commands/list-todo-tasks.ts
 var exports_list_todo_tasks = {};
 __export(exports_list_todo_tasks, {
-  schema: () => schema84,
-  execute: () => execute84
+  schema: () => schema67,
+  meta: () => meta69,
+  execute: () => execute67
+});
+var schema67 = exports_external.object({ todoTaskListId: exports_external.string().min(1) });
+var { execute: execute67 } = buildCommand((p) => `/me/todo/lists/${p.todoTaskListId}/tasks`, schema67);
+var meta69 = {
+  summary: "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.",
+  category: "tasks",
+  graphMethod: "GET",
+  graphPathTemplate: "/me/todo/lists/{todo-task-list-id}/tasks",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/todotasklist-list-tasks",
+  options: [{ name: "todo-task-list-id", key: "todoTaskListId", required: true, description: "To Do task list ID. Returned by `ask-marcel list-todo-task-lists`." }],
+  example: "ask-marcel list-todo-tasks --todo-task-list-id 'AAMkAGI...'",
+  responseShape: "collection of Microsoft Graph `todoTask` resources under `value[]`"
+};
+
+// src/use-cases/commands/next-page.ts
+var exports_next_page = {};
+__export(exports_next_page, {
+  schema: () => schema68,
+  meta: () => meta70,
+  execute: () => execute68
 });
-var schema84 = exports_external.object({ todoTaskListId: exports_external.string().min(1) });
-var { execute: execute84 } = buildCommand((p) => `/me/todo/lists/${p.todoTaskListId}/tasks`, schema84);
+var PREFIX = "https://graph.microsoft.com/v1.0";
+var schema68 = exports_external.object({
+  url: exports_external.string().min(1).refine((v) => v.startsWith(`${PREFIX}/`), { message: `must be a Microsoft Graph v1.0 URL starting with ${PREFIX}/` })
+});
+var { execute: execute68 } = buildCommand((p) => p.url.slice(PREFIX.length), schema68);
+var meta70 = {
+  summary: "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.",
+  category: "meta",
+  graphMethod: "GET",
+  graphPathTemplate: "{url}",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/paging",
+  options: [
+    {
+      name: "url",
+      key: "url",
+      required: true,
+      description: "Full Graph v1.0 URL — copy the `@odata.nextLink` field from the previous response. " + "Example: `https://graph.microsoft.com/v1.0/me/messages?$skiptoken=AKDsfg...`. " + "Loop: keep calling until the response no longer contains `@odata.nextLink`. " + "Also handles `@odata.deltaLink` if you want to resume a delta query."
+    }
+  ],
+  example: "ask-marcel next-page --url 'https://graph.microsoft.com/v1.0/me/messages?$skip=10'",
+  responseShape: 'same shape as the originating endpoint (typically `{ value: [...], "@odata.nextLink": "..." }`)'
+};
+
+// src/use-cases/commands/search-mail-messages.ts
+var exports_search_mail_messages = {};
+__export(exports_search_mail_messages, {
+  schema: () => schema69,
+  meta: () => meta71,
+  execute: () => execute69
+});
+var schema69 = exports_external.object({ query: exports_external.string().min(1) });
+var { execute: execute69 } = buildCommand((p) => `/me/messages?$search="${p.query}"`, schema69);
+var meta71 = {
+  summary: "Search the signed-in user’s entire Outlook mailbox using KQL or free text. Results are ranked by Graph relevance.",
+  category: "mail",
+  graphMethod: "GET",
+  graphPathTemplate: '/me/messages?$search="{query}"',
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/user-list-messages",
+  options: [
+    {
+      name: "query",
+      key: "query",
+      required: true,
+      description: "KQL or free-text query. Searches subject, body, sender, and recipients. " + "Examples: `Q3 budget`, `from:alice@contoso.com`, `subject:invoice received>=2026-01-01`."
+    }
+  ],
+  example: "ask-marcel search-mail-messages --query 'from:alice subject:Q3'",
+  responseShape: "collection of Microsoft Graph `message` resources under `value[]`, ranked by relevance"
+};
+
+// src/use-cases/commands/search-my-documents.ts
+var exports_search_my_documents = {};
+__export(exports_search_my_documents, {
+  schema: () => schema70,
+  meta: () => meta72,
+  execute: () => execute70
+});
+var schema70 = exports_external.object({ query: exports_external.string().min(1) });
+var { execute: execute70 } = buildCommand((p) => `/me/drive/search(q='${p.query}')`, schema70);
+var meta72 = {
+  summary: "Search the signed-in user’s default OneDrive for documents matching a free-text query (filename, content, metadata).",
+  category: "drive",
+  graphMethod: "GET",
+  graphPathTemplate: "/me/drive/search(q='{query}')",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/driveitem-search",
+  options: [
+    {
+      name: "query",
+      key: "query",
+      required: true,
+      description: "Free-text search query. Matches filename, content, and metadata across the user’s personal OneDrive. " + "Use `search-onedrive-files --drive-id <id>` instead to target a specific shared SharePoint or OneDrive drive by ID."
+    }
+  ],
+  example: "ask-marcel search-my-documents --query 'q1 budget'",
+  responseShape: "collection of Microsoft Graph `driveItem` resources under `value[]`"
+};
 
 // src/use-cases/commands/search-onedrive-files.ts
 var exports_search_onedrive_files = {};
 __export(exports_search_onedrive_files, {
-  schema: () => schema85,
-  execute: () => execute85
+  schema: () => schema71,
+  meta: () => meta73,
+  execute: () => execute71
 });
-var schema85 = exports_external.object({ driveId: exports_external.string().min(1), query: exports_external.string().min(1) });
-var execute85 = async (graph, params) => {
-  const parsed = schema85.safeParse(params);
+var schema71 = exports_external.object({ driveId: exports_external.string().min(1), query: exports_external.string().min(1) });
+var execute71 = async (graph, params) => {
+  const parsed = schema71.safeParse(params);
   if (!parsed.success)
     throw new Error(`validation failed: ${parsed.error.message}`);
   return graph.get(`/drives/${parsed.data.driveId}/search(q='${parsed.data.query}')`);
 };
+var meta73 = {
+  summary: "Search a single OneDrive / SharePoint drive for files and folders matching a free-text query.",
+  category: "drive",
+  graphMethod: "GET",
+  graphPathTemplate: "/drives/{drive-id}/search(q='{query}')",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/driveitem-search",
+  options: [
+    { name: "drive-id", key: "driveId", required: true, description: "Microsoft Graph drive ID to search inside. Returned by `ask-marcel list-drives`." },
+    { name: "query", key: "query", required: true, description: "Free-text search query. Matches filename, content, and metadata." }
+  ],
+  example: "ask-marcel search-onedrive-files --drive-id 'b!1234' --query 'q1 budget'",
+  responseShape: "collection of Microsoft Graph `driveItem` resources under `value[]`"
+};
+
+// src/use-cases/commands/search-onenote-pages.ts
+var exports_search_onenote_pages = {};
+__export(exports_search_onenote_pages, {
+  schema: () => schema72,
+  meta: () => meta74,
+  execute: () => execute72
+});
+var schema72 = exports_external.object({ titleSubstring: exports_external.string().min(1) });
+var { execute: execute72 } = buildCommand((p) => `/me/onenote/pages?$filter=contains(title,'${p.titleSubstring}')`, schema72);
+var meta74 = {
+  summary: "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.",
+  category: "notes",
+  graphMethod: "GET",
+  graphPathTemplate: "/me/onenote/pages?$filter=contains(title,'{title-substring}')",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/onenote-list-pages",
+  options: [
+    {
+      name: "title-substring",
+      key: "titleSubstring",
+      required: true,
+      description: "Substring to look for inside OneNote page titles (case-sensitive, exact substring). " + "This is title-only — full-text body search is not available on OneNote pages in v1.0 Graph. " + "Use `list-onenote-section-pages` if you already know the section."
+    }
+  ],
+  example: "ask-marcel search-onenote-pages --title-substring 'meeting notes'",
+  responseShape: "collection of Microsoft Graph `onenotePage` resources under `value[]` whose title contains the substring"
+};
+
+// src/use-cases/commands/search-sharepoint-sites-by-name.ts
+var exports_search_sharepoint_sites_by_name = {};
+__export(exports_search_sharepoint_sites_by_name, {
+  schema: () => schema73,
+  meta: () => meta75,
+  execute: () => execute73
+});
+var schema73 = exports_external.object({ query: exports_external.string().min(1) });
+var { execute: execute73 } = buildCommand((p) => `/sites?search=${p.query}`, schema73);
+var meta75 = {
+  summary: "Search the tenant for SharePoint sites whose display name or description matches a free-text query (returns up to 25).",
+  category: "sharepoint",
+  graphMethod: "GET",
+  graphPathTemplate: "/sites?search={query}",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/site-search",
+  options: [
+    {
+      name: "query",
+      key: "query",
+      required: true,
+      description: "Free-text query. Matches site display name and description across the tenant. " + "Use `search-sharepoint-sites` (no query) to instead list the sites the signed-in user follows."
+    }
+  ],
+  example: "ask-marcel search-sharepoint-sites-by-name --query 'marketing'",
+  responseShape: "collection of Microsoft Graph `site` resources under `value[]` (up to 25)"
+};
 
 // src/use-cases/commands/search-sharepoint-sites.ts
 var exports_search_sharepoint_sites = {};
 __export(exports_search_sharepoint_sites, {
-  schema: () => schema86,
-  execute: () => execute86
+  schema: () => schema74,
+  meta: () => meta76,
+  execute: () => execute74
 });
-var schema86 = exports_external.object({}).strict();
-var { execute: execute86 } = buildCommand(() => "/sites", schema86);
+var schema74 = exports_external.object({}).strict();
+var { execute: execute74 } = buildCommand(() => "/sites", schema74);
+var meta76 = {
+  summary: "List the SharePoint sites the signed-in user has access to (returns the followed sites by default).",
+  category: "sharepoint",
+  graphMethod: "GET",
+  graphPathTemplate: "/sites",
+  graphDocsUrl: "https://learn.microsoft.com/en-us/graph/api/site-search",
+  options: [],
+  example: "ask-marcel search-sharepoint-sites",
+  responseShape: "collection of Microsoft Graph `site` resources under `value[]`"
+};
 
 // src/use-cases/commands/index.ts
 var commands = {
@@ -26935,7 +28122,9 @@ var commands = {
   "get-drive-item": exports_get_drive_item,
   "list-drive-item-permissions": exports_list_drive_item_permissions,
   "list-drive-item-versions": exports_list_drive_item_versions,
+  "download-drive-item-version-content": exports_download_drive_item_version_content,
   "search-onedrive-files": exports_search_onedrive_files,
+  "search-my-documents": exports_search_my_documents,
   "get-excel-range": exports_get_excel_range,
   "list-excel-worksheets": exports_list_excel_worksheets,
   "list-excel-tables": exports_list_excel_tables,
@@ -26943,22 +28132,23 @@ var commands = {
   "list-excel-table-rows": exports_list_excel_table_rows,
   "get-drive-delta": exports_get_drive_delta,
   "search-sharepoint-sites": exports_search_sharepoint_sites,
+  "search-sharepoint-sites-by-name": exports_search_sharepoint_sites_by_name,
   "get-sharepoint-site": exports_get_sharepoint_site,
   "list-sharepoint-site-drives": exports_list_sharepoint_site_drives,
   "get-sharepoint-site-drive-by-id": exports_get_sharepoint_site_drive_by_id,
-  "list-sharepoint-site-items": exports_list_sharepoint_site_items,
-  "get-sharepoint-site-item": exports_get_sharepoint_site_item,
   "list-sharepoint-site-lists": exports_list_sharepoint_site_lists,
   "get-sharepoint-site-list": exports_get_sharepoint_site_list,
   "list-sharepoint-site-list-items": exports_list_sharepoint_site_list_items,
   "get-sharepoint-site-list-item": exports_get_sharepoint_site_list_item,
   "get-sharepoint-site-by-path": exports_get_sharepoint_site_by_path,
-  "get-sharepoint-sites-delta": exports_get_sharepoint_sites_delta,
   "list-todo-task-lists": exports_list_todo_task_lists,
   "list-todo-tasks": exports_list_todo_tasks,
+  "list-incomplete-todo-tasks": exports_list_incomplete_todo_tasks,
   "get-todo-task": exports_get_todo_task,
   "list-todo-linked-resources": exports_list_todo_linked_resources,
+  "list-planner-plans": exports_list_planner_plans,
   "list-planner-tasks": exports_list_planner_tasks,
+  "list-incomplete-planner-tasks": exports_list_incomplete_planner_tasks,
   "get-planner-plan": exports_get_planner_plan,
   "list-plan-tasks": exports_list_plan_tasks,
   "get-planner-task": exports_get_planner_task,
@@ -26974,11 +28164,13 @@ var commands = {
   "get-mail-attachment": exports_get_mail_attachment,
   "list-mail-rules": exports_list_mail_rules,
   "get-mailbox-settings": exports_get_mailbox_settings,
+  "search-mail-messages": exports_search_mail_messages,
   "list-onenote-notebooks": exports_list_onenote_notebooks,
   "list-onenote-notebook-sections": exports_list_onenote_notebook_sections,
   "list-all-onenote-sections": exports_list_all_onenote_sections,
   "list-onenote-section-pages": exports_list_onenote_section_pages,
   "get-onenote-page-content": exports_get_onenote_page_content,
+  "search-onenote-pages": exports_search_onenote_pages,
   "get-current-user": exports_get_current_user,
   "get-my-profile-photo": exports_get_my_profile_photo,
   "list-calendar-events": exports_list_calendar_events,
@@ -26991,88 +28183,160 @@ var commands = {
   "list-calendars": exports_list_calendars,
   "list-calendar-events-delta": exports_list_calendar_events_delta,
   "list-calendar-view-delta": exports_list_calendar_view_delta,
-  "list-outlook-contacts": exports_list_outlook_contacts,
-  "get-outlook-contact": exports_get_outlook_contact,
-  "list-chats": exports_list_chats,
-  "get-chat": exports_get_chat,
   "list-chat-members": exports_list_chat_members,
-  "list-chat-messages": exports_list_chat_messages,
-  "get-chat-message": exports_get_chat_message,
-  "list-chat-message-hosted-contents": exports_list_chat_message_hosted_contents,
-  "get-chat-message-hosted-content": exports_get_chat_message_hosted_content,
-  "list-chat-message-replies": exports_list_chat_message_replies,
-  "list-pinned-chat-messages": exports_list_pinned_chat_messages,
   "list-joined-teams": exports_list_joined_teams,
   "get-team": exports_get_team,
   "list-team-channels": exports_list_team_channels,
   "get-team-channel": exports_get_team_channel,
-  "list-channel-messages": exports_list_channel_messages,
-  "get-channel-message": exports_get_channel_message,
-  "list-channel-message-hosted-contents": exports_list_channel_message_hosted_contents,
-  "get-channel-message-hosted-content": exports_get_channel_message_hosted_content,
-  "list-channel-message-replies": exports_list_channel_message_replies,
-  "list-channel-tabs": exports_list_channel_tabs,
-  "list-team-members": exports_list_team_members,
-  "get-channel-files-folder": exports_get_channel_files_folder
+  "next-page": exports_next_page
 };
 
 // src/use-cases/commands/login.ts
-var schema87 = exports_external.object({}).strict();
-var execute87 = async (auth) => auth.getAccessToken();
+var schema75 = exports_external.object({}).strict();
+var execute75 = async (auth) => auth.getAccessToken();
 
 // src/use-cases/commands/logout.ts
-var schema88 = exports_external.object({}).strict();
-var execute88 = async (auth) => auth.logout();
+var schema76 = exports_external.object({}).strict();
+var execute76 = async (auth) => auth.logout();
+
+// src/use-cases/commands/update.ts
+var PACKAGE = "ask-marcel-office-cli";
+var argsFor = (manager) => manager === "bun" ? ["add", "-g", `${PACKAGE}@latest`] : ["i", "-g", `${PACKAGE}@latest`];
+var schema77 = exports_external.object({}).strict();
+var execute77 = async (runner, manager) => {
+  const result = await runner.runInherit(manager, argsFor(manager));
+  if (!result.ok)
+    return err({ type: "spawn_failed", message: result.error.message });
+  if (result.value.exitCode !== 0)
+    return err({ type: "install_failed", exitCode: result.value.exitCode });
+  return ok({ exitCode: result.value.exitCode });
+};
+
+// src/composition/package-manager.ts
+var detectPackageManager = (binPath) => {
+  const normalised = binPath.replaceAll("\\", "/");
+  if (normalised.includes("/.bun/") || normalised.endsWith("/.bun"))
+    return "bun";
+  return "npm";
+};
 
 // src/composition/cli.ts
 var buildCli = (deps) => {
-  const { auth, graph, logger, version: version2 } = deps;
+  const { auth, graph, logger, processRunner, version: version2 } = deps;
   const program2 = new Command;
+  const fail = (message) => {
+    renderError(message, logger);
+    deps.onCommandError?.();
+  };
   program2.name("ask-marcel").description("Microsoft Graph CLI").version(version2 ?? "0.0.0");
-  program2.command("login").description("Authenticate (cached → refresh → browser)").action(async () => {
-    const result = await execute87(auth);
+  program2.commandsGroup("Lifecycle:");
+  const loginCmd = program2.command("login").description("Authenticate against Microsoft Graph using the Teams web client (cached token → refresh → browser fallback).").action(async () => {
+    const result = await execute75(auth);
     if (result.ok)
       render({ status: "authenticated" }, logger);
     else
-      renderError(result.error.type === "auth_cancelled" ? "Authentication cancelled" : result.error.message, logger);
-  });
-  program2.command("logout").description("Clear cached tokens").action(async () => {
-    const result = await execute88(auth);
+      fail(result.error.type === "auth_cancelled" ? "Authentication cancelled" : result.error.message);
+  });
+  loginCmd.addHelpText("after", [
+    "",
+    "Token cache:   ~/.ask-marcel/token-cache.json (access + refresh tokens, JSON, 0600).",
+    "Browser data:  ~/.ask-marcel/browser-profile/ (Playwright persistent context).",
+    "Scopes:        granted by Microsoft to the Teams web client (CLIENT_ID 5e3ce6c0-...);",
+    "               this CLI cannot request additional scopes. To inspect the granted set:",
+    "               bun run scripts/print-token-scopes.ts",
+    "Stuck flow:    `ask-marcel logout` then re-run; the browser fallback opens a fresh Edge / Chrome window."
+  ].join(`
+  `));
+  const logoutCmd = program2.command("logout").description("Clear the cached Microsoft Graph token so the next command forces a fresh sign-in.").action(async () => {
+    const result = await execute76(auth);
     if (result.ok)
       render({ status: "logged_out" }, logger);
     else
-      renderError(result.error.type === "auth_cancelled" ? "Logout cancelled" : result.error.message, logger);
-  });
-  for (const [name, cmd] of Object.entries(commands)) {
-    const commandDef = program2.command(name).description(`Graph API: ${name}`);
-    const schemaKeys = getSchemaKeys(cmd.schema);
-    for (const key of schemaKeys)
-      commandDef.requiredOption(`--${camelToKebab(key)} <value>`, key);
-    commandDef.action(async (opts) => {
-      const result = await cmd.execute(graph, opts);
-      if (result.ok)
-        render(result.value, logger);
-      else
-        renderError(result.error.message, logger);
-    });
+      fail(result.error.type === "auth_cancelled" ? "Logout cancelled" : result.error.message);
+  });
+  logoutCmd.addHelpText("after", [
+    "",
+    "Removes:       ~/.ask-marcel/token-cache.json (access + refresh tokens).",
+    "Leaves alone:  ~/.ask-marcel/browser-profile/ (delete it manually if you want a clean Playwright session too).",
+    "Verify clean:  ls ~/.ask-marcel/  (token-cache.json should be gone)."
+  ].join(`
+  `));
+  const updateCmd = program2.command("update").description("Re-install the latest published ask-marcel from npm, in place. Auto-detects whether you originally installed via npm or bun.").action(async () => {
+    const manager = deps.packageManager ?? detectPackageManager(process.argv[1] ?? "");
+    const result = await execute77(processRunner, manager);
+    if (result.ok)
+      render({ status: "updated", via: manager }, logger);
+    else if (result.error.type === "spawn_failed")
+      fail(`update failed: ${result.error.message}`);
+    else
+      fail(`update install exited with code ${result.error.exitCode}`);
+  });
+  updateCmd.addHelpText("after", [
+    "",
+    "Detection:    based on the bin path of the running CLI.",
+    "              `/usr/local/lib/node_modules/...` -> npm, `~/.bun/install/...` -> bun.",
+    "Side effect:  shells out to `npm i -g ask-marcel-office-cli@latest` or `bun add -g ...`.",
+    "Token cache:  preserved (this only re-installs the JS bundle).",
+    "Local clone:  do NOT use `update` — pull and re-run `bun install` instead."
+  ].join(`
+  `));
+  program2.command("docs").description("Print Markdown docs for a single command (the same per-command page that ships in `docs/commands.json`).").argument("<command>", "Command name to show docs for (run `ask-marcel --help` to list every command).").action((commandName) => {
+    const result = renderSingleCommand(commands, commandName);
+    if (result.ok)
+      process.stdout.write(`${result.value}
+`);
+    else
+      fail(`Unknown command "${result.error.name}". Run \`ask-marcel --help\` to list every command.`);
+  });
+  for (const category of CATEGORY_ORDER) {
+    const entries = Object.entries(commands).filter(([, c]) => c.meta.category === category);
+    if (entries.length === 0)
+      continue;
+    program2.commandsGroup(`${CATEGORY_LABELS[category]}:`);
+    for (const [name, cmd] of entries) {
+      const commandDef = program2.command(name).description(cmd.meta.summary);
+      for (const opt of cmd.meta.options)
+        commandDef.requiredOption(`--${opt.name} <value>`, opt.description);
+      const helpLines = [
+        `
+Graph endpoint: ${cmd.meta.graphMethod} ${cmd.meta.graphPathTemplate}`,
+        `Microsoft Learn: ${cmd.meta.graphDocsUrl}`,
+        ...cmd.meta.bodyTemplate ? [`
+Request body:
+  ${cmd.meta.bodyTemplate}`] : [],
+        `
+Example:
+  ${cmd.meta.example}`
+      ];
+      commandDef.addHelpText("after", helpLines.join(`
+`));
+      commandDef.action(async (opts) => {
+        const result = await cmd.execute(graph, opts);
+        if (result.ok)
+          render(result.value, logger);
+        else
+          fail(result.error.message);
+      });
+    }
   }
   return program2;
 };
-var getSchemaKeys = (schema89) => {
-  const def = schema89;
-  const shape = def.shape;
-  if (shape)
-    return Object.keys(shape);
-  return [];
-};
-var camelToKebab = (s) => s.replaceAll(/([A-Z])/g, "-$1").toLowerCase();
 
 // src/main.ts
 var ONE_WEEK_MS = 1000 * 60 * 60 * 24 * 7;
 var main = async () => {
   updateNotifier({ pkg: { name: package_default.name, version: package_default.version }, updateCheckInterval: ONE_WEEK_MS }).notify({ defer: false });
   const deps = buildDeps();
-  const cli = buildCli({ auth: deps.auth, graph: deps.graph, logger: deps.logger, version: package_default.version });
+  const cli = buildCli({
+    auth: deps.auth,
+    graph: deps.graph,
+    logger: deps.logger,
+    processRunner: deps.processRunner,
+    version: package_default.version,
+    onCommandError: () => {
+      process.exitCode = 1;
+    }
+  });
   await cli.parseAsync();
 };
 try {