@rubytech/create-siteoffice-code 0.1.256

package/payload/platform/plugins/outlook/mcp/dist/tools/mailbox-info.js

@@ -0,0 +1,58 @@
+import { callGraph } from "../lib/graph-client.js";
+import { log } from "../lib/log.js";
+/**
+ * Health probe: answers "did account X auth?" + "is the token in the
+ * refresh window?" without grepping logs. If the account isn't registered,
+ * returns `registered: false` rather than throwing.
+ */
+export async function runMailboxInfo(config) {
+    const blob = config.tokenStore.read();
+    const startMs = Date.now();
+    if (!blob) {
+        log({
+            event: "mailbox-info",
+            account: config.accountId,
+            tokenWithinRefreshWindow: false,
+            folderCount: 0,
+        });
+        return {
+            registered: false,
+            graphUserId: null,
+            scopes: [],
+            tokenExpSec: null,
+            refreshTokenExpSec: null,
+            tokenWithinRefreshWindow: false,
+            folderCount: null,
+        };
+    }
+    let folderCount = null;
+    try {
+        const result = await callGraph(config, async (client) => {
+            return (await client.api("/me/mailFolders").top(50).select("id").get());
+        }, { tool: "mailbox-info" });
+        folderCount = result.value.length;
+    }
+    catch {
+        // Don't throw — operator should still see the auth state even if Graph
+        // is unreachable. folderCount stays null.
+        folderCount = null;
+    }
+    const tokenWithinRefreshWindow = config.tokenStore.needsRefresh();
+    log({
+        event: "mailbox-info",
+        account: config.accountId,
+        tokenWithinRefreshWindow,
+        folderCount: folderCount ?? -1,
+        elapsedMs: Date.now() - startMs,
+    });
+    return {
+        registered: true,
+        graphUserId: blob.graphUserId,
+        scopes: blob.scopes,
+        tokenExpSec: Math.floor(blob.accessTokenExpiry / 1000),
+        refreshTokenExpSec: Math.floor(blob.refreshTokenExpiry / 1000),
+        tokenWithinRefreshWindow,
+        folderCount,
+    };
+}
+//# sourceMappingURL=mailbox-info.js.map

package/payload/platform/plugins/outlook/mcp/dist/tools/mailbox-info.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mailbox-info.js","sourceRoot":"","sources":["../../src/tools/mailbox-info.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC;AAyBpC;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,MAAyB;IAC5D,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC;IACtC,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAE3B,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,GAAG,CAAC;YACF,KAAK,EAAE,cAAc;YACrB,OAAO,EAAE,MAAM,CAAC,SAAS;YACzB,wBAAwB,EAAE,KAAK;YAC/B,WAAW,EAAE,CAAC;SACf,CAAC,CAAC;QACH,OAAO;YACL,UAAU,EAAE,KAAK;YACjB,WAAW,EAAE,IAAI;YACjB,MAAM,EAAE,EAAE;YACV,WAAW,EAAE,IAAI;YACjB,kBAAkB,EAAE,IAAI;YACxB,wBAAwB,EAAE,KAAK;YAC/B,WAAW,EAAE,IAAI;SAClB,CAAC;IACJ,CAAC;IAED,IAAI,WAAW,GAAkB,IAAI,CAAC;IACtC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,SAAS,CAC5B,MAAM,EACN,KAAK,EAAE,MAAM,EAAE,EAAE;YACf,OAAO,CAAC,MAAM,MAAM,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,CAAiC,CAAC;QAC1G,CAAC,EACD,EAAE,IAAI,EAAE,cAAc,EAAE,CACzB,CAAC;QACF,WAAW,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC;IACpC,CAAC;IAAC,MAAM,CAAC;QACP,uEAAuE;QACvE,0CAA0C;QAC1C,WAAW,GAAG,IAAI,CAAC;IACrB,CAAC;IAED,MAAM,wBAAwB,GAAG,MAAM,CAAC,UAAU,CAAC,YAAY,EAAE,CAAC;IAClE,GAAG,CAAC;QACF,KAAK,EAAE,cAAc;QACrB,OAAO,EAAE,MAAM,CAAC,SAAS;QACzB,wBAAwB;QACxB,WAAW,EAAE,WAAW,IAAI,CAAC,CAAC;QAC9B,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO;KAChC,CAAC,CAAC;IAEH,OAAO;QACL,UAAU,EAAE,IAAI;QAChB,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,WAAW,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,iBAAiB,GAAG,IAAI,CAAC;QACtD,kBAAkB,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,kBAAkB,GAAG,IAAI,CAAC;QAC9D,wBAAwB;QACxB,WAAW;KACZ,CAAC;AACJ,CAAC"}

