onenote-cli 0.1.0

package/.env.example

@@ -0,0 +1,10 @@
+# Azure AD App Registration
+# Register at: https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps
+# 1. New registration -> Name: onenote-cli
+# 2. Supported account types: Personal Microsoft accounts + Organizational
+# 3. Platform: Mobile and desktop applications
+# 4. Copy Application (client) ID here:
+ONENOTE_CLIENT_ID=YOUR_CLIENT_ID
+
+# Authority URL (default: common for multi-tenant + personal accounts)
+ONENOTE_AUTHORITY=https://login.microsoftonline.com/common

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sno
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,142 @@
+# onenote-cli
+
+**Make your OneNote notebooks survive in the age of AI.**
+
+A CLI that lets AI agents (and humans) search, read, and operate your OneNote — with full-text page-level search and deep links that open directly to the matching page.
+
+## Features
+
+- **Page-level search** — search inside all your OneNote pages, get results with URLs that open directly to the matching page in OneNote Online
+- **Notebooks / Sections / Pages** — list, get, create, delete via Graph API
+- **5,000-item workaround** — when Graph OneNote API is blocked by the SharePoint document library limit, automatically falls back to OneDrive file API + local binary parsing
+- **Local cache** — downloads `.one` files, extracts text (UTF-8 + UTF-16LE), builds a searchable index
+- **Official OneNote URLs** — resolves page GUIDs via `GET /me/onenote/sections/0-{guid}/pages` to get URLs that bypass OneNote Online's session caching
+- **Device code flow auth** — works in SSH / headless / terminal environments
+- **Cross-directory** — `.env.local` and cache are loaded from the package directory, so `onenote` works from any working directory
+
+## Install
+
+### As an AI Agent Skill
+
+```bash
+# Claude Code / OpenClaw / Codex / Cursor / any SKILL.md-compatible agent
+npx skills add snomiao/onenote-cli
+```
+
+### Manual
+
+```bash
+git clone https://github.com/snomiao/onenote-cli.git
+cd onenote-cli
+bun install
+```
+
+## Setup
+
+1. Register an Azure AD app at [entra.microsoft.com](https://entra.microsoft.com) (see [docs/setup.md](docs/setup.md) for full walkthrough)
+2. Copy `.env.example` to `.env.local` and set your Client ID:
+   ```bash
+   cp .env.example .env.local
+   # Edit .env.local with your Application (client) ID
+   ```
+3. Login:
+   ```bash
+   bun run src/index.ts auth login
+   ```
+
+## Usage
+
+```bash
+# Auth
+onenote auth login          # Login via device code flow
+onenote auth whoami         # Show current user
+onenote auth setup          # Print setup instructions
+onenote auth logout         # Clear tokens
+
+# Notebooks
+onenote notebooks list
+onenote notebooks get <id>
+onenote notebooks create <name>
+
+# Sections (falls back to OneDrive if Graph API is blocked)
+onenote sections list -n <notebook-id>
+onenote sections create -n <notebook-id> --name <name>
+
+# Pages
+onenote pages list -s <section-id>
+onenote pages get <id>
+onenote pages content <id>
+onenote pages create -s <section-id> -t <title> -b "<html>"
+onenote pages delete <id>
+
+# Search
+onenote sync                # Download and cache all sections
+onenote search <query>      # Full-text page-level search (local)
+onenote search <query> -o   # Online section-level search (Graph API)
+```
+
+### Search Example
+
+```
+$ onenote search 年金番号
+
+# (20250303) nenkin bangou screenshot @mynaportal
+  Section: MyNumberCard-マイナンバカード | Notebook: sno@ja
+  基础**年金番号** ...
+  https://snomiao-my.sharepoint.com/.../Notebooks/sno@ja?wd=target(...)
+
+2 page-level results found.
+```
+
+Clicking the URL opens OneNote Online directly on the matching page.
+
+## How Search Works
+
+1. `onenote sync` downloads all `.one` section files from OneDrive
+2. Extracts page GUIDs from the MS-ONESTORE binary format
+3. Fetches official page URLs via OneNote Graph API (`/me/onenote/sections/0-{guid}/pages`)
+4. On search, scans the binary for matches (UTF-8 and UTF-16LE), attributes each match to the correct page via context-based anchor lookup
+5. Returns results with official OneNote URLs that navigate directly to the page
+
+See [docs/local-search-architecture.md](docs/local-search-architecture.md) for the full technical design.
+
+## API Permissions Required
+
+| Permission | Type | Purpose |
+|---|---|---|
+| `Notes.Read` | Delegated | Read notebooks |
+| `Notes.ReadWrite` | Delegated | Create/modify pages |
+| `Notes.ReadWrite.All` | Delegated | Access all notebooks |
+| `Files.Read` | Delegated | Download .one files from OneDrive |
+| `Files.Read.All` | Delegated | Access all accessible files |
+| `Sites.Read.All` | Delegated | Search via SharePoint listItem API |
+
+## File Structure
+
+```
+src/
+  index.ts      CLI entry point (yargs)
+  auth.ts       MSAL device code flow + .env.local auto-loader
+  graph.ts      Microsoft Graph API client (OneNote + OneDrive)
+  cache.ts      Local cache, .one binary parser, page GUID extraction
+docs/
+  setup.md                     Azure AD registration walkthrough
+  local-search-architecture.md Technical design of local search
+  graph-api-endpoints.md       OneNote Graph API reference
+  development-notes.md         Lessons learned
+  onen0te-cli-analysis.md      Competitor UX analysis
+```
+
+## Configuration
+
+| Source | Location | Priority |
+|---|---|---|
+| `.env.local` | Package root (auto-loaded) | Highest |
+| `~/.onenote-cli/config.json` | Home directory | Fallback |
+| `ONENOTE_CLIENT_ID` env var | Shell environment | Overrides all |
+
+Cache location: `<package>/.onenote/cache/` (override with `ONENOTE_CACHE_DIR`)
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: onenote-cli
+description: Make your OneNote notebooks survive in the age of AI. Search and operate OneNote from CLI via Microsoft Graph API. Use when the user wants to search OneNote notes, list notebooks, read pages, or manage OneNote content.
+---
+
+# onenote-cli
+
+CLI for Microsoft OneNote via Microsoft Graph. Built with Bun + yargs + MSAL.
+
+## Quick Reference
+
+```bash
+onenote auth login                    # Device code flow login
+onenote auth logout                   # Clear cached tokens
+onenote auth whoami                   # Show current user
+onenote auth setup                    # Show OAuth setup instructions
+
+onenote notebooks list                # List notebooks
+onenote notebooks get <id>            # Get notebook by ID
+onenote notebooks create <name>       # Create notebook
+
+onenote sections list -n <nb-id>      # List sections in a notebook
+onenote sections create -n <nb> --name <name>
+
+onenote pages list -s <sec-id>        # List pages in a section
+onenote pages content <id>            # Get page HTML content
+onenote pages create -s <sec> -t <title> -b <html>
+onenote pages delete <id>
+
+onenote sync                          # Build local cache (.one binary + page index)
+onenote search <query>                # Full-text search across cached pages
+onenote search <query> --online       # Online section-level search via Graph
+```
+
+## Setup
+
+See [docs/setup.md](docs/setup.md) for full Azure AD app registration walkthrough.
+
+Quick setup:
+1. Register app at https://entra.microsoft.com → App registrations → New
+2. Supported account types: "Accounts in any organizational directory and personal Microsoft accounts"
+3. Add platform: Mobile and desktop applications, redirect URI `https://login.microsoftonline.com/common/oauth2/nativeclient`
+4. Settings → Allow public client flows: **Yes**
+5. API permissions → Microsoft Graph → Delegated: `Notes.Read`, `Notes.ReadWrite`, `Notes.ReadWrite.All`, `Files.Read`, `Files.Read.All`, `Sites.Read.All`
+6. Copy Application (client) ID into `.env.local`:
+   ```env
+   ONENOTE_CLIENT_ID=your-client-id-here
+   ONENOTE_AUTHORITY=https://login.microsoftonline.com/common
+   ```
+
+## How Search Works
+
+`onenote search <query>` returns page-level results with **official OneNote URLs** that navigate directly to the matching page (bypassing OneNote Online's session caching).
+
+The search:
+1. Downloads `.one` files via OneDrive (cached locally in `<package>/.onenote/cache/`)
+2. Extracts page GUIDs from the binary
+3. Resolves official `oneNoteWebUrl` via `/me/onenote/sections/0-{guid}/pages` (works around the 5,000-item document library limit)
+4. Searches the binary for the query (UTF-8 + UTF-16LE) and attributes matches to the correct page using context-based lookup
+
+See [docs/local-search-architecture.md](docs/local-search-architecture.md) for details.
+
+## File Locations
+
+- `.env.local` — at the package root (auto-loaded via `import.meta.dir`)
+- Token cache — `~/.onenote-cli/msal-cache.json`
+- Config fallback — `~/.onenote-cli/config.json`
+- Page cache — `<package>/.onenote/cache/` (override with `ONENOTE_CACHE_DIR`)
+
+## Common Issues
+
+| Error | Fix |
+|---|---|
+| `AADSTS7000218` | Enable "Allow public client flows" in app Authentication settings |
+| `AADSTS65001` | Admin consent required for API permissions, or accept consent during login |
+| `Graph API 403: error 10008` | Document library has > 5,000 OneNote items; use `onenote sync` and local search instead |
+| Cache empty | Run `onenote sync` (auto-runs on first search) |

package/bun.lock

@@ -0,0 +1,92 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "onenote-cli",
+      "dependencies": {
+        "@azure/msal-node": "^2.16.0",
+        "yargs": "^17.7.2",
+      },
+      "devDependencies": {
+        "@types/yargs": "^17.0.33",
+        "typescript": "^5.7.0",
+      },
+    },
+  },
+  "packages": {
+    "@azure/msal-common": ["@azure/msal-common@14.16.1", "", {}, "sha512-nyxsA6NA4SVKh5YyRpbSXiMr7oQbwark7JU9LMeg6tJYTSPyAGkdx61wPT4gyxZfxlSxMMEyAsWaubBlNyIa1w=="],
+
+    "@azure/msal-node": ["@azure/msal-node@2.16.3", "", { "dependencies": { "@azure/msal-common": "14.16.1", "jsonwebtoken": "^9.0.0", "uuid": "^8.3.0" } }, "sha512-CO+SE4weOsfJf+C5LM8argzvotrXw252/ZU6SM2Tz63fEblhH1uuVaaO4ISYFuN4Q6BhTo7I3qIdi8ydUQCqhw=="],
+
+    "@types/yargs": ["@types/yargs@17.0.35", "", { "dependencies": { "@types/yargs-parser": "*" } }, "sha512-qUHkeCyQFxMXg79wQfTtfndEC+N9ZZg76HJftDJp+qH2tV7Gj4OJi7l+PiWwJ+pWtW8GwSmqsDj/oymhrTWXjg=="],
+
+    "@types/yargs-parser": ["@types/yargs-parser@21.0.3", "", {}, "sha512-I4q9QU9MQv4oEOz4tAHJtNz1cwuLxn2F3xcc2iV5WdqLPpUnj30aUuxt1mAxYTG+oe8CZMV/+6rU4S4gRDzqtQ=="],
+
+    "ansi-regex": ["ansi-regex@5.0.1", "", {}, "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ=="],
+
+    "ansi-styles": ["ansi-styles@4.3.0", "", { "dependencies": { "color-convert": "^2.0.1" } }, "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg=="],
+
+    "buffer-equal-constant-time": ["buffer-equal-constant-time@1.0.1", "", {}, "sha512-zRpUiDwd/xk6ADqPMATG8vc9VPrkck7T07OIx0gnjmJAnHnTVXNQG3vfvWNuiZIkwu9KrKdA1iJKfsfTVxE6NA=="],
+
+    "cliui": ["cliui@8.0.1", "", { "dependencies": { "string-width": "^4.2.0", "strip-ansi": "^6.0.1", "wrap-ansi": "^7.0.0" } }, "sha512-BSeNnyus75C4//NQ9gQt1/csTXyo/8Sb+afLAkzAptFuMsod9HFokGNudZpi/oQV73hnVK+sR+5PVRMd+Dr7YQ=="],
+
+    "color-convert": ["color-convert@2.0.1", "", { "dependencies": { "color-name": "~1.1.4" } }, "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ=="],
+
+    "color-name": ["color-name@1.1.4", "", {}, "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA=="],
+
+    "ecdsa-sig-formatter": ["ecdsa-sig-formatter@1.0.11", "", { "dependencies": { "safe-buffer": "^5.0.1" } }, "sha512-nagl3RYrbNv6kQkeJIpt6NJZy8twLB/2vtz6yN9Z4vRKHN4/QZJIEbqohALSgwKdnksuY3k5Addp5lg8sVoVcQ=="],
+
+    "emoji-regex": ["emoji-regex@8.0.0", "", {}, "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A=="],
+
+    "escalade": ["escalade@3.2.0", "", {}, "sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA=="],
+
+    "get-caller-file": ["get-caller-file@2.0.5", "", {}, "sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg=="],
+
+    "is-fullwidth-code-point": ["is-fullwidth-code-point@3.0.0", "", {}, "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg=="],
+
+    "jsonwebtoken": ["jsonwebtoken@9.0.3", "", { "dependencies": { "jws": "^4.0.1", "lodash.includes": "^4.3.0", "lodash.isboolean": "^3.0.3", "lodash.isinteger": "^4.0.4", "lodash.isnumber": "^3.0.3", "lodash.isplainobject": "^4.0.6", "lodash.isstring": "^4.0.1", "lodash.once": "^4.0.0", "ms": "^2.1.1", "semver": "^7.5.4" } }, "sha512-MT/xP0CrubFRNLNKvxJ2BYfy53Zkm++5bX9dtuPbqAeQpTVe0MQTFhao8+Cp//EmJp244xt6Drw/GVEGCUj40g=="],
+
+    "jwa": ["jwa@2.0.1", "", { "dependencies": { "buffer-equal-constant-time": "^1.0.1", "ecdsa-sig-formatter": "1.0.11", "safe-buffer": "^5.0.1" } }, "sha512-hRF04fqJIP8Abbkq5NKGN0Bbr3JxlQ+qhZufXVr0DvujKy93ZCbXZMHDL4EOtodSbCWxOqR8MS1tXA5hwqCXDg=="],
+
+    "jws": ["jws@4.0.1", "", { "dependencies": { "jwa": "^2.0.1", "safe-buffer": "^5.0.1" } }, "sha512-EKI/M/yqPncGUUh44xz0PxSidXFr/+r0pA70+gIYhjv+et7yxM+s29Y+VGDkovRofQem0fs7Uvf4+YmAdyRduA=="],
+
+    "lodash.includes": ["lodash.includes@4.3.0", "", {}, "sha512-W3Bx6mdkRTGtlJISOvVD/lbqjTlPPUDTMnlXZFnVwi9NKJ6tiAk6LVdlhZMm17VZisqhKcgzpO5Wz91PCt5b0w=="],
+
+    "lodash.isboolean": ["lodash.isboolean@3.0.3", "", {}, "sha512-Bz5mupy2SVbPHURB98VAcw+aHh4vRV5IPNhILUCsOzRmsTmSQ17jIuqopAentWoehktxGd9e/hbIXq980/1QJg=="],
+
+    "lodash.isinteger": ["lodash.isinteger@4.0.4", "", {}, "sha512-DBwtEWN2caHQ9/imiNeEA5ys1JoRtRfY3d7V9wkqtbycnAmTvRRmbHKDV4a0EYc678/dia0jrte4tjYwVBaZUA=="],
+
+    "lodash.isnumber": ["lodash.isnumber@3.0.3", "", {}, "sha512-QYqzpfwO3/CWf3XP+Z+tkQsfaLL/EnUlXWVkIk5FUPc4sBdTehEqZONuyRt2P67PXAk+NXmTBcc97zw9t1FQrw=="],
+
+    "lodash.isplainobject": ["lodash.isplainobject@4.0.6", "", {}, "sha512-oSXzaWypCMHkPC3NvBEaPHf0KsA5mvPrOPgQWDsbg8n7orZ290M0BmC/jgRZ4vcJ6DTAhjrsSYgdsW/F+MFOBA=="],
+
+    "lodash.isstring": ["lodash.isstring@4.0.1", "", {}, "sha512-0wJxfxH1wgO3GrbuP+dTTk7op+6L41QCXbGINEmD+ny/G/eCqGzxyCsh7159S+mgDDcoarnBw6PC1PS5+wUGgw=="],
+
+    "lodash.once": ["lodash.once@4.1.1", "", {}, "sha512-Sb487aTOCr9drQVL8pIxOzVhafOjZN9UU54hiN8PU3uAiSV7lx1yYNpbNmex2PK6dSJoNTSJUUswT651yww3Mg=="],
+
+    "ms": ["ms@2.1.3", "", {}, "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA=="],
+
+    "require-directory": ["require-directory@2.1.1", "", {}, "sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q=="],
+
+    "safe-buffer": ["safe-buffer@5.2.1", "", {}, "sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ=="],
+
+    "semver": ["semver@7.7.4", "", { "bin": { "semver": "bin/semver.js" } }, "sha512-vFKC2IEtQnVhpT78h1Yp8wzwrf8CM+MzKMHGJZfBtzhZNycRFnXsHk6E5TxIkkMsgNS7mdX3AGB7x2QM2di4lA=="],
+
+    "string-width": ["string-width@4.2.3", "", { "dependencies": { "emoji-regex": "^8.0.0", "is-fullwidth-code-point": "^3.0.0", "strip-ansi": "^6.0.1" } }, "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g=="],
+
+    "strip-ansi": ["strip-ansi@6.0.1", "", { "dependencies": { "ansi-regex": "^5.0.1" } }, "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "uuid": ["uuid@8.3.2", "", { "bin": { "uuid": "dist/bin/uuid" } }, "sha512-+NYs2QeMWy+GWFOEm9xnn6HCDp0l7QBD7ml8zLUmJ+93Q5NF0NocErnwkTkXVFNiX3/fpC6afS8Dhb/gz7R7eg=="],
+
+    "wrap-ansi": ["wrap-ansi@7.0.0", "", { "dependencies": { "ansi-styles": "^4.0.0", "string-width": "^4.1.0", "strip-ansi": "^6.0.0" } }, "sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q=="],
+
+    "y18n": ["y18n@5.0.8", "", {}, "sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA=="],
+
+    "yargs": ["yargs@17.7.2", "", { "dependencies": { "cliui": "^8.0.1", "escalade": "^3.1.1", "get-caller-file": "^2.0.5", "require-directory": "^2.1.1", "string-width": "^4.2.3", "y18n": "^5.0.5", "yargs-parser": "^21.1.1" } }, "sha512-7dSzzRQ++CKnNI/krKnYRV7JKKPUXMEh61soaHKg9mrWEhzFWhFnxPxGl+69cD1Ou63C13NUPCnmIcrvqCuM6w=="],
+
+    "yargs-parser": ["yargs-parser@21.1.1", "", {}, "sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw=="],
+  }
+}

