kushi-agents 3.4.2 → 3.13.0

package/plugin/skills/pull-onenote/SKILL.md

@@ -1,82 +1,431 @@
 ---
 name: "pull-onenote"
-version: "2.1.0"
-description: "Pull OneNote evidence (snapshot: full page bodies; stream: page-edit events). WorkIQ-only per workspace auth policy — Graph OneNote is unreliable."
+version: "2.5.1"
+description: "Pull OneNote evidence (snapshot: full page bodies; stream: page-edit events). Browser-scrape (OneNote-for-Web via Playwright with persisted profile) is the PRIMARY capture path because it is the only mechanism that returns reliable, complete, verbatim page bodies in this tenant. WorkIQ remains the fallback when the browser auth profile expires (Conditional Access / MFA). Per-page retry registry persists both ID forms (browser webPageId + WorkIQ wdpartid) and tracks last_status across runs."
 ---
 
 # Skill: pull-onenote
 
+> **v3.8.0 contracts** — This skill operates under six HARD-rule doctrines:
+> - `verbatim-by-default.instructions.md` — full bodies by default; no preview-grade pulls accepted.
+> - `m365-id-registry.instructions.md` — discover-once / consume-deterministically (section IDs, dual page-id schema).
+> - `capture-learnings.instructions.md` — every fix/discovery is logged to `plugin/learnings/<source>.md`.
+> - `cleanup-on-resolution.instructions.md` — when a value resolves, all stale unavailable-markers are upgraded in the same turn.
+> - `run-reports.instructions.md` — every refresh writes a per-user report under `Evidence/<alias>/refresh-reports/`.
+> - `thoroughness-detector.instructions.md` — runtime detector + auto-retry + paste-prompt for any page where the primary path returns nothing or partial. The per-page retry registry IS this skill's thoroughness contract.
+
+> **Canonical evidence layout** (HARD, kushi v3.12.1+): all artifacts produced by this skill MUST be written under `<project>/Evidence/<alias>/<source>/{snapshot,stream,...}/` — sibling folders under `<project>/` (e.g. `<project>/<source>-context/`, `<project>/<source>/`, `<project>/_Weekly Summaries/`) are FORBIDDEN. See `evidence-layout-canonical.instructions.md`.
+
 Pulls **onenote** evidence in two shapes per `snapshot-vs-stream.instructions.md`:
 
