Merge pull request #5 from neilgfoster/003-categorise-and-search-folders

feat: category-assigning rules + category & search-folder verbs

Author: neilgfoster

CLAUDE.md

@@ -101,9 +101,11 @@ or advertise it.
 reference bundled files via `${CLAUDE_PLUGIN_ROOT}/...` — it resolves to `plugin/`.
 
 <!-- SPECKIT START -->
-Active feature plan: `specs/002-fix-graph-query-encoding/plan.md` (defect fix: percent-encode all
-Graph query params + real-URL regression coverage + Azure setup docs). Foundation feature plan:
-`specs/001-msgraph-mail-rules/plan.md` (spec, research, data-model, contracts/tools.md, quickstart
-alongside it) — read it for the technical context, the stdlib-only device-code design, the `TOOLS`
-catalog contract, and the safety-model decisions before implementing.
+Active feature plan: `specs/003-categorise-and-search-folders/plan.md` (extend the kernel with
+category-assigning rules + category-ensure under the existing rule-authoring scope, and
+search-folder create/list/remove behind a NEW `Mail.ReadWrite` auth tier `--mode folders`; research,
+data-model, contracts/tools.md, quickstart alongside it). Prior feature plans:
+`specs/002-fix-graph-query-encoding/plan.md` (percent-encode Graph query params + real-URL coverage)
+and `specs/001-msgraph-mail-rules/plan.md` (foundation: stdlib-only device-code design, `TOOLS`
+catalog contract, safety-model decisions) — read them for the technical context before implementing.
 <!-- SPECKIT END -->

DEFINITION_OF_DONE.md

@@ -7,16 +7,23 @@ plugin is "done" for its first release when **every** box below is true. Read `C
 
 - [ ] **Auth** — device-code login works end-to-end; token cached at
       `${XDG_STATE_HOME:-~/.local/state}/msgraph-stdlib/token.json` (`0600`, outside the repo) and
-      transparently refreshed. Two distinct modes: read-only (`Mail.Read`) and
-      rule-authoring (`+ MailboxSettings.ReadWrite`).
+      transparently refreshed. Three distinct modes (the scope ratchet): read-only (`Mail.Read`),
+      rule-authoring (`+ MailboxSettings.ReadWrite`), and search-folder (`Mail.ReadWrite`).
 - [ ] **Mail read** — `mail-list` and `mail-get` return messages and their internet headers,
       read-only, with concise/detailed output and a sane pagination default.
 - [ ] **Rule read** — `rule-list` enumerates existing Outlook `messageRule`s, agent-legibly.
 - [ ] **Rule verify** — `rule-verify` takes candidate predicates and returns the **read-only
       catch-set** (the messages the rule would match) without writing anything.
-- [ ] **Rule create** — `rule-create` installs a predicate→move-to-folder rule, and **refuses**
-      unless a catch-set has been verified for it.
+- [ ] **Rule create** — `rule-create` installs a predicate→move-to-folder **and/or assign-category**
+      rule, and **refuses** unless a catch-set has been verified for it (and unless it has an action).
 - [ ] **Rule remove** — `rule-remove` deletes a rule by id (the reversibility primitive).
+- [ ] **Categories** — `category-list` enumerates the mailbox master categories; `category-ensure`
+      create-if-absent a named category (coloured), under the rule-authoring scope. `rule-create`
+      ensures any category it assigns so labels always render with a colour.
+- [ ] **Search folders** — `searchfolder-create` makes a virtual `mailSearchFolder` (a saved,
+      category-filtered view; never moves/deletes mail) under the **separate** `Mail.ReadWrite` tier;
+      `searchfolder-list` enumerates them agent-legibly; `searchfolder-remove` deletes one by id
+      (reversibility primitive — affects only the virtual folder, never mail).
 
 ## Constraints (any failure = not done)
 
@@ -26,10 +33,13 @@ plugin is "done" for its first release when **every** box below is true. Read `C
       the working tree are clean of secrets; storage is the external XDG path only. No git-crypt
       dependency.
 - [ ] **Read cannot mutate.** Read-only mode holds `Mail.Read` only; no write endpoint is reachable
-      from any read skill. Write capability exists *only* after explicit `MailboxSettings.ReadWrite`
-      opt-in.
+      from any read skill. Write capability exists *only* after explicit opt-in, and each write tier is
+      a **separate, distinctly-consented** scope: rule/category authoring (`MailboxSettings.ReadWrite`)
+      and search-folder creation (`Mail.ReadWrite`, `--mode folders`) are independent ratchet steps —
+      neither read nor rule-authoring tokens can create a search folder.
 - [ ] **No imperative per-message mutation.** The plugin never archives/moves/deletes an individual
