Initial commit: Microsoft To Do for Claude (skill + .mcpb extension)

Claude Code skill (CLI over Microsoft Graph, delegated auth-code + PKCE) and a Claude Desktop .mcpb extension sharing one dependency-free core client. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-16 17:31:48 -06:00
commit 2162aac515
16 changed files with 3385 additions and 0 deletions
--- a/.claude/skills/ms-todo/.env.example
+++ b/.claude/skills/ms-todo/.env.example
@@ -0,0 +1,25 @@
+# Copy to ".env" in this folder and fill in. Git-ignored — never commit real values.
+
+# Application (client) ID of an Entra PUBLIC client app with the delegated
+# Tasks.ReadWrite permission. See references/setup.md.
+TODO_CLIENT_ID=00000000-0000-0000-0000-000000000000
+
+# Optional. Default "common" (work/school OR personal accounts).
+#   - a tenant GUID/domain  -> work/school accounts in that tenant only
+#   - "organizations"       -> any work/school account
+#   - "consumers"           -> personal Microsoft accounts only
+# TODO_TENANT_ID=common
+
+# Optional. Where to cache the signed-in token (refresh token).
+# Default: .token-cache.json next to scripts/. Keep it OUT of git.
+# TODO_TOKEN_CACHE=/absolute/path/to/.token-cache.json
+
+# Optional. Pin the loopback redirect port used during `login`. Default: the OS
+# picks a free port (works when http://localhost is registered, since Entra
+# ignores the port for loopback). Set this only if your tenant requires an exact
+# redirect URI, then register http://127.0.0.1:<port> in the app.
+# TODO_REDIRECT_PORT=53682
+
+# Optional. Time zone applied to --due / --start / --reminder dates (default UTC).
+# Accepts IANA (e.g. America/Denver) or Windows zone names.
+# TODO_TIMEZONE=UTC
--- a/.claude/skills/ms-todo/.gitignore
+++ b/.claude/skills/ms-todo/.gitignore
@@ -0,0 +1,4 @@
+# Secrets and cached credentials — never commit.
+.env
+.token-cache.json
+scripts/.token-cache.json
--- a/.claude/skills/ms-todo/SKILL.md
+++ b/.claude/skills/ms-todo/SKILL.md
@@ -0,0 +1,194 @@
+---
+name: ms-todo
+description: >-
+  Read and write Microsoft To Do tasks via the Microsoft Graph API using
+  delegated (browser, auth-code + PKCE) authentication. Use this skill whenever the user wants
+  to view, list, search, add, create, update, complete, check off, or delete
+  their Microsoft To Do tasks, task lists, or subtasks/checklist items — even if
+  they just say "my to-dos", "my tasks", "my task list", "add a reminder", "what's
+  on my list", or name a specific To Do list rather than saying "Microsoft To Do"
+  explicitly. Also use it for bulk operations over tasks (export, reporting, batch
+  complete/clean-up) and for sign-in/connectivity troubleshooting against To Do.
+  This is for Microsoft *To Do* (personal tasks in a user's mailbox), not Planner,
+  Project, or SharePoint task lists.
+---
+
+# Microsoft To Do
+
+Connect to Microsoft To Do and perform full CRUD (create, read, update, delete)
+on task lists, tasks, and checklist items (subtasks) through the Microsoft Graph
+API.
+
+**Authentication is delegated, not app-only.** Microsoft To Do has *no*
+application permission — the Graph `/me/todo` endpoints only accept a signed-in
+user's token. This skill uses the OAuth2 **authorization-code + PKCE** flow:
+`login` opens your browser, you sign in, and the refresh token is cached locally
+so later runs refresh silently. This is the key difference from an app-only
+integration like SharePoint Lists — there are no `*_CLIENT_SECRET` credentials
+and a human must sign in the first time. (A browser flow is used rather than
+device-code because device-code is often blocked by Conditional Access —
+AADSTS53003.)
+
+All operations go through one CLI, `scripts/todo.mjs`, which wraps the reusable
+core client in `scripts/lib/graph.mjs`. Run it with Node (already available):
+
+```bash
+node scripts/todo.mjs <command> [flags]
+```
+
+> Paths above are relative to this skill's directory. From elsewhere, use the
+> absolute path, e.g. `node "<skill-dir>/scripts/todo.mjs" ...`.
+
+## Prerequisites (one-time)
+
+You need an Entra (Azure AD) **public client** app registration with the
+delegated `Tasks.ReadWrite` permission. It requires only one value:
+
+- `TODO_CLIENT_ID` — Application (client) ID
+- `TODO_TENANT_ID` — optional; defaults to `common` (use a tenant id for
+  work/school-only apps, or `consumers` for personal Microsoft accounts only)
+
+Set them as environment variables, or copy `.env.example` to `.env` in this
+skill's directory and fill it in (the CLI loads `.env` automatically; `.env` is
+git-ignored).
+
+**If the app registration is not yet set up**, do not guess — point the user to
+[references/setup.md](references/setup.md), a step-by-step walkthrough of creating
+the public-client app, adding the loopback redirect URI, adding the delegated
+`Tasks.ReadWrite` permission, and signing in.
+
+## First step in any task: sign in, then verify
+
+Sign in once (interactive — the user must complete it in a browser):
+
+```bash
+node scripts/todo.mjs login
+```
+
+This opens the user's browser to the Microsoft sign-in page (and prints the URL
+as a fallback). The user signs in and approves; the browser redirects back to a
+temporary local server and the refresh token is cached to
+`scripts/.token-cache.json` (git-ignored). Run `login` on the same machine as the
+browser. After that, confirm everything works:
+
+```bash
+node scripts/todo.mjs test
+```
+
+A successful response shows who is signed in and the names of their task lists.
+If any command returns `"needsLogin": true`, the cached sign-in is missing or
+expired — run `login` again.
+
+## Identifying a list
+
+- A **task list** can be given by display name (e.g. `"Groceries"`) or by its
+  opaque list id. The client resolves names to ids and, on a typo, lists the
+  available names so you can correct it.
+- To Do list ids are long opaque strings (not GUIDs), so prefer the display name
+  unless you already have the id from a previous call.
+
+When unsure what lists exist, discover first:
+
+```bash
+node scripts/todo.mjs lists
+```
+
+## Reading tasks
+
+```bash
+# Everything in a list (follows pagination):
+node scripts/todo.mjs tasks --list "Groceries" --all
+
+# Open tasks only, soonest due first, projected:
+node scripts/todo.mjs tasks --list "Work" \
+  --filter "status ne 'completed'" \
+  --select "title,status,dueDateTime,importance" \
+  --orderby "dueDateTime/dateTime asc" --top 50
+
+# One task by id:
+node scripts/todo.mjs get --list "Work" --id "<TASK_ID>"
+```
+
+Tasks come back simplified (id, title, status, importance, due/start/reminder
+date-times, body, categories, timestamps). See
+[references/graph-api.md](references/graph-api.md) for the full property set and
+OData query details.
+
+## Writing tasks
+
+Convenience flags cover the common properties; `--fields` (inline JSON,
+`@file.json`, or `-` for stdin) merges on top for anything else.
+
+```bash
+# Create
+node scripts/todo.mjs create --list "Work" \
+  --title "Renew SSL cert" --due 2026-07-01 --importance high \
+  --body "Use the prod ACME account"
+
+# Update (partial — only what you pass changes)
+node scripts/todo.mjs update --list "Work" --id "<TASK_ID>" --status inProgress
+
+# Complete (shorthand for --status completed)
+node scripts/todo.mjs done --list "Work" --id "<TASK_ID>"
+
+# Delete
+node scripts/todo.mjs delete --list "Work" --id "<TASK_ID>"
+```
+
+`--due`, `--start`, and `--reminder` accept `2026-07-01` or a full date-time and
+are converted to Graph's `dateTimeTimeZone` shape using `TODO_TIMEZONE` (default
+`UTC`). Setting `--reminder` also turns the reminder on.
+
+**Deletes are irreversible.** Confirm the task id with the user before deleting,
+and prefer showing them the task via `get` first. For bulk deletes, confirm the
+full set once, then proceed.
+
+## Task lists and checklist items
+
+```bash
+# Lists
+node scripts/todo.mjs list-create --name "Trip planning"
+node scripts/todo.mjs list-update --list "Trip planning" --name "Italy trip"
+node scripts/todo.mjs list-delete --list "Italy trip"      # deletes its tasks too — confirm first
+
+# Checklist items (subtasks) on a task
+node scripts/todo.mjs checklist        --list "Work" --id "<TASK_ID>"
+node scripts/todo.mjs checklist-add    --list "Work" --id "<TASK_ID>" --name "Draft email"
+node scripts/todo.mjs checklist-check  --list "Work" --id "<TASK_ID>" --item "<ITEM_ID>"   # --uncheck to undo
+node scripts/todo.mjs checklist-delete --list "Work" --id "<TASK_ID>" --item "<ITEM_ID>"
+```
+
+## Bulk operations
+
+For exports or batch edits, fetch with `--all`, transform the JSON however the
+task needs, then loop the relevant `create`/`update`/`done`/`delete` calls. Keep
+concurrency modest — Graph throttles with HTTP 429; the client already retries
+with backoff, but don't fan out hundreds of parallel writes.
+
+## Handling errors
+
+The CLI prints a JSON error to stderr and exits non-zero. Common cases:
+
+- `"needsLogin": true` → no cached sign-in or the refresh token expired/was
+  revoked. Run `node scripts/todo.mjs login`.
+- `401`/`403` right after login → the app is missing the delegated
+  `Tasks.ReadWrite` permission, or consent wasn't granted — see
+  [references/setup.md](references/setup.md).
+- `AADSTS53003` during sign-in → a Conditional Access policy blocked it. This
+  browser flow avoids device-code-specific blocks; if the policy requires a
+  compliant/managed device, the device must be enrolled first. See setup.
+- `AADSTS50011` (redirect mismatch) → register `http://localhost` **and**
+  `http://127.0.0.1` under the app's Mobile-and-desktop platform. See setup.
+- `400` on a write → usually a bad property name or value format (e.g. a date not
+  in `dateTimeTimeZone` shape, or an invalid `status`/`importance` enum). Check
+  [references/graph-api.md](references/graph-api.md).
+- `404` on a list → wrong name; run `lists` to see valid names.
+
+## Note on graduating to an MCP server
+
+The core logic is isolated in `scripts/lib/graph.mjs` (the `MSTodoClient` class,
+zero dependencies). To expose this as a standalone MCP server later, import that
+class and expose its methods (`listTasks`, `getTask`, `createTask`, `updateTask`,
+`deleteTask`, list/checklist methods) as MCP tools — no rewrite of the Graph or
+auth logic needed. The only wrinkle vs. an app-only server: the browser `login`
+must be run once on the host to seed the token cache the server reads.
--- a/.claude/skills/ms-todo/references/graph-api.md
+++ b/.claude/skills/ms-todo/references/graph-api.md
@@ -0,0 +1,112 @@
+# Graph API reference for Microsoft To Do
+
+Quick reference for the parts of the Microsoft Graph To Do API this skill relies
+on. Full docs: <https://learn.microsoft.com/graph/api/resources/todo-overview>.
+
+## Object model
+
+```
+/me/todo/lists                                  todoTaskList[]   (the task lists)
+/me/todo/lists/{listId}/tasks                   todoTask[]       (tasks in a list)
+/me/todo/lists/{listId}/tasks/{taskId}/checklistItems   checklistItem[]  (subtasks)
+```
+
+- **List ids** are long opaque strings (base64-ish), *not* GUIDs. Resolve by
+  display name when you can.
+- **Task ids** and **checklist item ids** are also opaque strings returned by the
+  API; pass them back verbatim.
+
+## todoTask properties (create / update)
+
+`--fields` (and the convenience flags) map to these `todoTask` properties:
+
+| Property | JSON value | Notes / example |
+|---|---|---|
+| `title` | string | **Required on create.** `{"title":"Buy milk"}` |
+| `body` | `{ "content": "...", "contentType": "text"\|"html" }` | `--body` builds the `text` form |
+| `importance` | `"low"` \| `"normal"` \| `"high"` | enum — exact strings |
+| `status` | `"notStarted"` \| `"inProgress"` \| `"completed"` \| `"waitingOnOthers"` \| `"deferred"` | enum |
+| `dueDateTime` | `dateTimeTimeZone` (see below) | `--due` builds this |
+| `startDateTime` | `dateTimeTimeZone` | `--start` builds this |
+| `reminderDateTime` | `dateTimeTimeZone` | set `isReminderOn:true` too (`--reminder` does both) |
+| `isReminderOn` | boolean | |
+| `categories` | array of strings | must match category names defined in the user's Outlook |
+| `recurrence` | `patternedRecurrence` object | advanced; pass via `--fields` |
+
+Read-only properties returned on GET (don't send them on write):
+`id`, `createdDateTime`, `lastModifiedDateTime`, `completedDateTime`,
+`hasAttachments`.
+
+### `dateTimeTimeZone` shape
+
+Date/time properties are **not** plain ISO strings — they're an object:
+
+```json
+{ "dueDateTime": { "dateTime": "2026-07-01T17:00:00", "timeZone": "UTC" } }
+```
+
+The CLI's `--due` / `--start` / `--reminder` accept `2026-07-01` (→ midnight) or a
+full `2026-07-01T17:00:00`, and wrap it using `TODO_TIMEZONE` (default `UTC`). The
+`timeZone` accepts IANA (`America/Denver`) or Windows (`Mountain Standard Time`)
+zone names. To set one manually via `--fields`, supply the full object.
+
+### Marking complete
+
+Set `status` to `"completed"` (the `done` command does this). Graph stamps
+`completedDateTime` automatically. Setting status back to `notStarted`/
+`inProgress` reopens it.
+
+## Querying tasks (OData)
+
+The CLI maps flags to OData query options on `/me/todo/lists/{listId}/tasks`:
+
+- `--filter` → `$filter`. To Do supports a subset of OData. Useful ones:
+  - `status ne 'completed'` — open tasks
+  - `status eq 'completed'`
+  - `importance eq 'high'`
+  - `lastModifiedDateTime gt 2026-06-01T00:00:00Z`
+  - combine with `and` / `or`
+  - Note: filtering directly on `dueDateTime` is limited; prefer fetching and
+    sorting client-side for due-date views.
+- `--orderby` → `$orderby`, e.g. `dueDateTime/dateTime asc` (nested path), or
+  `importance desc`, `lastModifiedDateTime desc`, `createdDateTime asc`.
+- `--select` → projects which properties come back: `title,status,dueDateTime`.
+- `--top` → page size; `--all` follows `@odata.nextLink` to return every page.
+
+### Escaping quotes
+
+OData string literals use single quotes; a literal single quote is doubled:
+`title eq 'O''Brien'`. In the shell, wrap the whole `--filter` value in double
+quotes.
+
+## Checklist items (subtasks)
+
+A `checklistItem` has just `displayName` and `isChecked`:
+
+```bash
+node scripts/todo.mjs checklist-add   --list "Work" --id "<TASK_ID>" --name "Draft outline"
+node scripts/todo.mjs checklist-check --list "Work" --id "<TASK_ID>" --item "<ITEM_ID>"   # --uncheck to undo
+```
+
+## Response shape (reads)
+
+Reads return tasks simplified to:
+
+```json
+{
+  "id": "<opaque task id>",
+  "title": "Renew SSL cert",
+  "status": "inProgress",
+  "importance": "high",
+  "isReminderOn": true,
+  "dueDateTime": { "dateTime": "2026-07-01T00:00:00.0000000", "timeZone": "UTC" },
+  "reminderDateTime": { "dateTime": "2026-06-30T09:00:00.0000000", "timeZone": "UTC" },
+  "body": { "content": "Use the prod ACME account", "contentType": "text" },
+  "categories": [],
+  "createdDateTime": "2026-06-16T10:00:00Z",
+  "lastModifiedDateTime": "2026-06-16T12:30:00Z"
+}
+```
+
+`id` is the value you pass to `get`, `update`, `done`, and `delete`. Empty/unset
+properties are omitted from the simplified shape.
--- a/.claude/skills/ms-todo/references/setup.md
+++ b/.claude/skills/ms-todo/references/setup.md
@@ -0,0 +1,144 @@
+# Setup: Entra app registration for Microsoft To Do (delegated, browser auth-code)
+
+Microsoft To Do has **no app-only access** — its Graph endpoints (`/me/todo/...`)
+only accept a signed-in user's token. So this skill authenticates as **you**
+(delegated) using the OAuth2 **authorization-code + PKCE** flow: `login` opens
+your system browser, you sign in, and the browser redirects back to a temporary
+local server. You create a *public client* app registration once, grant it the
+delegated To Do permission, and sign in once per machine. There is no client
+secret.
+
+> Why browser auth-code and not device-code? Many tenants block the device-code
+> flow with a Conditional Access policy (error **AADSTS53003**). The browser flow
+> runs in your real browser session, satisfying far more policies. If a policy
+> requires a *compliant/managed device*, the Mac must be registered/enrolled
+> (Company Portal/Intune) first — no flow can bypass that.
+
+You do **not** need to be an admin if your tenant allows users to consent to the
+`Tasks.ReadWrite` delegated permission (it is a low-risk, user-consentable
+permission by default). If admin consent is required in your org, ask an admin to
+grant it once.
+
+## 1. Register the application
+
+1. Go to <https://entra.microsoft.com> → **Identity** → **Applications** →
+   **App registrations** → **New registration**.
+2. Name it something recognizable, e.g. `claude-ms-todo`.
+3. Supported account types:
+   - work/school only → **Accounts in this organizational directory only**
+   - also personal Microsoft accounts → **... and personal Microsoft accounts**
+4. Leave **Redirect URI** blank for now — you'll add it in step 2.
+5. **Register**.
+
+On the app's **Overview** page, copy:
+- **Application (client) ID** → `TODO_CLIENT_ID`
+- **Directory (tenant) ID** → `TODO_TENANT_ID` (optional; `common` also works)
+
+## 2. Add a loopback redirect URI (public client)
+
+1. App → **Authentication** → **Add a platform** → **Mobile and desktop
+   applications**.
+2. Under **Custom redirect URIs**, add **both**:
+   - `http://localhost`
+   - `http://127.0.0.1`
+   (Adding both avoids IPv4/IPv6 surprises. The skill redirects to
+   `http://127.0.0.1:<port>` at runtime; Entra ignores the port for loopback
+   redirects, so the OS-assigned port needs no registration.)
+3. **Configure** / **Save**.
+
+This marks the app as a public client for that redirect — no client secret is
+needed; PKCE protects the code exchange. (You do **not** need "Allow public
+client flows" for auth-code+PKCE.)
+
+## 3. Add the delegated Graph permission
+
+App → **API permissions** → **Add a permission** → **Microsoft Graph** →
+**Delegated permissions**. Add:
+
+| Permission | Why |
+|---|---|
+| **`Tasks.ReadWrite`** | Read/write the signed-in user's To Do tasks & lists |
+| `offline_access` | Issue a refresh token so sign-in persists (usually added automatically) |
+| `User.Read` | Identify the signed-in user in `test` (usually present by default) |
+
+If your tenant requires it, click **Grant admin consent for &lt;tenant&gt;**.
+Otherwise consent happens interactively during the first `login`.
+
+> Use `Tasks.Read` instead of `Tasks.ReadWrite` if you want read-only access.
+> The skill's write commands will then return `403`.
+
+## 4. Give the skill the client id
+
+Copy `.env.example` to `.env` in the skill directory and set `TODO_CLIENT_ID`
+(and `TODO_TENANT_ID` if not `common`). The CLI loads `.env` automatically, and
+`.env` is git-ignored. Alternatively, export them as environment variables.
+
+## 5. Sign in (once)
+
+```bash
+node scripts/todo.mjs login
+```
+
+This opens your **system browser** to the Microsoft sign-in page (and prints the
+URL as a fallback if it can't auto-open). Sign in and approve; the browser
+redirects to a temporary local server and you'll see "Signed in ✓". The refresh
+token is cached to `scripts/.token-cache.json` (git-ignored, written with `0600`
+perms). The CLI refreshes silently after that — you won't be asked again until
+the refresh token expires or is revoked.
+
+> Run `login` on the machine whose browser you'll use; the temporary redirect
+> server listens on `127.0.0.1`, so the browser and the CLI must be on the same
+> host (not over plain SSH without port forwarding).
+
+## 6. Verify
+
+```bash
+node scripts/todo.mjs test
+```
+
+Expected: `{ "ok": true, "signedInAs": "you@contoso.com", "listCount": N, "lists": [...] }`.
+
+Troubleshooting:
+- **`AADSTS53003` (blocked by Conditional Access)** — a CA policy blocked the
+  sign-in. If it targets the *device-code* flow specifically, this browser flow
+  already avoids it. If it requires a **compliant/managed device** (your device
+  shows as *Unregistered*), enroll the Mac (Company Portal/Intune) or have an
+  admin exclude this app. Use the sign-in log's Correlation Id to find the exact
+  policy.
+- **`redirect_uri` mismatch (`AADSTS50011`)** — add both `http://localhost` and
+  `http://127.0.0.1` under the Mobile-and-desktop platform (step 2).
+- **Browser redirect never returns / connection refused** — something else holds
+  the port, or you're on a remote/SSH session. Run `login` locally, or pin a port
+  with `TODO_REDIRECT_PORT` and register `http://127.0.0.1:<port>`.
+- **`AADSTS65001` / consent error during sign-in** — the org requires admin
+  consent for `Tasks.ReadWrite`; have an admin grant it (step 3).
+- **`test` returns `403`** — the delegated `Tasks.ReadWrite` permission is
+  missing or only `Tasks.Read` was granted.
+- **Any command returns `"needsLogin": true`** — the cached refresh token is gone
+  or expired; run `login` again.
+- **Personal Microsoft account won't work** — set `TODO_TENANT_ID=consumers` (or
+  `common`) and register the app for personal accounts in step 1.
+
+---
+
+## Note: graduating to an MCP server
+
+When you want this available across all sessions as native tools rather than a
+CLI, build a small MCP server that imports `scripts/lib/graph.mjs`:
+
+```js
+import { MSTodoClient } from "./graph.mjs";
+const client = new MSTodoClient({
+  clientId: process.env.TODO_CLIENT_ID,
+  tenantId: process.env.TODO_TENANT_ID,
+  tokenCachePath: process.env.TODO_TOKEN_CACHE,
+});
+// Expose client.listTasks / getTask / createTask / updateTask / deleteTask
+// (and the list/checklist methods) as MCP tools.
+```
+
+The client is dependency-free; its only state is the on-disk token cache. The one
+difference from an app-only server: you must run `login` once on the host to seed
+that cache before the server can call Graph. For a containerized HTTP transport,
+mount the token-cache file as a volume and guard the `/mcp` endpoint with a bearer
+token — the server acts as the single signed-in user.
--- a/.claude/skills/ms-todo/scripts/lib/graph.mjs
+++ b/.claude/skills/ms-todo/scripts/lib/graph.mjs
@@ -0,0 +1,642 @@
+// Microsoft To Do core client — Microsoft Graph, DELEGATED (auth-code + PKCE).
+//
+// Zero dependencies. Uses Node's global fetch (Node 18+). This module is the
+// single source of truth for talking to Microsoft To Do; the CLI (todo.mjs) is a
+// thin wrapper around it, and a future MCP server can import this same class.
+//
+// Auth model — IMPORTANT: Microsoft To Do does NOT support app-only access.
+// The Graph /me/todo endpoints only accept *delegated* permissions
+// (Tasks.ReadWrite), so a user must sign in. We use the OAuth2 *authorization
+// code* flow with PKCE and a loopback (http://localhost) redirect: `login` opens
+// the system browser, the user signs in, and the refresh token is cached to disk
+// so subsequent runs refresh silently — no client secret, works with MFA.
+//
+// Why not device-code? Many tenants block the device-code flow via Conditional
+// Access (AADSTS53003), because it's headless. The browser-based auth-code flow
+// runs in the device's real browser session, so it satisfies far more CA
+// policies. (If a policy still requires a *compliant/managed device*, the Mac
+// must be registered/enrolled first — no auth flow can bypass that.)
+//
+// The app registration must register a public-client redirect URI of
+// http://localhost ("Mobile and desktop applications" platform) and hold the
+// delegated Tasks.ReadWrite (+ offline_access, openid, profile, User.Read)
+// permission. See references/setup.md.
+
+import { readFileSync, writeFileSync, existsSync, rmSync, chmodSync } from "node:fs";
+import { createServer } from "node:http";
+import { randomBytes, createHash } from "node:crypto";
+import { spawn } from "node:child_process";
+
+const LOGIN_HOST = "https://login.microsoftonline.com";
+const GRAPH_ROOT = "https://graph.microsoft.com/v1.0";
+
+// offline_access -> refresh token; openid/profile -> id_token (who signed in);
+// User.Read -> identify the user in `test`; Tasks.ReadWrite -> full To Do CRUD.
+const SCOPES = "offline_access openid profile User.Read Tasks.ReadWrite";
+
+/** Error carrying the Graph status code + structured error body, when present. */
+export class GraphError extends Error {
+  constructor(message, { status, code, requestId, body } = {}) {
+    super(message);
+    this.name = "GraphError";
+    this.status = status;
+    this.code = code;
+    this.requestId = requestId;
+    this.body = body;
+  }
+}
+
+/** Thrown when there is no cached login (or the refresh token is dead). */
+export class AuthRequiredError extends Error {
+  constructor(message = 'Not signed in. Run "node todo.mjs login" first.') {
+    super(message);
+    this.name = "AuthRequiredError";
+  }
+}
+
+export class MSTodoClient {
+  /**
+   * @param {object} cfg
+   * @param {string} cfg.clientId   Application (client) ID of a PUBLIC client app.
+   * @param {string} [cfg.tenantId="common"] Tenant id / "common" / "organizations" / "consumers".
+   * @param {string} cfg.tokenCachePath Absolute path to the JSON token cache file.
+   * @param {number} [cfg.redirectPort=0] Loopback port for the auth-code redirect.
+   *   0 = let the OS pick (works when http://localhost is registered, since Entra
+   *   ignores the port for loopback). Pin it only if your tenant requires an exact
+   *   redirect URI (then register http://localhost:<port>).
+   * @param {number} [cfg.maxRetries=3] Retries for 429/503 (honors Retry-After).
+   */
+  constructor({ clientId, tenantId = "common", tokenCachePath, redirectPort = 0, maxRetries = 3 } = {}) {
+    if (!clientId) {
+      throw new Error("Missing clientId (set TODO_CLIENT_ID). See references/setup.md.");
+    }
+    if (!tokenCachePath) {
+      throw new Error("Missing tokenCachePath.");
+    }
+    this.clientId = clientId;
+    this.tenantId = tenantId || "common";
+    this.tokenCachePath = tokenCachePath;
+    this.redirectPort = redirectPort;
+    this.maxRetries = maxRetries;
+    this._cache = null; // lazy-loaded { accessToken, expiresAt, refreshToken, ... }
+    this._listCache = new Map(); // nameOrId(lower) -> list object
+  }
+
+  // ---- Token cache (on disk) ---------------------------------------------
+
+  _loadCache() {
+    if (this._cache) return this._cache;
+    if (!existsSync(this.tokenCachePath)) return null;
+    try {
+      this._cache = JSON.parse(readFileSync(this.tokenCachePath, "utf8"));
+    } catch {
+      this._cache = null;
+    }
+    return this._cache;
+  }
+
+  _saveCache(tokens) {
+    const cache = {
+      clientId: this.clientId,
+      tenantId: this.tenantId,
+      accessToken: tokens.access_token,
+      expiresAt: Date.now() + (tokens.expires_in ?? 3600) * 1000,
+      refreshToken: tokens.refresh_token ?? this._cache?.refreshToken,
+      scope: tokens.scope ?? SCOPES,
+      account: tokens.account ?? this._cache?.account,
+    };
+    writeFileSync(this.tokenCachePath, JSON.stringify(cache, null, 2));
+    try {
+      chmodSync(this.tokenCachePath, 0o600); // best-effort; refresh token is sensitive
+    } catch {
+      /* ignore (e.g. on filesystems without POSIX modes) */
+    }
+    this._cache = cache;
+    return cache;
+  }
+
+  /** Remove the cached login. Returns true if a cache file existed. */
+  logout() {
+    this._cache = null;
+    if (existsSync(this.tokenCachePath)) {
+      rmSync(this.tokenCachePath);
+      return true;
+    }
+    return false;
+  }
+
+  isLoggedIn() {
+    const c = this._loadCache();
+    return Boolean(c?.refreshToken);
+  }
+
+  // ---- Auth ---------------------------------------------------------------
+
+  /**
+   * Interactive sign-in via the authorization-code + PKCE flow. Spins up a
+   * temporary loopback HTTP server, opens the system browser to the Entra
+   * authorize page, captures the redirect, exchanges the code for tokens, and
+   * persists them to the cache file. Returns the cached account.
+   *
+   * @param {(info:{authorizeUrl:string,redirectUri:string})=>void} [onPrompt]
+   *   Called with the URL being opened (so the CLI can print it as a fallback).
+   * @param {object} [opts]
+   * @param {number} [opts.timeoutMs=300000] How long to wait for the redirect.
+   */
+  async login(onPrompt, { timeoutMs = 300_000 } = {}) {
+    const verifier = base64url(randomBytes(32));
+    const challenge = base64url(createHash("sha256").update(verifier).digest());
+    const state = base64url(randomBytes(16));
+
+    // Start the loopback server first so we know the actual port for redirect_uri.
+    const { server, port, waitForCode } = await startRedirectServer(
+      state,
+      timeoutMs,
+      this.redirectPort,
+    );
+    // 127.0.0.1 (not "localhost") so the bind address and the browser's target
+    // always agree, even on IPv6-first hosts. Register http://localhost AND
+    // http://127.0.0.1 in the app so either works. Entra ignores the port for
+    // loopback redirects, so the OS-assigned port needs no registration.
+    const redirectUri = `http://127.0.0.1:${port}`;
+
+    const authorizeUrl =
+      `${LOGIN_HOST}/${encodeURIComponent(this.tenantId)}/oauth2/v2.0/authorize?` +
+      new URLSearchParams({
+        client_id: this.clientId,
+        response_type: "code",
+        redirect_uri: redirectUri,
+        response_mode: "query",
+        scope: SCOPES,
+        state,
+        code_challenge: challenge,
+        code_challenge_method: "S256",
+        prompt: "select_account",
+      });
+
+    if (typeof onPrompt === "function") onPrompt({ authorizeUrl, redirectUri });
+    openBrowser(authorizeUrl);
+
+    let code;
+    try {
+      code = await waitForCode;
+    } finally {
+      server.close();
+    }
+
+    const tokRes = await fetch(
+      `${LOGIN_HOST}/${encodeURIComponent(this.tenantId)}/oauth2/v2.0/token`,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({
+          grant_type: "authorization_code",
+          client_id: this.clientId,
+          code,
+          redirect_uri: redirectUri,
+          code_verifier: verifier,
+          scope: SCOPES,
+        }),
+      },
+    );
+    const tok = await tokRes.json().catch(() => ({}));
+    if (!tokRes.ok) {
+      throw new GraphError(
+        `Token exchange failed (${tokRes.status}): ${tok.error_description || tok.error || tokRes.statusText}`,
+        { status: tokRes.status, code: tok.error, body: tok },
+      );
+    }
+    this._saveCache({ ...tok, account: accountFromIdToken(tok.id_token) });
+    return this._cache.account ?? { ok: true };
+  }
+
+  /** Get a valid access token, refreshing with the cached refresh token if needed. */
+  async getToken() {
+    const cache = this._loadCache();
+    if (!cache?.refreshToken) throw new AuthRequiredError();
+    if (cache.accessToken && cache.expiresAt - 60_000 > Date.now()) {
+      return cache.accessToken;
+    }
+    const res = await fetch(
+      `${LOGIN_HOST}/${encodeURIComponent(this.tenantId)}/oauth2/v2.0/token`,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({
+          grant_type: "refresh_token",
+          client_id: this.clientId,
+          refresh_token: cache.refreshToken,
+          scope: SCOPES,
+        }),
+      },
+    );
+    const json = await res.json().catch(() => ({}));
+    if (!res.ok) {
+      // invalid_grant => the refresh token is revoked/expired; force re-login.
+      if (json.error === "invalid_grant") {
+        throw new AuthRequiredError(
+          'Saved sign-in expired or was revoked. Run "node todo.mjs login" again.',
+        );
+      }
+      throw new GraphError(
+        `Token refresh failed (${res.status}): ${json.error_description || json.error || res.statusText}`,
+        { status: res.status, code: json.error, body: json },
+      );
+    }
+    this._saveCache(json);
+    return this._cache.accessToken;
+  }
+
+  // ---- Low-level request --------------------------------------------------
+
+  /**
+   * Make a Graph request. `path` is relative to the v1.0 root (e.g. "/me/todo/lists").
+   * @param {string} method
+   * @param {string} path
+   * @param {object} [opts]
+   * @param {object} [opts.query]    Query params; keys starting with "$" are OData.
+   * @param {object} [opts.body]     JSON body (will be stringified).
+   * @param {object} [opts.headers]  Extra headers (e.g. Prefer).
+   */
+  async graph(method, path, { query, body, headers } = {}) {
+    const url = new URL(path.startsWith("http") ? path : `${GRAPH_ROOT}${path}`);
+    if (query) {
+      for (const [k, v] of Object.entries(query)) {
+        if (v !== undefined && v !== null && v !== "") url.searchParams.set(k, v);
+      }
+    }
+    for (let attempt = 0; ; attempt++) {
+      const token = await this.getToken();
+      const res = await fetch(url, {
+        method,
+        headers: {
+          Authorization: `Bearer ${token}`,
+          Accept: "application/json",
+          ...(body ? { "Content-Type": "application/json" } : {}),
+          ...headers,
+        },
+        body: body ? JSON.stringify(body) : undefined,
+      });
+
+      if ((res.status === 429 || res.status === 503) && attempt < this.maxRetries) {
+        const retryAfter = Number(res.headers.get("Retry-After")) || 2 ** attempt;
+        await sleep(retryAfter * 1000);
+        continue;
+      }
+
+      if (res.status === 204) return null; // No Content (e.g. DELETE)
+      const json = await res.json().catch(() => null);
+      if (!res.ok) {
+        const err = json?.error || {};
+        throw new GraphError(
+          `Graph ${method} ${url.pathname} failed (${res.status}): ${err.message || res.statusText}`,
+          {
+            status: res.status,
+            code: err.code,
+            requestId: res.headers.get("request-id"),
+            body: json,
+          },
+        );
+      }
+      return json;
+    }
+  }
+
+  /** Identify the signed-in user. */
+  async me() {
+    return this.graph("GET", "/me", {
+      query: { $select: "id,displayName,userPrincipalName,mail" },
+    });
+  }
+
+  // ---- Task lists ---------------------------------------------------------
+
+  /** List all To Do task lists. */
+  async listTaskLists() {
+    const data = await this.graph("GET", "/me/todo/lists");
+    return data.value;
+  }
+
+  /**
+   * Resolve a list identifier (opaque list id or display name) to its id.
+   * To Do list ids are long opaque strings, not GUIDs, so we always check
+   * display names too. Caches per identifier.
+   */
+  async resolveListId(listIdOrName) {
+    if (!listIdOrName) throw new Error("A list id or name is required.");
+    const key = listIdOrName.toLowerCase();
+    if (this._listCache.has(key)) return this._listCache.get(key).id;
+
+    const lists = await this.listTaskLists();
+    // Exact id match first (ids are case-sensitive opaque strings).
+    let match = lists.find((l) => l.id === listIdOrName);
+    if (!match) {
+      match = lists.find((l) => l.displayName?.toLowerCase() === key);
+    }
+    if (!match) {
+      const names = lists.map((l) => l.displayName).join(", ");
+      throw new Error(
+        `No task list named "${listIdOrName}". Available: ${names || "(none)"}`,
+      );
+    }
+    this._listCache.set(key, match);
+    return match.id;
+  }
+
+  /** Create a task list. */
+  async createTaskList(displayName) {
+    if (!displayName) throw new Error("displayName is required.");
+    this._listCache.clear();
+    return this.graph("POST", "/me/todo/lists", { body: { displayName } });
+  }
+
+  /** Rename a task list. */
+  async updateTaskList(listIdOrName, displayName) {
+    const listId = await this.resolveListId(listIdOrName);
+    this._listCache.clear();
+    return this.graph("PATCH", `/me/todo/lists/${listId}`, { body: { displayName } });
+  }
+
+  /** Delete a task list (and all its tasks). */
+  async deleteTaskList(listIdOrName) {
+    const listId = await this.resolveListId(listIdOrName);
+    await this.graph("DELETE", `/me/todo/lists/${listId}`);
+    this._listCache.clear();
+    return true;
+  }
+
+  // ---- Tasks: read --------------------------------------------------------
+
+  /**
+   * List tasks in a list.
+   * @param {object} [opts]
+   * @param {string} [opts.filter]  OData $filter, e.g. "status ne 'completed'".
+   * @param {string} [opts.select]  Comma list of properties, e.g. "title,status,dueDateTime".
+   * @param {string} [opts.orderby] e.g. "dueDateTime/dateTime asc".
+   * @param {number} [opts.top]     Page size / max when not fetching all.
+   * @param {boolean}[opts.all]     Follow @odata.nextLink to fetch every page.
+   */
+  async listTasks(listIdOrName, opts = {}) {
+    const listId = await this.resolveListId(listIdOrName);
+    const { filter, select, orderby, top, all = false } = opts;
+    const query = { $filter: filter, $select: select, $orderby: orderby, $top: top };
+
+    let data = await this.graph("GET", `/me/todo/lists/${listId}/tasks`, { query });
+    const tasks = data.value.map(simplifyTask);
+    if (!all) return tasks;
+
+    while (data["@odata.nextLink"]) {
+      data = await this.graph("GET", data["@odata.nextLink"]);
+      tasks.push(...data.value.map(simplifyTask));
+    }
+    return tasks;
+  }
+
+  /** Get a single task by id. */
+  async getTask(listIdOrName, taskId) {
+    const listId = await this.resolveListId(listIdOrName);
+    const data = await this.graph("GET", `/me/todo/lists/${listId}/tasks/${taskId}`);
+    return simplifyTask(data);
+  }
+
+  // ---- Tasks: write -------------------------------------------------------
+
+  /** Create a task. `fields` is a map of todoTask property -> value (title required). */
+  async createTask(listIdOrName, fields) {
+    const listId = await this.resolveListId(listIdOrName);
+    if (!fields || !fields.title) throw new Error("A task `title` is required.");
+    const data = await this.graph("POST", `/me/todo/lists/${listId}/tasks`, { body: fields });
+    return simplifyTask(data);
+  }
+
+  /** Update a task (partial; only provided properties change). */
+  async updateTask(listIdOrName, taskId, fields) {
+    const listId = await this.resolveListId(listIdOrName);
+    const data = await this.graph("PATCH", `/me/todo/lists/${listId}/tasks/${taskId}`, {
+      body: fields,
+    });
+    return simplifyTask(data);
+  }
+
+  /** Mark a task completed (convenience over updateTask). */
+  async completeTask(listIdOrName, taskId) {
+    return this.updateTask(listIdOrName, taskId, { status: "completed" });
+  }
+
+  /** Delete a task by id. */
+  async deleteTask(listIdOrName, taskId) {
+    const listId = await this.resolveListId(listIdOrName);
+    await this.graph("DELETE", `/me/todo/lists/${listId}/tasks/${taskId}`);
+    return true;
+  }
+
+  // ---- Checklist items (subtasks) ----------------------------------------
+
+  async listChecklistItems(listIdOrName, taskId) {
+    const listId = await this.resolveListId(listIdOrName);
+    const data = await this.graph(
+      "GET",
+      `/me/todo/lists/${listId}/tasks/${taskId}/checklistItems`,
+    );
+    return data.value;
+  }
+
+  async createChecklistItem(listIdOrName, taskId, displayName) {
+    if (!displayName) throw new Error("displayName is required.");
+    const listId = await this.resolveListId(listIdOrName);
+    return this.graph("POST", `/me/todo/lists/${listId}/tasks/${taskId}/checklistItems`, {
+      body: { displayName },
+    });
+  }
+
+  /** Update a checklist item: rename and/or (un)check it. */
+  async updateChecklistItem(listIdOrName, taskId, itemId, { displayName, isChecked } = {}) {
+    const listId = await this.resolveListId(listIdOrName);
+    const body = {};
+    if (displayName !== undefined) body.displayName = displayName;
+    if (isChecked !== undefined) body.isChecked = isChecked;
+    return this.graph(
+      "PATCH",
+      `/me/todo/lists/${listId}/tasks/${taskId}/checklistItems/${itemId}`,
+      { body },
+    );
+  }
+
+  async deleteChecklistItem(listIdOrName, taskId, itemId) {
+    const listId = await this.resolveListId(listIdOrName);
+    await this.graph(
+      "DELETE",
+      `/me/todo/lists/${listId}/tasks/${taskId}/checklistItems/${itemId}`,
+    );
+    return true;
+  }
+
+  // ---- Convenience --------------------------------------------------------
+
+  /** Verify the cached login works. Returns the signed-in user + list count. */
+  async test() {
+    const me = await this.me();
+    const lists = await this.listTaskLists();
+    return {
+      ok: true,
+      signedInAs: me.userPrincipalName || me.mail || me.displayName,
+      displayName: me.displayName,
+      listCount: lists.length,
+      lists: lists.map((l) => l.displayName),
+    };
+  }
+}
+
+// ---- helpers --------------------------------------------------------------
+
+/** Flatten a todoTask into a compact, useful shape. */
+function simplifyTask(t) {
+  if (!t) return t;
+  return {
+    id: t.id,
+    title: t.title,
+    status: t.status,
+    importance: t.importance,
+    isReminderOn: t.isReminderOn,
+    dueDateTime: t.dueDateTime,
+    startDateTime: t.startDateTime,
+    reminderDateTime: t.reminderDateTime,
+    completedDateTime: t.completedDateTime,
+    categories: t.categories,
+    body: t.body?.content ? t.body : undefined,
+    recurrence: t.recurrence,
+    hasAttachments: t.hasAttachments,
+    checklistItems: t.checklistItems,
+    createdDateTime: t.createdDateTime,
+    lastModifiedDateTime: t.lastModifiedDateTime,
+  };
+}
+
+/** Best-effort decode of the id_token payload to record which account signed in. */
+function accountFromIdToken(idToken) {
+  if (!idToken || typeof idToken !== "string") return undefined;
+  const parts = idToken.split(".");
+  if (parts.length < 2) return undefined;
+  try {
+    const payload = JSON.parse(Buffer.from(parts[1], "base64url").toString("utf8"));
+    return {
+      username: payload.preferred_username || payload.upn || payload.email,
+      name: payload.name,
+      tid: payload.tid,
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Build a Graph dateTimeTimeZone object from a friendly date string.
+ * Accepts "2026-07-01", "2026-07-01T15:30", or a full ISO string. A bare date
+ * defaults to midnight. Returns { dateTime, timeZone }.
+ */
+export function toDateTimeTimeZone(input, timeZone = "UTC") {
+  if (!input) return undefined;
+  let dateTime = String(input).trim();
+  if (/^\d{4}-\d{2}-\d{2}$/.test(dateTime)) dateTime += "T00:00:00";
+  // Strip a trailing Z — Graph carries the zone in the timeZone field instead.
+  dateTime = dateTime.replace(/Z$/, "");
+  return { dateTime, timeZone };
+}
+
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+/** URL-safe base64 with no padding (for PKCE verifier/challenge/state). */
+function base64url(buf) {
+  return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+/**
+ * Start a loopback HTTP server that captures the OAuth redirect. Resolves with
+ * `{ server, port, waitForCode }`, where `waitForCode` is a promise for the
+ * authorization code (rejects on error param, state mismatch, or timeout).
+ */
+function startRedirectServer(expectedState, timeoutMs, listenPort = 0) {
+  return new Promise((resolveStart, rejectStart) => {
+    let settle;
+    const waitForCode = new Promise((resolve, reject) => {
+      settle = { resolve, reject };
+    });
+
+    const server = createServer((req, res) => {
+      const url = new URL(req.url, "http://localhost");
+      if (url.pathname === "/favicon.ico") {
+        res.writeHead(204).end();
+        return;
+      }
+      const error = url.searchParams.get("error");
+      const errorDesc = url.searchParams.get("error_description");
+      const code = url.searchParams.get("code");
+      const state = url.searchParams.get("state");
+
+      const reply = (title, msg) => {
+        res.writeHead(200, { "Content-Type": "text/html" });
+        res.end(
+          `<!doctype html><meta charset="utf-8"><title>${title}</title>` +
+            `<body style="font:16px system-ui;margin:3rem"><h2>${title}</h2><p>${msg}</p>` +
+            `<p>You can close this tab and return to the terminal.</p></body>`,
+        );
+      };
+
+      if (error) {
+        reply("Sign-in failed", escapeHtml(errorDesc || error));
+        settle.reject(
+          new GraphError(`Sign-in was blocked or cancelled: ${errorDesc || error}`, {
+            status: 400,
+            code: error,
+          }),
+        );
+      } else if (!code) {
+        reply("Waiting…", "No authorization code in the request.");
+      } else if (state !== expectedState) {
+        reply("Sign-in failed", "State mismatch — possible CSRF. Try again.");
+        settle.reject(new Error("OAuth state mismatch; aborting sign-in."));
+      } else {
+        reply("Signed in ✓", "Microsoft To Do is now connected.");
+        settle.resolve(code);
+      }
+    });
+
+    const timer = setTimeout(() => {
+      settle.reject(new Error("Timed out waiting for browser sign-in."));
+      server.close();
+    }, timeoutMs);
+    // Clear the timer when the code promise settles, without creating an
+    // unhandled-rejection branch (login() is the one that handles the rejection).
+    waitForCode.finally(() => clearTimeout(timer)).catch(() => {});
+
+    server.on("error", (e) => rejectStart(e));
+    server.listen(listenPort, "127.0.0.1", () => {
+      resolveStart({ server, port: server.address().port, waitForCode });
+    });
+  });
+}
+
+/** Best-effort open of a URL in the system browser (macOS / Windows / Linux). */
+function openBrowser(url) {
+  const cmd =
+    process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+  try {
+    const child = spawn(cmd, process.platform === "win32" ? ["", url] : [url], {
+      stdio: "ignore",
+      detached: true,
+      shell: process.platform === "win32",
+    });
+    child.on("error", () => {}); // ignore; the CLI also prints the URL as a fallback
+    child.unref();
+  } catch {
+    /* ignore — user can open the printed URL manually */
+  }
+}
+
+function escapeHtml(s) {
+  return String(s).replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c]);
+}
+
+export default MSTodoClient;
--- a/.claude/skills/ms-todo/scripts/todo.mjs
+++ b/.claude/skills/ms-todo/scripts/todo.mjs
@@ -0,0 +1,306 @@
+#!/usr/bin/env node
+// CLI wrapper around MSTodoClient. Prints JSON to stdout; errors to stderr with a
+// non-zero exit so callers can detect failure reliably.
+//
+// Auth is DELEGATED (auth-code + PKCE, browser) — Microsoft To Do has no app-only
+// access. Run `login` once; it opens your browser. The refresh token is then
+// cached and reused automatically thereafter.
+//
+// Config (env or a .env file in the CWD or this skill's directory):
+//   TODO_CLIENT_ID     (or AZURE_CLIENT_ID)   required — a PUBLIC client app id
+//   TODO_TENANT_ID     (or AZURE_TENANT_ID)   optional — default "common"
+//   TODO_TOKEN_CACHE   optional — path to the token cache (default: .token-cache.json here)
+//   TODO_REDIRECT_PORT optional — pin the loopback redirect port (default: OS-assigned)
+//   TODO_TIMEZONE      optional — IANA/Windows zone for --due/--start/--reminder (default UTC)
+//
+// Usage:
+//   node todo.mjs login                                   Sign in (opens browser), once
+//   node todo.mjs logout                                  Forget the cached sign-in
+//   node todo.mjs test                                    Verify auth; show signed-in user
+//   node todo.mjs lists                                   List task lists
+//   node todo.mjs list-create  --name "Groceries"
+//   node todo.mjs list-update  --list NAME_OR_ID --name "New name"
+//   node todo.mjs list-delete  --list NAME_OR_ID
+//   node todo.mjs tasks   --list NAME_OR_ID [--filter ODATA] [--select F1,F2] [--orderby "dueDateTime/dateTime asc"] [--top N] [--all]
+//   node todo.mjs get     --list NAME_OR_ID --id TASK_ID
+//   node todo.mjs create  --list NAME_OR_ID --title "..." [--due 2026-07-01] [--start ...] [--reminder ...] [--importance high] [--body "..."] [--fields JSON]
+//   node todo.mjs update  --list NAME_OR_ID --id TASK_ID [--title ...] [--status completed] [--due ...] [--importance ...] [--body ...] [--fields JSON]
+//   node todo.mjs done    --list NAME_OR_ID --id TASK_ID
+//   node todo.mjs delete  --list NAME_OR_ID --id TASK_ID
+//   node todo.mjs checklist        --list NAME_OR_ID --id TASK_ID                 List checklist (subtasks)
+//   node todo.mjs checklist-add    --list NAME_OR_ID --id TASK_ID --name "step"
+//   node todo.mjs checklist-check  --list NAME_OR_ID --id TASK_ID --item ITEM_ID [--uncheck]
+//   node todo.mjs checklist-delete --list NAME_OR_ID --id TASK_ID --item ITEM_ID
+//
+// --fields accepts inline JSON, @path/to/file.json, or "-" (stdin) and is merged
+// over the convenience flags, so you can express anything the Graph API supports.
+
+import { readFileSync, existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  MSTodoClient,
+  GraphError,
+  AuthRequiredError,
+  toDateTimeTimeZone,
+} from "./lib/graph.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+main().catch((err) => {
+  const payload = {
+    ok: false,
+    error: err.message,
+    ...(err instanceof GraphError
+      ? { status: err.status, code: err.code, requestId: err.requestId }
+      : {}),
+    ...(err instanceof AuthRequiredError ? { needsLogin: true } : {}),
+  };
+  process.stderr.write(JSON.stringify(payload, null, 2) + "\n");
+  process.exit(1);
+});
+
+async function main() {
+  loadDotEnv();
+  const [, , command, ...rest] = process.argv;
+  const flags = parseFlags(rest);
+
+  if (!command || command === "help" || flags.help) {
+    printHelp();
+    return;
+  }
+
+  const client = new MSTodoClient({
+    clientId: env("TODO_CLIENT_ID", "AZURE_CLIENT_ID"),
+    tenantId: env("TODO_TENANT_ID", "AZURE_TENANT_ID") || "common",
+    tokenCachePath: env("TODO_TOKEN_CACHE") || join(__dirname, ".token-cache.json"),
+    redirectPort: env("TODO_REDIRECT_PORT") ? Number(env("TODO_REDIRECT_PORT")) : 0,
+  });
+  const tz = env("TODO_TIMEZONE") || "UTC";
+
+  const needList = () => {
+    if (!flags.list) throw new Error("Missing --list NAME_OR_ID.");
+    return flags.list;
+  };
+  const needId = () => {
+    if (!flags.id) throw new Error("Missing --id TASK_ID.");
+    return flags.id;
+  };
+  const needItem = () => {
+    if (!flags.item) throw new Error("Missing --item ITEM_ID.");
+    return flags.item;
+  };
+
+  let result;
+  switch (command) {
+    case "login":
+      result = await client.login((p) => {
+        process.stderr.write(
+          `\nOpening your browser to sign in…\nIf it didn't open, paste this URL:\n${p.authorizeUrl}\n\n` +
+            `Waiting for you to finish signing in (redirect to ${p.redirectUri})…\n\n`,
+        );
+      });
+      result = { ok: true, signedIn: result };
+      break;
+    case "logout":
+      result = { ok: true, loggedOut: client.logout() };
+      break;
+    case "test":
+      result = await client.test();
+      break;
+    case "lists":
+      result = await client.listTaskLists();
+      break;
+    case "list-create":
+      result = await client.createTaskList(needName());
+      break;
+    case "list-update":
+      result = await client.updateTaskList(needList(), needName());
+      break;
+    case "list-delete":
+      await client.deleteTaskList(needList());
+      result = { ok: true, deletedList: needList() };
+      break;
+    case "tasks":
+      result = await client.listTasks(needList(), {
+        filter: flags.filter,
+        select: flags.select,
+        orderby: flags.orderby,
+        top: flags.top ? Number(flags.top) : undefined,
+        all: Boolean(flags.all),
+      });
+      break;
+    case "get":
+      result = await client.getTask(needList(), needId());
+      break;
+    case "create":
+      result = await client.createTask(needList(), buildTaskFields(flags, tz, true));
+      break;
+    case "update":
+      result = await client.updateTask(needList(), needId(), buildTaskFields(flags, tz, false));
+      break;
+    case "done":
+      result = await client.completeTask(needList(), needId());
+      break;
+    case "delete":
+      await client.deleteTask(needList(), needId());
+      result = { ok: true, deleted: needId() };
+      break;
+    case "checklist":
+      result = await client.listChecklistItems(needList(), needId());
+      break;
+    case "checklist-add":
+      result = await client.createChecklistItem(needList(), needId(), needName());
+      break;
+    case "checklist-check":
+      result = await client.updateChecklistItem(needList(), needId(), needItem(), {
+        isChecked: !flags.uncheck,
+        displayName: flags.name,
+      });
+      break;
+    case "checklist-delete":
+      await client.deleteChecklistItem(needList(), needId(), needItem());
+      result = { ok: true, deletedItem: needItem() };
+      break;
+    default:
+      throw new Error(`Unknown command "${command}". Run "node todo.mjs help".`);
+  }
+
+  process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+
+  function needName() {
+    if (!flags.name) throw new Error("Missing --name VALUE.");
+    return flags.name;
+  }
+}
+
+// ---- helpers --------------------------------------------------------------
+
+function env(...names) {
+  for (const n of names) if (process.env[n]) return process.env[n];
+  return undefined;
+}
+
+function parseFlags(args) {
+  const flags = {};
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (!a.startsWith("--")) continue;
+    const key = a.slice(2);
+    const next = args[i + 1];
+    if (next === undefined || next.startsWith("--")) {
+      flags[key] = true; // boolean flag (e.g. --all, --uncheck)
+    } else {
+      flags[key] = next;
+      i++;
+    }
+  }
+  return flags;
+}
+
+/**
+ * Build a todoTask body from convenience flags, then merge raw --fields JSON on
+ * top so power users can override anything. On create, title is required.
+ */
+function buildTaskFields(flags, tz, requireTitle) {
+  const fields = {};
+  if (flags.title) fields.title = flags.title;
+  if (flags.importance) fields.importance = flags.importance; // low|normal|high
+  if (flags.status) fields.status = flags.status; // notStarted|inProgress|completed|waitingOnOthers|deferred
+  if (flags.body) fields.body = { content: flags.body, contentType: "text" };
+  if (flags.due) fields.dueDateTime = toDateTimeTimeZone(flags.due, tz);
+  if (flags.start) fields.startDateTime = toDateTimeTimeZone(flags.start, tz);
+  if (flags.reminder) {
+    fields.reminderDateTime = toDateTimeTimeZone(flags.reminder, tz);
+    fields.isReminderOn = true;
+  }
+  if (flags.categories) {
+    fields.categories = String(flags.categories)
+      .split(",")
+      .map((s) => s.trim())
+      .filter(Boolean);
+  }
+
+  const raw = readFieldsFlag(flags);
+  Object.assign(fields, raw);
+
+  if (requireTitle && !fields.title) {
+    throw new Error("Missing --title (or a title in --fields) for create.");
+  }
+  return fields;
+}
+
+function readFieldsFlag(flags) {
+  const raw = flags.fields;
+  if (raw === undefined || raw === true) return {};
+  let text = raw;
+  if (raw === "-") text = readFileSync(0, "utf8");
+  else if (raw.startsWith("@")) text = readFileSync(raw.slice(1), "utf8");
+  try {
+    return JSON.parse(text);
+  } catch (e) {
+    throw new Error(`--fields is not valid JSON: ${e.message}`);
+  }
+}
+
+// Minimal .env loader (no dependency). Looks in CWD then this skill's dir.
+function loadDotEnv() {
+  for (const dir of [process.cwd(), __dirname, join(__dirname, "..")]) {
+    const file = join(dir, ".env");
+    if (!existsSync(file)) continue;
+    for (const line of readFileSync(file, "utf8").split("\n")) {
+      const m = line.match(/^\s*([A-Z0-9_]+)\s*=\s*(.*)\s*$/i);
+      if (!m) continue;
+      const key = m[1];
+      let val = m[2].trim();
+      if (
+        (val.startsWith('"') && val.endsWith('"')) ||
+        (val.startsWith("'") && val.endsWith("'"))
+      ) {
+        val = val.slice(1, -1);
+      }
+      if (process.env[key] === undefined) process.env[key] = val;
+    }
+  }
+}
+
+function printHelp() {
+  process.stdout.write(
+    `ms-todo CLI — Microsoft To Do via Microsoft Graph (delegated / browser auth-code+PKCE)
+
+Auth (one-time):
+  login                                          Sign in (opens your browser)
+  logout                                         Forget the cached sign-in
+  test                                           Verify auth; show signed-in user
+
+Task lists:
+  lists                                          List all task lists
+  list-create  --name "Groceries"
+  list-update  --list NAME_OR_ID --name "New name"
+  list-delete  --list NAME_OR_ID
+
+Tasks:
+  tasks   --list NAME_OR_ID [filters]            Query tasks
+  get     --list NAME_OR_ID --id TASK_ID         Get one task
+  create  --list NAME_OR_ID --title "..." [opts] Create a task
+  update  --list NAME_OR_ID --id TASK_ID [opts]  Update a task
+  done    --list NAME_OR_ID --id TASK_ID         Mark a task completed
+  delete  --list NAME_OR_ID --id TASK_ID         Delete a task
+
+  task opts: --title --body --importance low|normal|high --status notStarted|inProgress|completed
+             --due 2026-07-01 --start ... --reminder ... --categories "a,b"
+  tasks filters: --filter "status ne 'completed'"  --select title,status,dueDateTime
+                 --orderby "dueDateTime/dateTime asc"  --top 50  --all
+
+Checklist items (subtasks):
+  checklist        --list NAME_OR_ID --id TASK_ID
+  checklist-add    --list NAME_OR_ID --id TASK_ID --name "step"
+  checklist-check  --list NAME_OR_ID --id TASK_ID --item ITEM_ID [--uncheck]
+  checklist-delete --list NAME_OR_ID --id TASK_ID --item ITEM_ID
+
+--fields accepts inline JSON, @file.json, or - (stdin); it merges over the flags.
+Config (env / .env): TODO_CLIENT_ID (required), TODO_TENANT_ID (default "common"),
+TODO_TOKEN_CACHE, TODO_TIMEZONE (default UTC).
+`,
+  );
+}