package/payload/platform/plugins/outlook/mcp/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@maxy/outlook",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@microsoft/microsoft-graph-client": "^3.0.7",
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  }
+}

package/payload/platform/plugins/outlook/mcp/scripts/verify-doc-impl.sh

@@ -0,0 +1,109 @@
+#!/usr/bin/env bash
+# verify-doc-impl.sh
+#
+# Doc-impl alignment grep, promoted from the manual verification step
+# to a permanent gate. Run from anywhere; resolves to the plugin tree itself.
+#
+# Verifies:
+#   1. Every `outlook-*` tool name in `platform/plugins/docs/references/outlook-guide.md`
+#      resolves to a `server.tool("outlook-...", ...)` registration in mcp/src/index.ts.
+#   2. Every `[outlook-mcp]` log-line shape in outlook-guide.md matches a
+#      log({event:"..."}) literal in mcp/src/.
+#   3. Every tool name in `PLUGIN.md` frontmatter matches a registration in mcp/src/index.ts.
+#   4. Public-agent isolation: `outlook` does not appear in public-agent assembly files.
+#   5. Bearer-token redaction: log.ts contains the redaction regex pair.
+#
+# Exit non-zero on any mismatch. Print the first diverging item.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PLUGIN_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+REPO_ROOT="$(cd "$PLUGIN_DIR/../../../.." && pwd)"
+GUIDE="$REPO_ROOT/platform/plugins/docs/references/outlook-guide.md"
+PLUGIN_MD="$REPO_ROOT/platform/plugins/outlook/PLUGIN.md"
+INDEX_TS="$PLUGIN_DIR/src/index.ts"
+SRC_DIR="$PLUGIN_DIR/src"
+
+fail() {
+  echo "[verify-doc-impl] FAIL: $1" >&2
+  exit 1
+}
+
+[ -f "$GUIDE" ] || fail "operator guide missing: $GUIDE"
+[ -f "$PLUGIN_MD" ] || fail "PLUGIN.md missing: $PLUGIN_MD"
+[ -f "$INDEX_TS" ] || fail "index.ts missing: $INDEX_TS"
+
+# Tool names registered in src/index.ts. The MCP-SDK call shape is:
+#   server.tool(
+#     "outlook-XYZ",
+#     ...
+# so the tool name appears on its own line as `  "outlook-XYZ",`.
+TOOLS_REGISTERED=$(grep -oE '"outlook-[a-z\-]+",' "$INDEX_TS" \
+  | sed -E 's/^"|",$//g' | sort -u)
+
+# Tool names referenced in outlook-guide.md (backtick-wrapped)
+TOOLS_IN_GUIDE=$(grep -oE '`outlook-[a-z\-]+`' "$GUIDE" | tr -d '`' | sort -u)
+
+# Tool names in PLUGIN.md frontmatter (lines starting with "  - outlook-")
+TOOLS_IN_PLUGIN_MD=$(grep -E '^\s+- outlook-' "$PLUGIN_MD" | sed -E 's/^[[:space:]]*-[[:space:]]+//' | sort -u)
+
+# Set 1: every tool in guide must be registered
+while IFS= read -r tool; do
+  [ -z "$tool" ] && continue
+  if ! echo "$TOOLS_REGISTERED" | grep -qx "$tool"; then
+    fail "tool '$tool' referenced in outlook-guide.md but not registered in mcp/src/index.ts"
+  fi
+done <<< "$TOOLS_IN_GUIDE"
+
+# Set 2: every tool in PLUGIN.md frontmatter must be registered
+while IFS= read -r tool; do
+  [ -z "$tool" ] && continue
+  if ! echo "$TOOLS_REGISTERED" | grep -qx "$tool"; then
+    fail "tool '$tool' declared in PLUGIN.md frontmatter but not registered in mcp/src/index.ts"
+  fi
+done <<< "$TOOLS_IN_PLUGIN_MD"
+
+# Set 3: every registered tool must appear in PLUGIN.md frontmatter
+while IFS= read -r tool; do
+  [ -z "$tool" ] && continue
+  if ! echo "$TOOLS_IN_PLUGIN_MD" | grep -qx "$tool"; then
+    fail "tool '$tool' registered in mcp/src/index.ts but missing from PLUGIN.md frontmatter"
+  fi
+done <<< "$TOOLS_REGISTERED"
+
+# Log-shape alignment: every event tag in outlook-guide.md must have a matching
+# log({ event: "..." }) literal in mcp/src/. Event tags appear in the table as:
+#   | Auth init | `auth-init account=<id> codeChallenge=...` |
+# We pull the first word inside backticks on each table row that contains "account=".
+EVENTS_IN_GUIDE=$(grep -E '`[a-z\-]+ account=' "$GUIDE" \
+  | sed -E 's/.*`([a-z\-]+) account=.*/\1/' | sort -u)
+EVENTS_IN_SRC=$(grep -rh -oE 'event:[[:space:]]*"[a-z\-]+"' "$SRC_DIR" \
+  | sed -E 's/^event:[[:space:]]*"|"$//g' | sort -u)
+
+while IFS= read -r ev; do
+  [ -z "$ev" ] && continue
+  if ! echo "$EVENTS_IN_SRC" | grep -qx "$ev"; then
+    fail "log event '$ev' documented in outlook-guide.md but no log({event:\"$ev\"}) literal in mcp/src/"
+  fi
+done <<< "$EVENTS_IN_GUIDE"
+
+# Public-agent isolation: outlook must not appear in public-agent assembly files.
+ISOLATION_HITS=$( (cd "$REPO_ROOT" && grep -rE 'outlook' \
+  platform/ui/app/lib/claude-agent/public-agent.ts \
+  platform/ui/app/lib/claude-agent/system-prompt-assembly.ts \
+  platform/templates/agents/public/ 2>/dev/null) || true)
+if [ -n "$ISOLATION_HITS" ]; then
+  echo "$ISOLATION_HITS" >&2
+  fail "isolation breach: 'outlook' string appears in public-agent assembly path"
+fi
+
+# Bearer redaction guard: lib/log.ts must contain both regex literals.
+if ! grep -q 'Bearer\\s+\[A-Za-z0-9' "$SRC_DIR/lib/log.ts"; then
+  fail "Bearer redaction regex missing in lib/log.ts"
+fi
+if ! grep -q 'access_token=\[A-Za-z0-9' "$SRC_DIR/lib/log.ts"; then
+  fail "access_token redaction regex missing in lib/log.ts"
+fi
+
+echo "[verify-doc-impl] OK — $(echo "$TOOLS_REGISTERED" | wc -l | tr -d ' ') tools, $(echo "$EVENTS_IN_GUIDE" | wc -l | tr -d ' ') events, isolation, redaction all aligned"