-      message itself; organisation happens only via installed rules, which file (never delete).
+      message itself; organisation happens only via installed rules, which file or label (never delete).
+      Search folders are **virtual saved views** — creating or removing one moves/deletes no mail.
 - [ ] **Agent-friendly.** Every skill meets `docs/AGENT-FRIENDLY.md`: onboarding-quality
       `description` (incl. when-to-use), flat JSON-schema inputs, agent-legible output (IDs resolved
       to names; concise/detailed), steering error messages, accurate `annotations`.

README.md

@@ -3,12 +3,17 @@
 A Claude Code plugin for Microsoft Graph (Outlook) that is **stdlib-only, zero-dependency, and
 zero-backend** by design — just `urllib` + `json`, no SDK, no server process, no install friction.
 
-It gives an agent two capabilities, with safety built into the *structure*, not the behaviour:
+It gives an agent these capabilities, with safety built into the *structure*, not the behaviour:
 
 1. **Read Outlook mail** — list/get messages and their headers, read-only.
 2. **Author native Outlook message rules** — create / list / verify / remove server-side
    `messageRule`s, so deterministic mail organisation lives *in Outlook* (runs even when nothing
-   else is, visible and editable in Outlook's own UI, reversible by deleting one rule).
+   else is, visible and editable in Outlook's own UI, reversible by deleting one rule). A rule can
+   file to a folder **and/or assign a coloured category**.
+3. **Manage master categories** — list and create-if-absent the coloured labels a rule assigns, so
+   they always render with a colour.
+4. **Create category search folders** — virtual `mailSearchFolder` views over a category, behind a
+   *separate* `Mail.ReadWrite` sign-in tier. A search folder never moves or deletes mail.
 
 ## Verbs (skills)
 
@@ -17,13 +22,18 @@ Each skill is a thin wrapper over the stdlib kernel; the runtime catalog is the
 
 | Skill | Scope it needs | What it does |
 |---|---|---|
-| `auth-login` | `Mail.Read + MailboxSettings.Read` (read, default) or `+ MailboxSettings.ReadWrite` (`--mode rules`) | Device-code sign-in; caches the token at the XDG path and refreshes it silently. **Run first.** |
+| `auth-login` | `Mail.Read + MailboxSettings.Read` (read, default), `+ MailboxSettings.ReadWrite` (`--mode rules`), or `Mail.ReadWrite` (`--mode folders`) | Device-code sign-in; caches the token at the XDG path and refreshes it silently. **Run first.** |
 | `mail-list` | `Mail.Read` | List recent inbox messages (concise/detailed, pagination default 25). |
 | `mail-get` | `Mail.Read` | Fetch one message incl. its internet headers (e.g. `List-Unsubscribe`). |
 | `rule-list` | `MailboxSettings.Read` | Enumerate existing inbox rules agent-legibly. |
 | `rule-verify` | `Mail.Read` | Compute a candidate rule's **read-only catch-set** and record the verification gate. |
-| `rule-create` | `MailboxSettings.ReadWrite` | Install a verified move-to-folder rule; refuses unverified criteria. |
+| `rule-create` | `MailboxSettings.ReadWrite` | Install a verified rule that files to a folder **and/or assigns a category**; refuses unverified criteria. |
 | `rule-remove` | `MailboxSettings.ReadWrite` | Delete a rule by id (the reversibility primitive). |
+| `category-list` | `MailboxSettings.Read` | List the mailbox master categories (name + colour). |
+| `category-ensure` | `MailboxSettings.ReadWrite` | Create a coloured category if absent (idempotent). |
+| `searchfolder-list` | `Mail.Read` | Enumerate existing virtual search folders agent-legibly. |
+| `searchfolder-create` | `Mail.ReadWrite` (`--mode folders`) | Create a virtual category search-folder view; never touches mail. |
+| `searchfolder-remove` | `Mail.ReadWrite` (`--mode folders`) | Delete a search folder by id (affects only the view, never mail). |
 
 ## Why stdlib / zero-backend
 
@@ -36,14 +46,16 @@ with no supply-chain surface beyond the standard library.
 
 - **Read-only by default.** Auth requests **`Mail.Read` only**. The plugin physically cannot move,
   archive, or delete a message — the token carries no write grant. Safety is structural.
-- **Scope ratchet.** Writing rules requires the *separate* `MailboxSettings.ReadWrite` scope,
-  granted only when you opt into rule authoring. Escalation is deliberate and auditable (the OAuth
-  consent is the record).
+- **Scope ratchet.** Writing rules/categories requires the *separate* `MailboxSettings.ReadWrite`
+  scope, and creating search folders requires a *further separate* `Mail.ReadWrite` tier
+  (`--mode folders`) — each granted only when you opt in. Escalation is deliberate and auditable (the
+  OAuth consent is the record); a read or rule-authoring token cannot create a search folder.
 - **Verify before install.** A candidate rule's **real catch-set is computed read-only** and shown
   *before* the rule is created — a rule is never trusted in the abstract (Graph `headerContains` is
   coarse substring matching, so it must be checked against actual mail).
-- **Reversible by construction.** Rules file mail to a folder; they never delete. Removing one rule
-  undoes the organisation.
+- **Reversible by construction.** Rules file or label mail; they never delete. Removing one rule
+  undoes the organisation. Search folders are virtual saved views — creating or removing one never
+  moves or deletes a message.
 
 ## Layout
 
@@ -64,7 +76,8 @@ CLAUDE.md                                # grounding + build plan for a Claude C
 
 An **Azure AD app registration** (public client, device-code / public-client flow **enabled**). Add
 the delegated permissions `Mail.Read` + `MailboxSettings.Read` (read mail and list rules), plus
-`MailboxSettings.ReadWrite` only if you want rule authoring. No cost, no admin consent for personal
+`MailboxSettings.ReadWrite` only if you want rule/category authoring, plus `Mail.ReadWrite` only if
+you want to create search folders (`--mode folders`). No cost, no admin consent for personal
 accounts. Then export the resulting identifiers before first sign-in (read from the environment,
 never hardcoded):
 

plugin/skills/category-ensure/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: "category-ensure"
+description: "Ensure a named Outlook master category exists: create it with a colour if absent (POST /me/outlook/masterCategories), no-op if it already exists. Idempotent. Requires rule-authoring sign-in (/msgraph-auth-login --mode rules; MailboxSettings.ReadWrite). Use to pre-create a label with a specific colour before assigning it; rule-create already ensures any category it assigns, so calling this first is optional unless you want to choose the colour. A category's display name is immutable once created. Pass --name and an optional --color preset (default preset9)."
+argument-hint: "--name <category name> [--color presetN]"
+user-invocable: true
+disable-model-invocation: false
+annotations:
+  readOnlyHint: false
+  destructiveHint: false
+  idempotentHint: true
+  openWorldHint: true
+---
+
+## What this does
+
+Create-if-absent for a master category. Lists the master categories, matches `--name`
+case-insensitively, and if missing creates it (`POST /me/outlook/masterCategories` with
+`{displayName, color}`). If present, it reports a no-op. Needs `MailboxSettings.ReadWrite` — the same
+rule-authoring tier; no new scope.
+
+Use it when you want a label to render with a **specific colour**. `rule-create --assign_category`
+ensures categories automatically (defaulting the colour to `preset9`), so this verb is only needed
+for colour control or to seed labels ahead of time. The display name cannot be changed after creation.
+
+## Discoverability
+
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT}/src/msgraph/client.py" describe --name category-ensure
+```
+
+## How it runs
+
+```bash
+/msgraph-auth-login --mode rules
+python3 "${CLAUDE_PLUGIN_ROOT}/src/msgraph/client.py" category-ensure --name "Needs attention" --color preset9
+# or:  python3 -m msgraph.client category-ensure --name "Receipts" --color preset5
+```
+
+## Output
+
+```
+Created category "Needs attention" (preset9). It now renders with a colour.
+Category "Receipts" already exists (preset5); no change.
+```
+
+## Errors steer the agent
+
+```
+error: This action needs rule-authoring permission … run /msgraph-auth-login --mode rules.
+```

plugin/skills/category-list/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: "category-list"
+description: "List the mailbox's Outlook master categories (each label's name and colour), read-only, via GET /me/outlook/masterCategories. Requires read sign-in (/msgraph-auth-login; MailboxSettings.Read). Use to see which labels already exist before authoring an assign-category rule (rule-create --assign_category) or a category search folder (searchfolder-create --category). Pairs with category-ensure, which create-if-absent a named category. concise (default) shows name + colour; detailed returns full JSON."
+argument-hint: "[--format concise|detailed]"
+user-invocable: true
+disable-model-invocation: false
+annotations:
+  readOnlyHint: true
+  destructiveHint: false
+  idempotentHint: true
+  openWorldHint: true
+---
+
+## What this does
+
+Lists the mailbox master category list (`GET /me/outlook/masterCategories`) — the named, coloured
+labels Outlook uses. Read-only; needs only `MailboxSettings.Read` (the default read sign-in). Use it
+to discover existing labels before you assign one in a rule or filter on one in a search folder.
+
+## Discoverability
+
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT}/src/msgraph/client.py" describe --name category-list
+```
+
+## How it runs
+
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT}/src/msgraph/client.py" category-list
+# or:  python3 -m msgraph.client category-list --format detailed
+```
+
+## Output
+
+```
+- "Needs attention"  (preset9)
+- "Receipts"  (preset5)
+2 categor(y/ies).
+```
+
+## Errors steer the agent
+
+```
+error: Not signed in — run /msgraph-auth-login first, then retry.
+```

plugin/skills/rule-create/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: "rule-create"
-description: "Install a native Outlook message rule that FILES matching mail to a folder (move-to-folder only — never delete). Requires rule-authoring sign-in (run /msgraph-auth-login --mode rules; MailboxSettings.ReadWrite). REFUSES unless the exact same header_contains criteria were verified first with rule-verify — verify-then-install is a hard safety gate, not a convention. Use after you have inspected headers (mail-get) and confirmed the catch-set (rule-verify). The rule appears in Outlook's own Rules UI and is fully reversible: remove it with rule-remove and any mail already filed stays put. Pass a name, the verified header_contains substrings, and an existing target folder name."
-argument-hint: "--name <rule name> --header_contains SUBSTR [SUBSTR ...] --move_to_folder <folder name>"
+description: "Install a native Outlook message rule that FILES matching mail to a folder and/or ASSIGNS a category to it (move-to-folder and/or assign-category — never delete). Requires rule-authoring sign-in (run /msgraph-auth-login --mode rules; MailboxSettings.ReadWrite). REFUSES unless the exact same header_contains criteria were verified first with rule-verify — verify-then-install is a hard safety gate, not a convention — and refuses if you give no action at all. Any assigned category is ensured to exist (coloured) first. Use after you have inspected headers (mail-get) and confirmed the catch-set (rule-verify). The rule appears in Outlook's own Rules UI and is fully reversible: remove it with rule-remove and any mail already filed/labelled stays put. Pass a name, the verified header_contains substrings, and at least one of --move_to_folder or --assign_category."
+argument-hint: "--name <rule name> --header_contains SUBSTR [SUBSTR ...] [--move_to_folder <folder name>] [--assign_category NAME ...]"
 user-invocable: true
 disable-model-invocation: false
 annotations:
@@ -14,9 +14,17 @@ annotations:
 ## What this does
 
 Creates a server-side `messageRule` under `POST /me/mailFolders/inbox/messageRules` with a
-`headerContains` predicate and a **`moveToFolder` action only**. No delete-style action is ever
-constructed, so installing a rule only ever *files* mail — removing the rule undoes the organisation
-and mail already filed stays put.
+`headerContains` predicate and a **`moveToFolder` and/or `assignCategories` action** — you must supply
+at least one (no action → refusal). No delete-style action is ever constructed, so installing a rule
+only ever *files* and/or *labels* mail — removing the rule undoes the organisation and mail already
+filed/labelled stays put.
+
+**Assign-category action.** Pass `--assign_category "Needs attention"` (repeatable) to tag matching
+mail with one or more Outlook categories — alone, or combined with `--move_to_folder` to label **and**
+file. Before installing, each named category is **ensured to exist** in the master list (created with
+a colour if absent, via the same `MailboxSettings.ReadWrite` scope), so the label always renders
+meaningfully. Use `category-list` to see existing labels and `category-ensure` to pre-create one with
+a specific colour.
 
 **Two gates must pass, or it refuses (this is the heart of the safety model):**
 
@@ -37,6 +45,9 @@ mail to a folder, they never create or delete one.
 /msgraph-auth-login --mode rules                               # escalate (separate consent)
 /msgraph-rule-create --name "Newsletters" \
     --header_contains "List-Unsubscribe" --move_to_folder "Newsletters"
+# or label on arrival (alone or combined with --move_to_folder):
+/msgraph-rule-create --name "Flag newsletters" \
+    --header_contains "List-Unsubscribe" --assign_category "Needs attention"
 ```
 
 ## Discoverability