-- **snapshot/** — full page bodies — one file per page with last-modified + author + verbatim body content
-- **stream/** — page-edit events with diff summary (created/modified/renamed/deleted)
+- **snapshot/** — full page bodies — one file per page with last-modified + verbatim body
+- **stream/** — page-edit events with diff summary
+
+## Tools (in order)
+
+1. **Playwright (browser-scrape, persisted profile)** — PRIMARY. Drives OneNote-for-Web to enumerate pages and read verbatim bodies via `#PageContentWrapper`. Profile lives at `~/.copilot/playwright-profile/onenote/` and is reused across runs. Implementation: `plugin/skills/pull-onenote/runner.mjs`.
+2. **WorkIQ** — FALLBACK only. Used when the Playwright profile is auth-expired (`auth-required`) and for the stream/edit-event source. Always cite `m365-id-registry` doctrine when invoking; never use as primary for body retrieval (proven non-deterministic).
+3. **Host (m365_*)** — not used (Graph `Notes.Read.All` denied admin consent in this tenant).
+
+## Canonical CLI invocations (do NOT re-derive — copy these exactly)
+
+These are the empirically validated invocations as of kushi v3.11.3. The runner has surprising defaults (visible browser by default, 60s timeout, preflight required) that can derail a run. Use these recipes; do not improvise flags.
+
+### Bootstrap (one-time per machine; ~3-5 days between runs as cookies expire)
+
+```pwsh
+cd C:\Usha\ISERepos\kushi
+node plugin/skills/pull-onenote/runner.mjs --bootstrap
+```
+
+Expected console flow (any deviation = defect):
+
+```
+[bootstrap] Step 1/2: Sign in to OneNote-for-Web. ...
+[bootstrap] Sign-in detected (OneNote chrome rendered).   ← MUST appear before Step 2/2
+[bootstrap] Step 2/2: Seeding SharePoint cookies at https://microsoft-my.sharepoint.com/
+[bootstrap] Step 2/2: Seeding SharePoint cookies at https://microsoft-my.sharepoint-df.com/
+[bootstrap] Both surfaces visited. Close the browser window when ready.
+[bootstrap] Profile saved at: ...
+```
+
+If `Sign-in detected` is missing → the v3.11.1-or-earlier `waitForURL` bug is back; the bootstrap is invalid; cookies are not minted; every subsequent scrape will return `auth-required`. Re-bootstrap with v3.11.2+.
+
+The visible Edge window stays open until you close it. Sign in fully, wait for OneNote to render, then close the window.
+
+### Scrape a section (production) — use the wrapper, not the bare runner
+
+The bare `runner.mjs` emits JSON to stdout only. The driver (PowerShell or agent) is then responsible for writing snapshot files, upserting the registry, and emitting a run report. That hand-rolled wiring is brittle (PowerShell's default `Out-File` mangles UTF-8 — NBSP becomes `┬á`) and almost always violates the canonical layout in [`snapshot-vs-stream.instructions.md`](../../instructions/snapshot-vs-stream.instructions.md).
+
+**HARD rule (kushi v3.11.5+):** drivers MUST call `write-snapshot.mjs`, which invokes the runner internally (child_process, no shell pipe), writes the snapshot in the canonical layout, upserts `m365Mutable.knownSections.<project>.one_pages[]`, and emits a run report. Never hand-write snapshot files from runner JSON.
+
+```pwsh
+cd C:\Usha\ISERepos\kushi
+$url = '<exact-section-url-from-m365-mutable.json#one_sectionWebUrl>'
+node plugin/skills/pull-onenote/write-snapshot.mjs `
+  --section-url $url `
+  --project "<project>" `
+  --engagement-root "<engagement-root>" `
+  --alias ushak
+```
+
+Output structure (per `snapshot-vs-stream.instructions.md`):
+
+```
+<engagement-root>/<project>/Evidence/<alias>/onenote/
+   snapshot/pages/<safe-title>.md       ← one file per page (HARD)
+   refresh-reports/<YYYYMMDD-HHMM>-onenote.md
+   stream/                              ← populated by WorkIQ stream pass (not by this wrapper)
+```
+
+The wrapper also writes back to `m365-mutable.json`:
+- `one_pages[]` — per-page retry registry (title, wdpartid, webPageId, lastModified, last_status, attempts, snapshot_path, captured_at)
+- `one_lastPullAt`, `one_lastPullRunStatus`, `one_lastPullKushiVersion`
+
+#### Bare runner (advanced — only when you need raw JSON)
+
+If you genuinely need the runner output without writing files (e.g. for diagnostics), call it directly — but DO NOT then pipe through PowerShell `Out-File` (UTF-8 corruption). Either use `node -e` to parse stdout in-process, or use the wrapper's `--json` mode to feed a pre-captured file written with `[IO.File]::WriteAllText` (always UTF-8).
+
+Flags the wrapper sets for you (all load-bearing):
+
+| Flag | Why required |
+|---|---|
+| `--skip-preflight` | Standalone preflight at `https://onenote.cloud.microsoft/` is unreliable post-bootstrap (OneNote SPA forces `prompt=select_account` even when SPO cookies are valid). The Doc.aspx URL uses different cookies and works fine. |
+| `--headless` | Without it, a visible browser opens — if the user accidentally closes it during scrape, run fails with `Target page, context or browser has been closed`. |
+| `--timeout 120000` | Default 60s is too short under tenant load. 120s is the empirical safety margin for sections up to ~25 pages. Override with `--timeout` on the wrapper. |
+
+### Diagnostics (when scrape produces `pages: []`)
+
+If the scrape returns `pages: []` with `runStatus: "partial"` and `error: "frame.waitForFunction: Timeout"`, the cause is almost always one of:
+
+1. **Single-page section regex mismatch** — fixed in v3.11.3. Verify runner is v3.11.3+.
+2. **Page-rail genuinely slow to render** — bump `--timeout` to 180000 and retry once.
+3. **Section URL stale** — re-run `recapture-section-url.mjs` (see C.1).
+
+Quick in-place diagnostic to see what aria-labels the page is actually emitting (drop this in `plugin/skills/pull-onenote/diag.mjs`, run from kushi root):
+
+```js
+import { chromium } from 'playwright';
+import os from 'os';
+import path from 'path';
+const ctx = await chromium.launchPersistentContext(
+  path.join(os.homedir(), '.copilot', 'playwright-profile', 'onenote'),
+  { headless: true, channel: 'msedge', viewport: { width: 1400, height: 900 } }
+);
+const page = ctx.pages()[0] || await ctx.newPage();
+await page.goto(process.argv[2], { timeout: 60000 });
+await page.waitForTimeout(60000);
+for (const f of page.frames()) {
+  try {
+    const labels = await f.evaluate(() =>
+      Array.from(document.querySelectorAll('[aria-label]'))
+        .map(n => n.getAttribute('aria-label'))
+        .filter(x => x && (x.includes('page') || x.includes('Page')))
+    );
+    if (labels.length) console.log(f.url().slice(0, 80), labels.slice(0, 40));
+  } catch (e) {}
+}
+await ctx.close();
+```
+
+Run: `node plugin/skills/pull-onenote/diag.mjs "<section-url>"`. If you see `, Page. Selected.` but not `, page N of M, Page.` → single-page section, runner must be v3.11.3+.
+
+## Empirical contract (what is true, validated 2026-05-13/14)
+
+These three facts are HARD-rule and supersede any earlier doctrine in this skill or in older learnings:
+
+1. **Browser-scrape via OneNote-for-Web is the only reliable verbatim-body path.** Tested against HCA on 2026-05-14: 16 of 16 pages captured (~120KB), vs WorkIQ's 1 of 18 (~7KB) on the same section minutes earlier. Browser-scrape uses the same SharePoint-resident OneNote canvas the user sees, so what it returns IS the page.
+2. **WorkIQ is non-deterministic for OneNote bodies and shall not be the primary path.** Same page returned a verbatim body and `BODY-NOT-EXPOSED` 6 minutes apart with no edits. WorkIQ is retained ONLY as the auth-degraded fallback (when the browser profile cannot complete sign-in) and as the source of stream/edit-event data.
+3. **The OneNote-for-Web `pageid` and the WorkIQ `wdpartid` are different identifiers.** Both must be persisted per page (`webPageId` for browser navigation; `wdpartid` for WorkIQ correlation and stream events). Neither alone is sufficient.
+
+## Pre-flight
+
+Before any retrieval, validate the Playwright profile and (only if used as fallback) the WorkIQ EULA.
+
+### A. Playwright profile (PRIMARY)
+
+```pwsh
+$prof = "$env:USERPROFILE\.copilot\playwright-profile\onenote"
+if (-not (Test-Path $prof)) {
+  Write-Host "[pull-onenote] Playwright profile not yet seeded."
+  Write-Host "[pull-onenote] Run plugin/skills/pull-onenote/runner.mjs --bootstrap once interactively to sign in."
+  # Skill MUST NOT fall through silently. Surface as run-report 'auth-required' on every pending page.
+}
+```
+
+**A.1 Browser channel — HARD rule (kushi v3.10.1+):** the runner MUST launch via Playwright's `channel: 'msedge'` (the user's installed Edge), NOT vanilla Playwright Chromium. The Microsoft tenant's Conditional Access policy denies vanilla Chromium with **"You can't get there from here — this application contains sensitive information and can only be accessed from devices or client applications that meet Microsoft management compliance policy"**. Edge is Intune-trusted; vanilla Chromium is not. This is codified in `runner.mjs` at `chromium.launchPersistentContext(...)`. If the user does not have Edge installed, the runner fails fast with a clear message — do not fall back to Chromium.
+
+**A.2 Two-surface bootstrap — HARD rule (kushi v3.10.1+, sign-in wait fixed in v3.11.2):** `runner.mjs --bootstrap` MUST visit BOTH cookie domains in sequence within the same persisted session:
+
+1. `https://onenote.cloud.microsoft/` — sign-in surface for OneNote-for-Web.
+2. `https://microsoft-my.sharepoint.com/` AND `https://microsoft-my.sharepoint-df.com/` — the actual SPO hosts where Doc.aspx URLs live.
+
+Cookie domains do not share between `*.cloud.microsoft` and `*.sharepoint(-df).com`. Signing into OneNote alone is insufficient — the runner's section URLs are SPO URLs and need separate cookies. The bootstrap script handles this automatically; do not modify the order.
+
+**HARD rule (kushi v3.11.2+ post-auth wait):** the bootstrap MUST wait for a real OneNote post-auth UI signal — NOT for the URL to match `onenote.cloud.microsoft` (which is a no-op because we just navigated TO that URL, collapsing the wait to ~0 ms). Required selector set:
+
+```
+[aria-label*="Account manager" i], [data-automationid="NotebookList"], button[aria-label*="notebook" i], iframe[src*="onenoteframe.aspx"]
+```
+
+These are the same selectors `preflightOneNoteWeb` uses. The bootstrap log MUST emit `Sign-in detected (OneNote chrome rendered).` between Step 1/2 and Step 2/2 — its absence is the defect signature of the v3.11.1-and-earlier bug (sign-in was silently skipped, and every subsequent scrape returned `auth-required` regardless of how thoroughly the user signed in). Same anti-pattern applies to any future bootstrap surface (SharePoint, Loop, M365 admin).
+
+**A.3 Profile reset on channel switch:** if migrating from a Chromium profile to Edge (or vice versa), delete `~/.copilot/playwright-profile/onenote/` first. Cookie/cache formats differ.
+
+**A.4 OneNote-for-Web reachability pre-flight — HARD rule (kushi v3.11.0+):** before navigating to any section URL, the runner MUST probe `https://onenote.cloud.microsoft/` and classify the end-state into exactly one of three buckets:
+
+| End-state | Detection | runStatus | Driver action |
+|---|---|---|---|
+| `ok` | Account chrome / notebook list / `onenoteframe.aspx` iframe rendered within `--preflight-timeout` (default 25s) | n/a (proceed) | Navigate to section URL as normal. |
+| `auth-required` | URL bounced to `login.microsoftonline.com` or `login.live.com` | `auth-required` | Same as today — surface in run report; next refresh re-attempts. |
+| `onenote-web-unavailable` | "Sorry, we ran into a problem" / "Something went wrong" / "We couldn't open" / "This notebook can't be opened" / "There was a problem" detected in any frame's body text, OR pre-flight timeout with no chrome rendered | `notebook-unavailable` | **Do NOT retry blindly.** Surface a clear diagnostic to the user with the recovery checklist below. Mark this run's pages `last_status: notebook-unavailable`. |
 
-Auth + retry + error logging per `auth-and-retry.instructions.md`. WorkIQ-only per `workiq-first.instructions.md`. Thoroughness per `evidence-thoroughness.instructions.md`; runtime detector + auto-retry + paste-prompt per `thoroughness-detector.instructions.md`. Citations per `citation-ledger.instructions.md`.
+The same three-way classification ALSO applies after navigating to the section URL — if OneNote-for-Web pops the "Sorry" dialog on the section page (rather than rendering the canvas), the runner emits `runStatus: notebook-unavailable`, NOT `auth-required`. The two are distinct failure modes and must be reported as such; conflating them sends the user down the wrong recovery path (re-bootstrap auth when the real fix is to recover the notebook).
 
-## Inputs
+**Standalone pre-flight CLI** (for scripts and gate drivers):
 
-- `<project>` — already-resolved project name.
-- `<alias>` — current contributor.
-- `<window>` — date range. For snapshot: ignored (always full re-fetch). For stream: `(from, to)`.
-- (read) `<engagement-root>/.project-evidence/m365/m365-mutable.json m365Mutable.knownSections.<project>` — pinned hints.
-- (read) `<engagement-root>/<project>/Evidence/<alias>/.settings.yml` — per-(project x user) overrides.
+```pwsh
+node plugin/skills/pull-onenote/runner.mjs --preflight
+# Exit 0 = ok, 4 = auth-required, 3 = onenote-web-unavailable, 1 = unexpected
+# stdout: { "preflight": { "ok": bool, "reason"?, "detail"? } }
+```
 
-## Resolution hints (pinned in mutable, query in this priority order)
+**Recovery checklist for `notebook-unavailable`** (surface verbatim to the user; do NOT auto-retry):
 
-1. `one_sectionFileId` — drive item ID of the project's section file (e.g. AGCO.one) — narrowest, use first
-2. `one_sectionName` — display name (typically `<Project>.one`)
-3. Project alias keyword search — last resort
+1. Hard-refresh `https://onenote.cloud.microsoft/` — if the root page shows the same error, the issue is service-side or notebook-side.
+2. Open the notebook in **OneNote desktop** and let it fully sync.
+3. If the notebook opens in desktop but not web, wait 10–15 minutes (web index lag) and retry.
+4. If the section specifically fails (root loads, section errors), re-capture `one_sectionWebUrl` from the address bar via `recapture-section-url.mjs` — the persisted URL may be stale or for a moved section.
+5. Only after the user can manually open the notebook in OneNote-for-Web, re-run the kushi pull.
 
-## Path cascade (HARD — per `auth-and-retry.instructions.md`)
+The runner detects the absence of valid cookies and the redirect to `login.microsoftonline.com`. When that happens:
 
-1. **WorkIQ** (only supported path here per `workiq-first.instructions.md` — workspace policy disables Graph `/me/onenote/*`):
-   - **Pre-flight**: `Get-Command workiq`. If missing → log `workiq-not-on-path` + ask user. Probe `workiq ask -q "ping"`; if EULA prompt → run `workiq accept-eula` once, retry.
-   - Then query with the **narrowest available** hint:
-     - Have `one_sectionFileId`? Query: `Get full page bodies from OneNote section with sectionFileId <id> modified between <start> and <end>`.
-     - Have `one_sectionName` only? Query: `Get full page bodies from OneNote section <section> in notebook <notebook> modified between <start> and <end>`.
-     - Neither? Query: `Find OneNote pages or sections that mention <project> or <project-aliases>. Return page titles, section names, last modified dates, and direct links.`
-2. Apply retry pattern (max 2 retries, 3s/6s backoff). Throttling → narrow scope once (sectionFileId if available), then stop.
-3. **Do NOT attempt Graph `/me/onenote/*`** — workspace policy: OneNote via Graph repeatedly fails 401 here. Record `graph-skipped-by-policy` if Graph is the only remaining option.
-4. If WorkIQ exhausts → write evidence file with `❌ all paths failed` marker and `next_step: ask user to paste page text from <section>`.
+- Mark every queued page in this run as `last_status: auth-required`.
+- Write a refresh-report entry naming the project and counting affected pages.
+- DO NOT re-attempt with WorkIQ for the body — WorkIQ has been empirically proven to make up the ratio with non-bodies. Instead, the next refresh re-attempts the browser path.
+- DO use WorkIQ for any stream-only items (page-edit events) — those don't depend on body retrieval.
 
-## Snapshot pass
+### B. WorkIQ EULA (FALLBACK)
 
-Write `snapshot/pages/<page-title>.md` per page with full verbatim body (NOT title only). Header: `Page: <title>` / `Section: <section>` / `Last modified: <ts> by <author>`.
+```pwsh
+workiq accept-eula  # idempotent; required once per machine for fallback queries
+```
 
-Write to: `<engagement-root>/<project>/Evidence/<alias>/OneNote/snapshot/<entity>.md`
+### C. Browser-URL completeness gate (HARD, kushi v3.10.0+)
 
-Use template: `templates/snapshot/onenote-<kind>.template.md`
+The Playwright runner navigates to `one_sectionWebUrl`. That URL is composed from FIVE registry fields, and ALL must be present and accurate:
 
-## Stream pass
+| Key | Source | Notes |
+|---|---|---|
+| `one_sectionName` | OneNote section file name | e.g. `AGCO.one` |
+| `one_sectionFileId` | `wd=target(<name>\|<GUID>/)` fragment | Same GUID as WorkIQ's `wdsectionfileid` |
+| `one_notebookSourceDoc` | `sourcedoc={<GUID>}` query param | Identifies the parent notebook |
+| `one_notebookSpoBaseUrl` | `<scheme>://<host>/personal/<upn>` segment | Tenant-specific |
+| `one_sectionWebUrl` | the canonical Doc.aspx URL | **MUST be user-pasted from address bar — see C.1** |
 
-Page-edit events for the window. Each event: page, edit type (created/modified/renamed), editor, timestamp, brief diff summary.
+**C.1 No-synthesis rule (HARD, kushi v3.10.2+):** `one_sectionWebUrl` MUST be the URL the user actually copied from OneNote-for-Web's address bar. There is NO reliable formula to synthesize it from the four sub-fields. Two formulas were tried and BOTH failed in production:
 
-Write to: `<engagement-root>/<project>/Evidence/<alias>/OneNote/stream/<YYYY-MM-DD>_onenote-stream.md` (date = Monday of the ISO week the events fall in).
+- `wd=target(<name>|<fileId>/)` → silent "Sorry, we ran into a problem" dialog.
+- `wd=target(/<name>/)` → silent "Sorry, we ran into a problem" dialog (even when this exact form works for sibling sections in the same notebook).
+
+OneNote's routing depends on internal session/tenant tokens we cannot reverse-engineer. Any URL constructed by string concatenation MUST be considered invalid. The recapture script's `tryAutoHeal()` may inherit notebook-level fields (`one_notebookSourceDoc`, `one_notebookSpoBaseUrl`, `one_notebookName`) from a sibling project sharing the same notebook — but it MUST fall through to the interactive paste prompt for the section URL itself.
+
+**C.2 Auto-heal scope:** `tryAutoHeal()` returns `{ stillNeedsPaste: true }` whenever the section URL is missing, even if all notebook fields were inherited. The gate driver MUST honor this signal and prompt for paste.
+
+**Rule:** A URL synthesized by template (i.e. one the user has not actually opened in a browser) is NOT acceptable. Common failure mode: an older bootstrap wrote `sharepoint-df.com` (dogfood) when the real tenant is `sharepoint.com`, or wrote a `sourcedoc` GUID that does not match the user's actual notebook. The result is OneNote-for-Web's silent error dialog "Sorry, we ran into a problem" — which the runner cannot distinguish from auth-required.
+
+**Gate:** Before dispatching the runner for a project, check completeness with:
+
+```pwsh
+node plugin/skills/pull-onenote/scripts/recapture-section-url.mjs `
+  --project <name> `
+  --engagement-root <engagement-root> `
+  --check
+```
+
+Exit 0 + `{"status":"ok"}` → proceed to Step A.
+Exit 1 + `{"status":"incomplete","missing":[...]}` → invoke recapture (interactive paste prompt):
+
+```pwsh
+node plugin/skills/pull-onenote/scripts/recapture-section-url.mjs `
+  --project <name> `
+  --engagement-root <engagement-root>
+```
+
+The script prompts the user to open OneNote-for-Web, click into the section, copy the address-bar URL, and paste it. It parses the URL, validates structure, and persists all five fields to `m365-mutable.json`. **This gate runs in BOTH bootstrap and refresh** — if a refresh discovers the gate is open, it MUST self-heal via this script before invoking the runner. This is NOT re-discovery (which is forbidden by `m365-id-registry.instructions.md`); it is a one-time backfill of pre-doctrine or stale registry fields, with the resolved IDs cached forever.
+
+If the user declines to paste a URL (script exits non-zero with no fields persisted), mark the OneNote source as `disabled: true, reason: section-url-not-captured` in `<project>/integrations.yml#boundaries.onenote`, log a refresh-report entry, and skip the runner. Do NOT fall back to WorkIQ-only — empirical proof shows WorkIQ returns BODY-NOT-EXPOSED for most pages.
+
+## Bootstrap discovery (one-time per project)
+
+For a project we have not pulled OneNote for before, capture into `m365-mutable.json#knownSections.<projectKey>`:
+
+| Key | Source | Example (HCA) |
+|---|---|---|
+| `one_sectionName` | OneNote section file name | `HCA.one` |
+| `one_sectionFileId` | OneNote-for-Web wd= URL fragment AND WorkIQ wdsectionfileid (they match) | `3d0ad388-fd6b-45a8-8619-60dd709b7ade` |
+| `one_notebookSourceDoc` | SharePoint sourcedoc GUID for the parent notebook | `2036c7b1-db1b-47fd-a14f-d8ee94ddd9bc` |
+| `one_notebookName` | OneNote notebook display name | `ISE Work` |
+| `one_notebookSpoBaseUrl` | the host segment of the SharePoint URL before `/_layouts/15/Doc.aspx` | `https://microsoft-my.sharepoint-df.com/personal/<upn>` |
+
+Discover by:
+
+1. Open OneNote-for-Web at `https://onenote.cloud.microsoft/`. Sign in.
+2. Open the project's notebook → click the project's section.
+3. Read the URL — it contains both `sourcedoc={<notebookSourceDoc>}` and `wd=target(<sectionName>|<sectionFileId>/...)`.
+4. Persist all five values to `m365-mutable.json` per `m365-id-registry.instructions.md`.
+
+If the section already exists in `knownSections.<projectKey>` from a prior WorkIQ run, only the browser-specific fields (`one_notebookSourceDoc`, `one_notebookName`, `one_notebookSpoBaseUrl`) need to be added. The `one_sectionFileId` is the same for both paths.
+
+## Step A — enumerate pages (browser, primary)
+
+The runner navigates to the section's deep-link URL and waits for the OneNote canvas to render inside the nested `ffc-onenote.officeapps.live.com/onenoteframe.aspx` frame. Page enumeration uses the accessibility tree and MUST handle BOTH aria-label formats (kushi v3.11.3+):
+
+| Section state | aria-label format | Parsed as |
+|---|---|---|
+| Multi-page | `<title>, page N of M, Page.` | `{ title, pos: N, total: M }` |
+| Single-page | `<title>, Page. Selected.` | `{ title, pos: 1, total: 1 }` |
+
+```js
+// runner.mjs excerpt (v3.11.3)
+const pages = await wac.evaluate(() => {
+  const out = [];
+  const seen = new Set();
+  for (const n of document.querySelectorAll('[aria-label]')) {
+    const label = n.getAttribute('aria-label') || '';
+    let m = label.match(/^(.*?), page (\d+) of (\d+), Page/);
+    if (m) {
+      const key = `${m[1]}|${m[2]}`;
+      if (!seen.has(key)) { seen.add(key); out.push({ title: m[1], pos: parseInt(m[2]), total: parseInt(m[3]) }); }
+      continue;
+    }
+    m = label.match(/^(.*?), Page\. Selected\./);
+    if (m) {
+      const key = `${m[1]}|1`;
+      if (!seen.has(key)) { seen.add(key); out.push({ title: m[1], pos: 1, total: 1 }); }
+    }
+  }
+  return out;
+});
+```
+
+**HARD rule (kushi v3.11.3+):** any aria-label-driven enumerator MUST handle the N=1 special-case format. Single-page sections do NOT render `, page N of M, Page.` — assuming they do is the defect signature `frame.waitForFunction: Timeout` with `pages: []` on a section that visibly has one page in the rail. Same anti-pattern applies to `waitForFunction` — its predicate must accept either format.
+
+This returns the canonical, ordered, complete page list as OneNote itself sees it — no SharePoint search-index residue.
+
+After clicking each page, the runner reads the URL to capture the `webPageId` from the `wd=target(...|<title>|<webPageId>/)` segment. Persist both `wdpartid` (from any prior WorkIQ enumeration, if available) and `webPageId` per entry.
+
+## Step B — fetch verbatim body (browser, primary)
+
+For each page, click its `aria-label` entry in the page rail, wait 2.5s for the canvas to settle, then:
+
+```js
+const body = await wac.evaluate(() => {
+  const node = document.querySelector('#PageContentWrapper')
+            || document.querySelector('.Page')
+            || document.querySelector('[role="main"]');
+  return node ? node.innerText : '';
+});
+```
+
+Acceptance check (HARD rule):
+
+- A captured body must contain at minimum the page title line and one non-whitespace non-toolbar paragraph.
+- A body shorter than 50 chars is acceptable IF the page genuinely is sparse (verify by visiting in OneNote desktop), otherwise mark `last_status: short-suspect` and retry next refresh.
+- If the page redirected to `login.microsoftonline.com` instead of rendering, mark `last_status: auth-required` and exit the run loop early — do not continue with stale auth.
+
+## Step B' — fallback: WorkIQ verbatim probe
+
+Used ONLY when:
+
+- The Playwright profile is absent on this machine, OR
+- The previous run hit auth-required and retry-cooldown has not elapsed (24h), OR
+- The user explicitly requests WorkIQ-only for diagnostic comparison.
+
+Canonical WorkIQ Step B query (the Nova-pattern):
+
+> Return the FULL readable content verbatim of the page titled `<title>` in my OneNote section `<one_sectionName>` in notebook `<one_notebookName>`. Do not summarize. Do not paraphrase. If the body is not exposed, say so explicitly with the literal phrase `BODY-NOT-EXPOSED` on its own line.
+
+Acceptance: real body OR literal `BODY-NOT-EXPOSED`. Anything else is rejected and counted as `last_status: workiq-degraded`.
+
+## Per-page retry registry (dual-ID schema)
+
+Persisted at `m365-mutable.json#knownSections.<projectKey>.one_pages[]`. Each entry:
+
+```json
+{
+  "title": "4/3 - HCA with Jay and Martin",
+  "wdpartid": "2233ac5a-007a-4b70-9d93-d6113f318ba3",
+  "webPageId": "78aac9b5-0629-4daa-ada3-f2436cb2381c",
+  "lastModified": "April 3rd",
+  "last_status": "captured",
+  "captured_via": "browser",
+  "attempts": 2,
+  "last_attempt_at": "2026-05-14T03:55:00Z",
+  "snapshot_path": "Evidence/ushak/onenote/snapshot/pages/4-3---HCA-with-Jay-and-Martin.md",
+  "captured_at": "2026-05-14T03:55:00Z"
+}
+```
+
+`last_status` is one of:
+
+| Status | Meaning | Next-run action |
+|---|---|---|
+| `captured` | Browser scrape returned full body | None unless `lastModified` advanced |
+| `user-pasted` | Human pasted body into snapshot file | Treat as captured; do not overwrite |
+| `auth-required` | Browser hit MFA / sign-in page | Retry browser; surface in run report |
+| `notebook-unavailable` | OneNote-for-Web error dialog ("Sorry, we ran into a problem" / "We couldn't open") instead of rendering — service- or notebook-side, NOT auth | Do NOT auto-retry. Surface recovery checklist (SKILL §A.4); next run re-checks pre-flight. |
+| `workiq-degraded` | Browser unavailable AND WorkIQ returned BODY-NOT-EXPOSED | Retry browser when profile valid again |
+| `BODY-NOT-EXPOSED` | WorkIQ-fallback explicitly returned the literal marker | Retry browser next run |
+| `short-suspect` | Body < 50 chars, may not be genuinely sparse | Verify in OneNote desktop, then retry |
+| `enumeration-only` | Page enumerated but Step B not yet attempted | Attempt Step B on next run |
+
+Retry doctrine: every refresh re-runs Step A and re-runs Step B for any page where `last_status NOT IN ('captured', 'user-pasted')`. Pages with `last_status='captured'` are re-fetched only if `lastModified` differs from the registry's last-known value.
+
+## Step C — stream events
+
+Stream still uses WorkIQ — page-edit events are surfaced through search-index activity, not through page bodies, and that surface IS deterministic. No change vs v2.5.0.
+
+## Snapshot file shape
+
+Front-matter (yaml) at top of every `snapshot/pages/<safe-title>.md`:
+
+```yaml
+---
+page_title:    "4/3 - HCA with Jay and Martin"
+section:       "HCA.one"
+notebook:      "ISE Work"
+section_id:    "3d0ad388-fd6b-45a8-8619-60dd709b7ade"
+wdpartid:      "2233ac5a-007a-4b70-9d93-d6113f318ba3"
+webPageId:     "78aac9b5-0629-4daa-ada3-f2436cb2381c"
+last_modified: "April 3rd"
+last_status:   "captured"
+captured_via:  "browser"
+attempts:      2
+last_attempt:  "2026-05-14T03:55:00Z"
+captured_at:   "2026-05-14T03:55:00Z"
+---
+```
 
-Use template: `templates/weekly/onenote-summary.template.md`
+Below the front-matter:
 
-If a week file already exists, MERGE (dedupe by event ID, append new events, keep existing).
+- IF `last_status` ∈ {`captured`, `user-pasted`}: a `## AI Narrative Summary` section (3+ paragraphs) AND a `## Body (verbatim)` section with the exact text the runner extracted (or the user pasted). NEVER paraphrase a captured body.
+- IF `last_status ∈ {auth-required, workiq-degraded, BODY-NOT-EXPOSED}`: an explicit unavailable-marker block, a `### next_step` block, and a metadata table. Do NOT fabricate body content from emails or chats.
+- IF `last_status == enumeration-only`: a transient marker only. Do NOT include any body content.
+- IF `last_status == short-suspect`: include whatever was captured plus an `### unconfirmed` note.
 
-## Mutable hints to upsert (during the run, not at the end)
+## Depth bar
 
-If discovered, immediately write to `m365Mutable.knownSections.<project>.<source>` with `discoveredOn` + `confidence`:
+For any captured page, the `## AI Narrative Summary` must be self-contained — the reader must not need to consult the verbatim body to understand what the page is about. Cover: meeting/topic, who participated, what was decided, what's open, dates referenced. No fabrication: nothing in the summary or verbatim body section may originate from sources outside the page itself.
 
-- `one_sectionFileId` — drive item ID of the project's section file
-- `one_sectionName` — display name
-- `one_sectionWebUrl` — direct link
+## Run report
 
-## Update run-log
+Every refresh writes `Evidence/<alias>/refresh-reports/<YYYY-MM-DD>-<HHMM>-onenote.md` with:
 
-After the pass:
-- `sources.onenote.last_run = now`
-- `sources.onenote.last_status = ok | partial | failed | skipped-auth`
-- `sources.onenote.watermark_to = now` (stream only; snapshot has no watermark)
-- `sources.onenote.items_pulled = <N>`
-- `sources.onenote.errors = [...]` per `auth-and-retry.instructions.md` schema
-- For each week touched, add to `weekly_files` index.
+- Total pages enumerated (browser-authoritative count)
+- Per-status counts (captured / auth-required / workiq-degraded / etc.)
+- List of pages whose `last_modified` advanced since prior run
+- Whether the runner exited early due to `auth-required`
+- Any short-suspect entries needing user verification
 
-## Stop conditions
 
-- Hint missing AND fuzzy resolution returns 0 candidates → ask user once, persist answer to mutable, continue.
-- Multiple plausible candidates → ask user to pick, persist answer.
-- All paths failed → write evidence file with `❌ all paths failed` + actionable `next_step`, log to run-log errors, continue with rest of run.