package/payload/platform/plugins/outlook/references/auth.md

@@ -0,0 +1,118 @@
+# Outlook Auth Reference
+
+## Vendored upstream
+
+The PKCE flow and encrypted token store are adapted from:
+
+- **Repo:** [`nsakki55/outlook-mcp`](https://github.com/nsakki55/outlook-mcp)
+- **Pinned commit:** `e49d8e68ac8d69db653c25803127dc3b98626cda`
+- **License:** MIT
+
+Adaptations:
+
+- Per-account paths (`{ACCOUNTS_DIR}/{accountId}/secrets/outlook/`) instead of upstream's single-user `~/.outlook-mcp/`
+- `keytar` fallback removed (Pi runs headless; no Secret Service)
+- `node-persist` removed; single JSON blob written atomically (temp + rename)
+- Loopback callback port is **ephemeral** via `server.listen(0)` (upstream uses fixed `49152`)
+- No `xdg-open` browser auto-launch; auth URL is logged + returned to the operator for the VNC browser
+- `outlook-account-register` awaits the full PKCE flow synchronously (5-min timeout)
+
+To re-vendor at a newer SHA:
+
+1. Fetch `tokenManager.ts` and `authManager.ts` from the new SHA.
+2. Apply the adaptations above.
+3. Update the **Pinned commit** line above.
+4. Bump `@maxy/outlook` version.
+5. Run the test suite.
+
+## Entra app registration (one-time per Maxy install)
+
+The plugin requires an Azure AD ("Entra ID") app the operator owns. Steps:
+
+1. Sign in to the [Azure portal](https://portal.azure.com) with a Microsoft account.
+2. Go to **Microsoft Entra ID → App registrations → New registration**.
+3. **Name:** `Maxy Outlook` (or any name the operator prefers).
+4. **Supported account types:** *Accounts in any organizational directory and personal Microsoft accounts*.
+5. **Redirect URI** (Platform: *Mobile and desktop applications*): `http://localhost`
+   - **Note:** no port is specified. Microsoft Identity Platform treats native-app loopback redirects with port-flexible matching, allowing the plugin to use an ephemeral port.
+6. Click **Register**. Copy the **Application (client) ID** — this is `OUTLOOK_CLIENT_ID`.
+7. Go to **API permissions → Add a permission → Microsoft Graph → Delegated permissions**, add:
+   - `offline_access`
+   - `User.Read`
+   - `Mail.Read`
+   - `Calendars.Read`
+   - `Contacts.Read`
+8. Click **Grant admin consent for <tenant>** if applicable. Personal accounts auto-consent at first sign-in.
+9. Set the env var on the Pi:
+   ```
+   OUTLOOK_CLIENT_ID=<the Application (client) ID copied above>
+   OUTLOOK_TENANT_ID=common   # or your tenant GUID for single-tenant
+   ```
+
+## PKCE flow (per-account)
+
+Triggered by `outlook-account-register`. Sequence:
+
+```
+operator                                        plugin                              Microsoft
+   |                                              |                                     |
+   | outlook-account-register                     |                                     |
+   |--------------------------------------------->|                                     |
+   |                                              | bind 127.0.0.1:<ephemeral-port>     |
+   |                                              | generate code_verifier (32 bytes)   |
+   |                                              | code_challenge = SHA256(verifier)   |
+   |                                              | state = randomBytes(16)             |
+   |                                              |                                     |
+   | { authUrl, status: "pending" }               |                                     |
+   |<---------------------------------------------|                                     |
+   |                                              |                                     |
+   | open authUrl in VNC browser                  |                                     |
+   |--------------------------------------------------------------------------------->  |
+   |                                              |                                     |
+   |                                  consent ←--------------------------------------- |
+   |                                              |                                     |
+   |                                              | GET /callback?code=...&state=...   |
+   |                                              | <----------------------------------|
+   |                                              |                                     |
+   |                                              | verify state                        |
+   |                                              | POST /token (code + verifier)       |
+   |                                              | -----------------------------------> |
+   |                                              | < tokens                             |
+   |                                              | <----------------------------------- |
+   |                                              | encrypt → write {tokens.enc}         |
+   |                                              | GET /me  (record graphUserId)        |
+   |                                              | -----------------------------------> |
+   |                                              |                                     |
+   | { status: "registered", graphUserId, ... }   |                                     |
+   |<---------------------------------------------|                                     |
+```
+
+## Token store layout
+
+Per-account, mode 0700 directory + mode 0600 files:
+
+```
+data/accounts/<accountId>/secrets/outlook/
+├── .key          # 32 random bytes, base64-encoded — the AES-256-CBC key
+└── tokens.enc    # AES-256-CBC ciphertext: "<iv-hex>:<cipher-hex>" of JSON blob
+```
+
+The JSON blob shape:
+
+```typescript
+{
+  accessToken: string;
+  refreshToken: string | null;
+  accessTokenExpiry: number;        // unix ms
+  refreshTokenExpiry: number;       // unix ms; ~90 days from issue
+  lastRefresh: number;              // unix ms
+  graphUserId: string | null;       // from /me.id
+  scopes: string[];                 // granted scopes from token response
+}
+```
+
+Atomic write: temp + rename. Either old or new tokens, never partial.
+
+## Refresh
+
+Triggered automatically when the access token is within `5 minutes` of expiry (`refreshThresholdMs`). Failure → terminal `token-refresh-failed`, tokens cleared, operator must re-register. Refresh tokens last 90 days.

package/payload/platform/plugins/outlook/references/graph-surfaces.md

@@ -0,0 +1,114 @@
+# Graph Surfaces
+
+Microsoft Graph endpoints used by each tool, with the response shape and the fields selected.
+
+## outlook-mail-list
+
+**Endpoint (Inbox):** `GET /me/mailFolders/Inbox/messages?$top={N}&$orderby=receivedDateTime DESC&$select=id,subject,from,receivedDateTime,bodyPreview,isRead`
+
+**Endpoint (other folder):** `GET /me/mailFolders/{folderId-or-displayName}/messages?...`
+
+**Returned shape:**
+```typescript
+Array<{
+  id: string;
+  subject: string | null;
+  from: string | null;          // emailAddress.address
+  receivedDateTime: string;     // ISO 8601
+  bodyPreview: string;          // truncated to 1024 chars
+  isRead: boolean;
+}>
+```
+
+## outlook-mail-search
+
+**Endpoint:** `GET /me/messages?$search="{query}"&$top={N}&$select=id,subject,from,receivedDateTime,bodyPreview,isRead`
+
+**Required header:** `ConsistencyLevel: eventual` (Graph requirement for `$search`).
+
+**Returned shape:** identical to `outlook-mail-list`.
+
+## outlook-calendar-list
+
+**Endpoint:** `GET /me/calendarView?startDateTime={now}&endDateTime={now+rangeDays}&$top={N}&$orderby=start/dateTime ASC&$select=id,subject,start,end,location,attendees,isAllDay,organizer`
+
+**Returned shape:**
+```typescript
+Array<{
+  id: string;
+  subject: string | null;
+  start: { dateTime: string; timeZone: string };
+  end:   { dateTime: string; timeZone: string };
+  location: string | null;
+  attendees: Array<{ email: string; name: string | null; response: string }>;
+  isAllDay: boolean;
+  organizer: string | null;
+}>
+```
+
+## outlook-calendar-event
+
+**Endpoint:** `GET /me/events/{eventId}?$select=id,subject,start,end,location,attendees,isAllDay,organizer,bodyPreview,body,webLink`
+
+**Returned shape:** as `outlook-calendar-list` plus:
+```typescript
+{
+  bodyPreview: string;       // 1024 chars
+  body: string;              // up to 16384 chars (HTML or text per content type)
+  webLink: string | null;
+}
+```
+
+## outlook-contacts-list
+
+**Endpoint:** `GET /me/contacts?$top={N}&$select=id,displayName,emailAddresses,businessPhones,homePhones,mobilePhone,jobTitle,companyName`
+
+**Returned shape:**
+```typescript
+Array<{
+  id: string;
+  displayName: string | null;
+  emailAddresses: string[];   // .address values flattened
+  phones: string[];           // business + home + mobile concatenated
+  jobTitle: string | null;
+  companyName: string | null;
+}>
+```
+
+## outlook-mailbox-info
+
+**Endpoint:** `GET /me/mailFolders?$top=50&$select=id` (best-effort — folder count is null if Graph is unreachable)
+
+**Returned shape:**
+```typescript
+{
+  registered: boolean;
+  graphUserId: string | null;
+  scopes: string[];
+  tokenExpSec: number | null;
+  refreshTokenExpSec: number | null;
+  tokenWithinRefreshWindow: boolean;
+  folderCount: number | null;
+}
+```
+
+## outlook-account-register
+
+No Graph endpoint of its own. The flow exchanges an authorization code at:
+
+- `POST https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token`
+
+After the token exchange, the tool fetches `GET /me?$select=id,mail,userPrincipalName` to record `graphUserId`.
+
+## Error classification
+
+All tool failures route through `lib/graph-client.ts:classifyGraphError`. Decisions key off **status code + Graph `error.code` field + headers**, never the error `message` body.
+
+| HTTP status | Graph `error.code` | Class | Action |
+|---|---|---|---|
+| 401 | (any) | `auth` | Refresh once, retry; if still 401 → terminal `auth-required` |
+| 429 | (any) — header `Retry-After` present | `rate-limit-recoverable` | Backoff per header, retry once |
+| 429 | (any) — header `Retry-After` absent | `rate-limit-terminal` | Terminal abort |
+| 503 | `MailboxNotEnabledForRESTAPI` | `on-prem` | Terminal: route operator to IMAP plugin |
+| 5xx | (any) | `5xx` | Retry once with 500 ms; then terminal |
+| any | (any) | `other` | Re-throw |

package/payload/platform/plugins/outlook/skills/outlook/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: outlook
+description: "Microsoft 365 / Outlook.com via Microsoft Graph (read-only). Use when the user asks about their Outlook mail, calendar, or contacts — listing, searching, or checking events. First-time use requires outlook-account-register; subsequent use is transparent. Tools — outlook-mail-list / outlook-mail-search (inbox), outlook-calendar-list / outlook-calendar-event (calendar), outlook-contacts-list (contacts), outlook-mailbox-info (health), outlook-account-register (PKCE register)."
+---
+
+# Outlook (Microsoft Graph)
+
+Read-only access to the user's Outlook.com or Microsoft 365 mailbox via Microsoft Graph. Per-account OAuth, encrypted token storage, refresh handled automatically.
+
+## When to activate
+
+Activate when the user asks about:
+
+- Their Outlook / Office 365 / Hotmail mail (recent messages, search by keyword/sender)
+- Their Outlook calendar (upcoming events, specific event details, free/busy windows)
+- Their Outlook contacts
+
+Do **not** activate for:
+
+- IMAP-only providers (Gmail, iCloud, custom domains not on Microsoft 365) — use the `email` plugin instead.
+- On-premises Exchange — Microsoft Graph deprecated hybrid REST 2023-07. The plugin detects on-prem mailboxes and emits a clear error pointing to the IMAP path.
+- Sending / drafting / modifying messages or events — out of scope. Read-only.
+
+## First-time setup (one-time per account)
+
+The Outlook plugin needs an **Entra app registration** in the operator's Microsoft tenant. This is a one-time-per-install step (not per-account), documented at [`references/auth.md`](references/auth.md).
+
+Once the Entra app exists and `OUTLOOK_CLIENT_ID` is set in the Maxy installation, run:
+
+1. **`outlook-account-register`** — the tool returns an `authUrl`. The operator opens this URL in the VNC browser, signs in with the Microsoft account they want to connect, and consents to the requested scopes (`offline_access`, `User.Read`, `Mail.Read`, `Calendars.Read`, `Contacts.Read`).
+2. Tool returns `{ status: "registered", graphUserId, scopes, tokenExpSec }` once consent completes.
+
+Subsequent tool calls use the persisted refresh token to mint access tokens transparently. Re-register is only needed if the refresh token expires (90 days) or the user revokes consent.
+
+## Reading mail
+
+- `outlook-mail-list` — recent mail, default top=25, folder=Inbox.
+- `outlook-mail-search query=<keyword>` — Microsoft Graph `$search` over the mailbox.
+
+## Reading calendar
+
+- `outlook-calendar-list rangeDays=<N>` — events in the next N days (default 7, max 365).
+- `outlook-calendar-event eventId=<id>` — single event with full body and attendees.
+
+## Reading contacts
+
+- `outlook-contacts-list` — top contacts, default top=50.
+
+## Health check
+
+- `outlook-mailbox-info` — quick state probe: is the account registered? Are tokens within the refresh window? How many folders are visible? Useful when troubleshooting a tool that returned `auth-required`.
+
+## What can go wrong
+
+| Error | Meaning | Operator action |
+|---|---|---|
+| `auth-required` | Account not registered, or refresh token expired | Run `outlook-account-register` |
+| `Outlook token refresh failed` | Network down or refresh token invalidated | Verify connectivity; re-run register if persistent |
+| `Microsoft Graph does not support on-premises Exchange` | Mailbox is on hybrid Exchange | Use the `email` plugin (IMAP) |
+| `Outlook rate-limited without Retry-After hint` | Graph 429 with no backoff guidance | Retry later; if persistent, file a bug |
+
+## Reference files
+
+- [`references/auth.md`](references/auth.md) — Entra app registration + PKCE flow + re-vendor procedure
+- [`references/graph-surfaces.md`](references/graph-surfaces.md) — Graph endpoint and response shape per tool

package/payload/platform/plugins/projects/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "projects",
+  "description": "Structured project execution. Phased sprints, operational investigations, deliverable reviews, and retrospectives — backed by :Project:Task graph nodes with HAS_TASK relationships, health signals, and lifecycle tracking.",
+  "version": "0.1.0",
+  "author": {
+    "name": "Rubytech LLC"
+  }
+}

package/payload/platform/plugins/projects/PLUGIN.md

@@ -0,0 +1,90 @@
+---
+name: projects
+description: "Structured project execution. Phased sprints, operational investigations, deliverable reviews, and retrospectives — backed by :Project:Task graph nodes with HAS_TASK relationships, health signals, and lifecycle tracking."
+requires:
+  - work
+metadata: {"platform":{"always":false,"embed":["admin"],"pluginKey":"projects","optional":true,"recommended":true}}
+---
+
+# Projects
+
+Structured execution discipline for business work. When the user has a project — a kitchen refit, a client engagement, a product launch, an operational investigation — this plugin provides phased workflows backed by dedicated project tools that handle graph operations atomically.
+
+## When to Apply
+
+When the user describes work that involves multiple steps, dependencies, or deliverables, offer structured execution. Ask: "Would you like to run this as a structured project, or just handle it as a task?" Learn the user's preference over time — if they consistently choose one mode, stop asking and default to it.
+
+Explicit triggers always apply structured execution without asking:
+- "let's sprint on..."
+- "run a project on..."
+- "investigate why..."
+- "review the deliverables for..."
+- "let's do a retro on..."
+
+## Modes
+
+| Mode | When | Reference |
+|------|------|-----------|
+| Sprint | Multi-step project execution with deliverables | `references/sprint.md` |
+| Investigation | Operational problem that needs root-cause diagnosis | `references/investigation.md` |
+| Review | Deliverable ready for quality check against the brief | `references/review.md` |
+| Retrospective | Project completed, extract learnings for future work | `references/retrospective.md` |
+
+Load the relevant reference via `plugin-read` when entering a mode. Each reference describes outcomes and constraints for that mode — follow them.
+
+## Creating a Project
+
+Use `project-create` to create a project atomically. One tool call creates the parent `:Project:Task` node, all child work items, dependency relationships (`BLOCKS`), and entity relationships (`RAISED_BY`, `AFFECTS`) in a single transaction.
+
+Choose a tier based on scope:
+- **quick** — straightforward work, few steps (e.g., boiler install)
+- **standard** — moderate complexity, multiple phases (e.g., kitchen refit)
+- **full** — significant scope, many dependencies (e.g., new build project)
+
+Include work items with their dependencies when the scope is known. If the user describes work incrementally, create the project first and add tasks later via `work-create` + `work-relate`.
+
+## Checking Project Status
+
+Use `project-list` to see all active projects with health signals. Use `project-get` for detailed status on a specific project including children, blockers, and lifecycle history.
+
+Health signals are computed server-side from child task data:
+
+| Signal | Meaning |
+|--------|---------|
+| Green | On track — no overdue tasks, no unresolved blockers |
+| Amber | Warning — at least one overdue task or blocker |
+| Red | At risk — multiple overdue, critical blocker, or stale |
+| Grey | No due dates set — shows completion count only |
+
+## Updating a Project
+
+Use `project-update` to change phase, tier, target date, client reference, status, or append notes. Phase changes automatically record `[PROJECT:PHASE]` lifecycle notes — no need to pass a separate note for transitions.
+
+## Completing a Project
+
+Use `project-complete` to mark a project done. The tool returns any incomplete children so you can confirm with the user: "2 tasks are still pending: X and Y. Mark them as cancelled and complete the project?" The tool always completes — it informs rather than gates.
+
+## Session-Start Awareness
+
+Active project summaries are injected into the session context automatically. At session start, project health data (name, phase, signal, next action) appears in the `<previous-context>` block without any tool calls needed.
+
+When project context is present, surface it conversationally: "You have 2 active projects. The kitchen refit is on track (3 of 5 done). The boiler install is blocked — waiting on parts."
+
+## Structured Lifecycle Notes
+
+The project tools append structured notes to the project node at key lifecycle moments. These create a searchable audit trail consumed by the retrospective to reconstruct project timelines.
+
+| Event | Note format |
+|-------|-------------|
+| Project start | `[PROJECT:START] {name} — {tier} tier, {n} tasks planned` |
+| Phase transition | `[PROJECT:PHASE] {phase name} — {brief summary of outcome}` |
+| Scope change | `[PROJECT:CHANGE] {what changed} — Reason: {why}` |
+| Issue recorded | `[PROJECT:ISSUE] {description} — Impact: {assessment}` |
+| Project complete | `[PROJECT:COMPLETE] {name} — {done}/{total} tasks done, {n} deferred` |
+| Project abandoned | `[PROJECT:ABANDONED] {name} — Reason: {why}` |
+
+For scope changes and issues, use `project-update` with a `note` parameter following the format above.
+
+## Dependencies
+
+This plugin requires the `work` plugin to be enabled. Project tools are co-located in the work MCP server — same data domain, same Neo4j connection. If work tools are unavailable (work plugin not enabled), tell the user: "I need the work plugin to run structured projects. Would you like to enable it?" Do not attempt structured execution without work tools — fall back to a regular conversational approach until the dependency is resolved.

package/payload/platform/plugins/projects/references/investigation.md

@@ -0,0 +1,63 @@
+# Investigation
+
+Root-cause diagnosis for operational problems. When something is going wrong — customer complaints spiking, a process is failing, costs are running over, a system isn't working as expected — this mode applies disciplined investigation to find the actual cause before proposing fixes.
+
+The iron rule: **no fixes without root cause.** Speculative fixes mask problems and waste time. One measurement beats three guesses.
+
+## Phases
+
+### Investigate
+
+Gather evidence about the problem. What is actually happening? What should be happening? When did the gap appear?
+
+- Search memory for relevant history — prior incidents, related changes, affected entities
+- Check task history for recent work that may be related
+- Ask the user targeted questions to establish the timeline and scope
+- Create a Task for this investigation with `[PROJECT:START] Investigation: {problem description}`
+
+Record what you find in the investigation task notes — every data point, every observation.
+
+### Analyse
+
+Pattern-match the evidence. What does the data tell you?
+
+- Look for correlations: did the problem start when something changed?
+- Check for scope: is this one instance or a pattern? One customer or many?
+- Test assumptions: is what the user believes about the problem supported by evidence?
+- Identify what you don't know and what evidence would fill the gap
+
+Record the analysis in task notes: `[PROJECT:PHASE] Analysis — {key findings}`.
+
+### Hypothesise
+
+Form one or more hypotheses that explain the evidence. For each:
+
+- **Hypothesis:** What do you believe is the cause?
+- **Evidence for:** What observations support this?
+- **Evidence against:** What observations contradict this?
+- **Test:** What would confirm or disprove this hypothesis?
+
+Rank hypotheses by how well they explain ALL the evidence, not just part of it. Present them to the user with a recommendation.
+
+### Implement
+
+Once the root cause is confirmed (or the most likely hypothesis is agreed), propose and execute the fix:
+
+- Describe the fix and its expected effect
+- Identify any risks or side effects
+- Execute the fix
+- Verify the problem is resolved — check the same evidence that surfaced the problem
+
+Mark the investigation complete: `[PROJECT:COMPLETE] Investigation: {problem} — Root cause: {cause}, Fix: {what was done}`.
+
+If the fix reveals a deeper problem, create a new investigation task rather than expanding this one.
+
+## When to Use
+
+- "Why are we getting so many complaints about..."
+- "Something is wrong with the scheduling..."
+- "Costs are way over what we quoted..."
+- "The process isn't working..."
+- "I keep seeing the same problem with..."
+
+Do not use investigation mode for simple questions with obvious answers. If the user asks "why did invoice X fail?" and the answer is immediately clear from the data, just answer. Investigation mode is for problems that need digging.