package/docs/azure-app-registration.md

@@ -0,0 +1,80 @@
+# Azure AD App Registration for OneNote CLI
+
+This document describes how to register an Azure AD application for use with `onenote-cli`, which uses the Microsoft Graph OneNote API with delegated (device code flow) authentication.
+
+## Prerequisites
+
+- A Microsoft account (personal or organizational)
+- Access to [Microsoft Entra admin center](https://entra.microsoft.com)
+
+## Step 1: Create the App Registration
+
+1. Go to [Microsoft Entra admin center](https://entra.microsoft.com)
+2. Navigate to **Entra ID** > **App registrations** > **New registration**
+3. Fill in:
+   - **Name**: `onenote-cli`
+   - **Supported account types**: "Accounts in any organizational directory and personal Microsoft accounts"
+   - **Redirect URI**: Leave blank (configured in the next step)
+4. Click **Register**
+5. Copy the **Application (client) ID** from the Overview page
+
+## Step 2: Configure Authentication Platform
+
+1. Go to **Authentication** tab in your app registration
+2. Click **Add a platform** > **Mobile and desktop applications**
+3. Check these redirect URIs:
+   - `https://login.microsoftonline.com/common/oauth2/nativeclient`
+   - `msal{client-id}://auth` (MSAL-specific URI)
+4. Click **Configure**
+
+## Step 3: Enable Public Client Flows
+
+1. In the **Authentication** tab, go to the **Settings** sub-tab
+2. Find **Allow public client flows** and set it to **Enabled**
+3. Click **Save**
+
+This is required for device code flow authentication. Without it, you will get error `AADSTS7000218`.
+
+## Step 4: Add API Permissions
+
+1. Go to **API permissions** > **Add a permission**
+2. Select **Microsoft Graph** > **Delegated permissions**
+3. Search for "Notes" and expand the **Notes** group
+4. Select:
+   - `Notes.Read` — Read user OneNote notebooks
+   - `Notes.ReadWrite` — Read and write user OneNote notebooks
+   - `Notes.ReadWrite.All` — Read and write all notebooks the user can access
+5. Click **Add permissions**
+
+The default `User.Read` permission is already included.
+
+## Step 5: Configure the CLI
+
+Set the client ID via environment variable or config file:
+
+```bash
+# Option A: .env.local
+ONENOTE_CLIENT_ID=your-client-id-here
+ONENOTE_AUTHORITY=https://login.microsoftonline.com/common
+
+# Option B: ~/.onenote-cli/config.json
+{
+  "clientId": "your-client-id-here",
+  "authority": "https://login.microsoftonline.com/common"
+}
+```
+
+Environment variables take priority over the config file.
+
+## Step 6: Login and Verify
+
+```bash
+bun run src/index.ts login
+bun run src/index.ts notebooks list
+```
+
+## Notes
+
+- The Microsoft Graph OneNote API **does not support app-only authentication** as of March 2025. Only delegated (user) authentication is supported.
+- The authority URL `https://login.microsoftonline.com/common` supports both organizational and personal Microsoft accounts.
+- Tokens are cached at `~/.onenote-cli/msal-cache.json` and automatically refreshed.

package/docs/development-notes.md

@@ -0,0 +1,84 @@
+# Development Notes
+
+Lessons learned and implementation notes from building `onenote-cli`.
+
+## Architecture Decisions
+
+### Bun + Yargs
+
+- Bun is used as the runtime, allowing direct execution of TypeScript without a build step
+- Yargs provides a natural command/subcommand CLI structure
+- The `bin` field in package.json points directly to `src/index.ts` — no compilation needed
+
+### MSAL Node for Authentication
+
+- `@azure/msal-node` provides the `PublicClientApplication` class for device code flow
+- Token caching is implemented via MSAL's `cachePlugin` interface, persisting to `~/.onenote-cli/msal-cache.json`
+- Silent token acquisition is attempted first (using cached refresh tokens), falling back to device code flow
+
+### Configuration Priority
+
+Configuration is resolved in this order:
+1. Environment variables (`ONENOTE_CLIENT_ID`, `ONENOTE_AUTHORITY`)
+2. Config file (`~/.onenote-cli/config.json`)
+3. Default values (which prompt the user to configure)
+
+This allows both `.env.local` for development and the config file for installed usage.
+
+## Implementation Details
+
+### Device Code Flow
+
+The device code flow is ideal for CLI applications because:
+- No web server or redirect handler is needed
+- Works in headless/SSH environments
+- User authenticates in any browser, even on a different device
+
+Flow:
+1. CLI requests a device code from Azure AD
+2. Azure AD returns a code and a URL
+3. User opens the URL in a browser and enters the code
+4. User authenticates and consents to permissions
+5. CLI polls Azure AD and receives tokens once authentication completes
+
+### Page Creation
+
+OneNote pages are created by POSTing raw HTML (Content-Type: `text/html`), not JSON. The HTML must include a `<title>` in the `<head>` and content in the `<body>`. This is different from most Graph API endpoints which use JSON.
+
+### App-Only Auth Not Supported
+
+As of March 2025, Microsoft Graph OneNote API no longer supports app-only (client credentials) authentication. All access must use delegated permissions with a signed-in user. This means the CLI must always go through the device code flow for initial authentication.
+
+## Azure Portal Navigation Tips
+
+### Entra Admin Center vs Azure Portal
+
+- App registrations are managed in the [Microsoft Entra admin center](https://entra.microsoft.com), not the classic Azure portal
+- The path is: **Entra ID** > **App registrations**
+- Direct URL: `https://entra.microsoft.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade`
+
+### Common Setup Mistakes
+
+1. **Forgetting to enable public client flows** — Device code flow requires "Allow public client flows" to be set to Yes in Authentication > Settings. Without this, authentication fails with `AADSTS7000218`.
+
+2. **Wrong account type selection** — For a CLI that should work with both personal and work accounts, select "Accounts in any organizational directory and personal Microsoft accounts".
+
+3. **Missing redirect URI** — While device code flow doesn't strictly require a redirect URI, adding `https://login.microsoftonline.com/common/oauth2/nativeclient` ensures compatibility with the MSAL library.
+
+4. **Not adding API permissions** — The default `User.Read` permission is not enough. You must explicitly add `Notes.Read` / `Notes.ReadWrite` delegated permissions under Microsoft Graph.
+
+## Troubleshooting
+
+### Token Refresh Failures
+
+If silent token acquisition fails after a long period, the refresh token may have expired. Run `onenote login` again to re-authenticate.
+
+### Graph API 403 Errors
+
+Usually means the required permission was not consented. Check that:
+- The permission is added in the app registration
+- The user consented during login (or admin consent was granted)
+
+### Graph API 404 Errors
+
+OneNote resources use opaque IDs. If a notebook/section/page was deleted or moved, its ID becomes invalid.

package/docs/graph-api-endpoints.md

@@ -0,0 +1,95 @@
+# Microsoft Graph OneNote API Endpoints
+
+Reference for the OneNote REST API endpoints used by `onenote-cli`.
+
+## Base URL
+
+```
+https://graph.microsoft.com/v1.0/me/onenote/
+```
+
+## Notebooks
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/me/onenote/notebooks` | List all notebooks |
+| GET | `/me/onenote/notebooks/{id}` | Get a notebook by ID |
+| POST | `/me/onenote/notebooks` | Create a notebook (`{ "displayName": "..." }`) |
+
+## Sections
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/me/onenote/sections` | List all sections |
+| GET | `/me/onenote/notebooks/{id}/sections` | List sections in a notebook |
+| GET | `/me/onenote/sections/{id}` | Get a section by ID |
+| POST | `/me/onenote/notebooks/{id}/sections` | Create a section (`{ "displayName": "..." }`) |
+
+## Section Groups
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/me/onenote/sectionGroups` | List all section groups |
+| GET | `/me/onenote/notebooks/{id}/sectionGroups` | List section groups in a notebook |
+
+## Pages
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/me/onenote/pages` | List all pages |
+| GET | `/me/onenote/sections/{id}/pages` | List pages in a section |
+| GET | `/me/onenote/pages/{id}` | Get page metadata |
+| GET | `/me/onenote/pages/{id}/content` | Get page HTML content |
+| POST | `/me/onenote/sections/{id}/pages` | Create a page (Content-Type: text/html) |
+| DELETE | `/me/onenote/pages/{id}` | Delete a page |
+
+## Search
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/me/onenote/pages?$search={query}` | Search pages by content |
+
+## Creating Pages
+
+Pages are created by POSTing HTML to a section:
+
+```http
+POST /me/onenote/sections/{section-id}/pages
+Content-Type: text/html
+
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Page Title</title>
+  </head>
+  <body>
+    <p>Page content here</p>
+  </body>
+</html>
+```
+
+## Required Permissions (Delegated)
+
+| Permission | Description |
+|------------|-------------|
+| `Notes.Read` | Read notebooks |
+| `Notes.ReadWrite` | Read and write notebooks |
+| `Notes.Read.All` | Read all accessible notebooks |
+| `Notes.ReadWrite.All` | Read and write all accessible notebooks |
+
+## Additional Scopes
+
+Notebooks can also be accessed via group or SharePoint site contexts:
+
+```
+/groups/{id}/onenote/{notebooks|sections|pages}
+/sites/{id}/onenote/{notebooks|sections|pages}
+```
+
+These require corresponding group/site read permissions.
+
+## References
+
+- [OneNote API overview](https://learn.microsoft.com/en-us/graph/integrate-with-onenote)
+- [OneNote REST API reference](https://learn.microsoft.com/en-us/graph/api/resources/onenote-api-overview)
+- [Graph Explorer](https://developer.microsoft.com/graph/graph-explorer)