kushi-agents 5.0.0 → 5.0.2

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

@@ -1,560 +1,212 @@
----
-name: "pull-onenote"
-version: "3.0.0"
-description: "v3.0.0 (kushi v4.9.0): Pull OneNote evidence as Comprehensive Structured Capture (CSC) blocks written to weekly/YYYY-MM-DD_onenote-csc.md. One block per page touched that week, upserted in _index/entities.yml. WorkIQ natural-language CSC prompts are the PRIMARY path (per workiq-onenote-query-shape.instructions.md). Playwright remains OPT-IN recovery-only fallback; its output now feeds CSC bullets (no snapshot/pages/<title>.md verbatim files). Per-page retry registry now lives as `low_signal`/`status` in `_index/entities.yml`. No snapshot/+stream/ split. Per-contributor _index/. See weekly-csc + comprehensive-structured-capture doctrines."
----
-
-# Skill: pull-onenote
-
-> **v3.0.0 contract change (kushi v4.9.0, 2026-05-26):** Output shape is now **weekly CSC** (`weekly/<YYYY-MM-DD>_onenote-csc.md` + `_index/entities.yml`). WorkIQ is still PRIMARY, Playwright is still OPT-IN recovery-only — but their outputs feed CSC bullets, not verbatim `snapshot/pages/<title>.md` files. The per-page retry registry now lives as `status` / `low_signal` rows in `_index/entities.yml`. See `weekly-csc.instructions.md` and `comprehensive-structured-capture.instructions.md`.
-
-> **v2.7.0 contract change (kushi v4.7.3, 2026-05-26):** Playwright is **demoted from PRIMARY to opt-in recovery-only fallback**. WorkIQ natural-language queries by display name are now the primary path. See `..\..\instructions\workiq-onenote-query-shape.instructions.md` for the working query shapes and the empirical record. The v3.8.0 pivot to Playwright-primary was driven by HCA body-retrieval rate (1/18 on 2026-05-14) — but per-page retry registries + multi-refresh accumulation close that gap without forcing every contributor onto Edge + Conditional Access + bootstrap-profile complexity.
-
-> **v4.9.0 contracts** — This skill operates under these HARD-rule doctrines:
-> - **`comprehensive-structured-capture.instructions.md`** — CSC block shape (canonical sections, bullets only, no prose).
-> - **`weekly-csc.instructions.md`** — weekly/ + _index/ writer contract; multi-user safety.
-> - `workiq-onenote-query-shape.instructions.md` — **PRIMARY**. The only working WorkIQ phrasings for OneNote. CSC canonical prompts adapt these query shapes per `workiq-only.instructions.md` § "CSC canonical prompts (kushi v4.9.0+)".
-> - `m365-id-registry.instructions.md` — discover-once / consume-deterministically (section IDs, dual page-id schema when both observed).
-> - `evidence-thoroughness.instructions.md` (v2.0.0) — per-source minimum bullet thresholds; `low_signal: true` flag.
-> - `citation-ledger.instructions.md` — citation format.
-> - `capture-learnings.instructions.md` — every fix/discovery is logged to `plugin/learnings/<source>.md`.
-> - `cleanup-on-resolution.instructions.md` — 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/`.
-> - `evidence-layout-canonical.instructions.md` — `weekly/` + `_index/` are canonical in v4.9.0+.
-> - ~~`verbatim-by-default.instructions.md`~~ (LEGACY — superseded by CSC).
-> - ~~`snapshot-vs-stream.instructions.md`~~ (LEGACY — superseded by weekly-csc).
-
-## v4.9.0 — Comprehensive Structured Capture (CSC) + weekly/ layout (HARD RULE; supersedes all snapshot/+stream/ guidance below)
-
-Per `comprehensive-structured-capture.instructions.md` and `weekly-csc.instructions.md`:
-
-- **Output target** (single file per source per ISO week):
-  `<engagement-root>/<project>/Evidence/<alias>/onenote/weekly/<YYYY-MM-DD>_onenote-csc.md`
-  where `<YYYY-MM-DD>` is the **Monday** of the ISO week the page was touched.
-  Empty weeks produce no file.
-
-- **Block shape (per page touched that week)**: one CSC block under `## <Page title> {#<entity-anchor>}` with canonical section order: Source basis → Coverage window → Last touched → Participants → Topics Discussed → Decisions → Dates & Numbers Shared → Action Items → Next Steps → Open Questions → Risks/Blockers/Dependencies → Customer Asks → Artifacts/Links → Coverage Notes. (Q&A and Who Said What omitted per CSC per-source applicability.) Bullets only — no prose paragraphs.
-
-- **Entity id (canonical for this source)**: `onenote://page/wdpartid=<id>` (preferred) or `onenote://page/webPageId=<id>`.
-
-- **WorkIQ prompts**: REPLACED by the CSC canonical prompts in `workiq-only.instructions.md` § "CSC canonical prompts (kushi v4.9.0+)". The Tier C per-page body prompt becomes the OneNote CSC per-page prompt. Do NOT use the v4.8 verbatim prompts.
-
-- **_index/entities.yml upsert** (per-contributor, per-source): on every write, upsert one row per page:
-  ```yaml
-  - id: 'onenote://page/wdpartid=<id>'
-    display_name: '<page title>'
-    entity_anchor: '<slug>'
-    latest_csc_file: 'weekly/<YYYY-MM-DD>_onenote-csc.md'
-    latest_csc_block_offset: <line>
-    last_touched: <ISO>
-    first_seen: <ISO>
-    weeks_touched: [<YYYY-MM-DD>, ...]
-    status: captured | body-not-exposed | unavailable | deferred  # was last_status pre-v4.9.0
-    low_signal: false | true   # set true when entity cannot meet evidence-thoroughness thresholds
-  ```
-  Path: `<engagement-root>/<project>/Evidence/<alias>/onenote/_index/entities.yml`.
-
-- **Idempotency**: same page, same week, two runs → REPLACE the block in place. Same page, different weeks → each week's file gets its own block.
-
-- **No body-fetch loop**: drop the AI Narrative Summary requirement and the dedicated verbatim `## Body (verbatim)` section. CSC bullets sourced directly from WorkIQ CSC output (or Playwright fallback output, rendered as CSC).
-
-- **Legacy `snapshot/` and `stream/` folders**: NOT written by this skill in v4.9.0. Pre-v4.9.0 folders (especially `snapshot/pages/<safe-title>.md`) on disk are left alone; readers fall back to them when `weekly/` is empty.
-
-### Source-specific notes (onenote)
-
-- WorkIQ Tier C per-page body prompt becomes the OneNote CSC per-page prompt (see `workiq-only.instructions.md` § CSC canonical prompts).
-- **KEEP Playwright as opt-in recovery-only fallback (unchanged)** — but its output now feeds CSC bullets, not `snapshot/pages/<title>.md` verbatim files. The runner produces structured page content that the skill renders into the canonical CSC block sections.
-- **Per-page retry registry stays** — but it now lives as `low_signal` / `status` fields in `_index/entities.yml` (not as a separate `one_pages[]` block). Pages that return `body-not-exposed` for ≥ 2 consecutive refreshes still escalate to Playwright when opted in.
-- **Drop `snapshot/pages/<safe-title>.md` write target.** All output goes to `weekly/<Monday>_onenote-csc.md`.
-
-Pulls **onenote** evidence in two shapes per `snapshot-vs-stream.instructions.md`:
-
-- **snapshot/** — full page bodies — one file per page with last-modified + verbatim body
-- **stream/** — page-edit events with diff summary
-
-## Tools (in order)
-
-1. **WorkIQ (natural-language by display name)** — **PRIMARY**. Use the approved query shapes from `workiq-onenote-query-shape.instructions.md`: one section per query, display names only, no enumeration verbs, no filter-syntax, no ID-lookup questions. Drives both section/page discovery and body retrieval. Pages that return `BODY-NOT-EXPOSED` are logged into `one_pages[].last_status` for retry on the next refresh — this multi-refresh accumulation is the thoroughness mechanism.
-2. **Playwright (browser-scrape, persisted profile)** — **OPT-IN RECOVERY-ONLY FALLBACK**. Only invoked when ALL of: (a) `m365Auth.oneNote.playwrightFallback: true`, (b) `one_pages[]` shows ≥ N pages with `last_status: BODY-NOT-EXPOSED` for ≥ 2 consecutive refreshes (N default 5, configurable via `m365-mutable.json#pullOnenote.playwrightThreshold`), (c) WorkIQ has been attempted in the current run. Profile lives at `~/.kushi/playwright-profile/onenote/`. Implementation: `plugin/skills/pull-onenote/runner.mjs`. See "Playwright fallback (optional)" section below.
-3. **Host (m365_*)** — not used (Graph `Notes.Read.All` denied admin consent in this tenant; also forbidden by kushi's WorkIQ-first doctrine).
-
-## Canonical CLI invocations
-
-### Primary path: WorkIQ natural-language (kushi v4.7.3+, default for all installs)
-
-Per `..\..\instructions\workiq-onenote-query-shape.instructions.md`. Resolves section IDs and pulls page bodies via display-name queries:
-
-```pwsh
-# Per-section discovery + page enumeration (also extracts wdpartid + wdsectionfileid from URL fragments):
-workiq ask -q "In the OneNote notebook '<NOTEBOOK DISPLAY NAME>', show me the pages in the section named '<SECTION DISPLAY NAME>'. Return a flat table with: page title, last modified, web URL. No commentary. Do not truncate."
-
-# Per-page body pull (one page at a time — narrow scope is mandatory):
-workiq ask -q "Open the OneNote page titled '<PAGE TITLE>' in section '<SECTION>' of notebook '<NOTEBOOK>'. Return the verbatim page body, no summary, no truncation."
-
-# Edit-event stream:
-workiq ask -q "Show me OneNote page edits in section '<SECTION>' of notebook '<NOTEBOOK>' since <ISO-DATE>. For each edit: page title, edited by, edited at, brief change summary."
-```
-
-Driver behavior:
-1. Run discovery query → parse `wdsectionfileid`, `wdpartid`, `sourcedoc` GUIDs out of the URL fragments in the response.
-2. Persist into `m365-mutable.json#knownSections.<projectKey>` per `m365-id-registry.instructions.md`. `webPageId` is left empty — it is only populated if/when Playwright fallback runs.
-3. For each enumerated page, run the body-pull query. Write snapshot files to the canonical layout. Populate `one_pages[].last_status`: `captured` on verbatim body return, `BODY-NOT-EXPOSED` on empty/partial, `workiq-degraded` on classified WorkIQ failure (per `fallback-status-reporting.instructions.md`).
-4. Pages with `BODY-NOT-EXPOSED` are surfaced in the run report and queued for retry on the next refresh. The per-page retry registry is the thoroughness mechanism — over multiple refreshes, transient non-determinism is absorbed.
-
-### Playwright fallback (OPT-IN, RECOVERY-ONLY — kushi v4.7.3+)
-
-**Do NOT bootstrap a Playwright profile on a fresh install.** This path exists only as a recovery valve for contributors whose WorkIQ body-retrieval rate stays poor across multiple refreshes. Enable explicitly:
-
-```jsonc
-// In <kushi-config-root>/user/m365-auth.json:
-"oneNote": {
-  "enabled": true,
-  "defaultNotebookName": "...",
-  "playwrightFallback": true            // OPT-IN — default false
-}
-```
-
-Once opted in, the driver auto-escalates to Playwright when `one_pages[]` shows ≥ N pages with `last_status: BODY-NOT-EXPOSED` for ≥ 2 consecutive refreshes (N default 5; configurable via `m365-mutable.json#pullOnenote.playwrightThreshold`). Until both thresholds are met, the driver MUST continue using WorkIQ. Never auto-bootstrap a profile — that is always a user-initiated action.
-
-The Playwright invocations below remain valid (cookie surfaces, channel requirements, preflight three-way classification are all empirically unchanged) — they are simply the **fallback** path now, not the default.
-
-These are the empirically validated invocations as of kushi v3.11.3 (still in force for the fallback path). 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 the Playwright profile (FALLBACK PATH ONLY — opt-in required)
-
-```pwsh
-cd <kushi-repo-root>
-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 <kushi-repo-root>
-$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 <your-alias>
-```
-
-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 + reframed 2026-05-26)
-
-These facts are HARD-rule and supersede any earlier doctrine in this skill or in older learnings:
-
-1. **WorkIQ natural-language by display name IS the primary, working path for OneNote.** Reframed v4.7.3 (2026-05-26) — see `..\..\instructions\workiq-onenote-query-shape.instructions.md`. The only WorkIQ phrasings that work are: (a) narrow, single-section-by-display-name discovery queries; (b) single-page-by-title body pulls; (c) section-scoped edit-event stream queries. Forbidden: enumeration verbs, structured-field filter syntax, ID-lookup questions, broad "list my notebooks" probes. Those all empirically fail (WorkIQ punts to Graph Explorer or routes to summary mode).
-2. **WorkIQ body retrieval is non-deterministic, BUT per-page retry registries close the gap over multiple refreshes.** The v3.8.0 pivot to Playwright was driven by HCA's 1-of-18 body-retrieval rate on 2026-05-14. That rate is the snapshot of one refresh — the retry registry (`one_pages[].last_status`) is the durable mechanism that accumulates captures across refreshes. A page that returns `BODY-NOT-EXPOSED` today is retried tomorrow; over 3-5 refreshes the cumulative capture rate converges. This is acceptable for engagement evidence (which is time-windowed, not real-time). Playwright remains as the opt-in recovery valve for contributors who need faster convergence and have accepted the Edge + Conditional Access + bootstrap complexity.
-3. **The OneNote-for-Web `pageid` and the WorkIQ `wdpartid` are different identifiers.** Both should be persisted per page when both are observed (`webPageId` for browser navigation; `wdpartid` for WorkIQ correlation and stream events). For WorkIQ-only operation, `wdpartid` alone is sufficient — `webPageId` is only populated if/when Playwright fallback runs.
-4. **Browser-scrape via OneNote-for-Web returns higher-fidelity verbatim bodies when it works** — tested against HCA on 2026-05-14: 16 of 16 pages captured (~120KB) in one run. This is why Playwright remains as the opt-in fallback. It is NOT the default because: (a) it requires Edge + Conditional Access compliance — not all contributors have that; (b) it requires a per-machine bootstrap that expires every 3-5 days; (c) most engagements do not need real-time full-fidelity capture — multi-refresh WorkIQ converges adequately.
-
-## 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\.kushi\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 `~/.kushi/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`. |
-
-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).
-
-**Standalone pre-flight CLI** (for scripts and gate drivers):
-
-```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"? } }
-```
-
-**Recovery checklist for `notebook-unavailable`** (surface verbatim to the user; do NOT auto-retry):
-
-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.
-
-The runner detects the absence of valid cookies and the redirect to `login.microsoftonline.com`. When that happens:
-
-- 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.
-
-### B. WorkIQ EULA (FALLBACK)
-
-```pwsh
-workiq accept-eula  # idempotent; required once per machine for fallback queries
-```
-
-### C. Browser-URL completeness gate (HARD, kushi v3.10.0+)
-
-The Playwright runner navigates to `one_sectionWebUrl`. That URL is composed from FIVE registry fields, and ALL must be present and accurate:
-
-| 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** |
-
-**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:
-
-- `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 (natural-language 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
-
-> **LEGACY (pre-v4.9.0).** Superseded by v4.9.0 weekly/ + CSC writer above. Page-edit events now surface as the `Last touched` line and Coverage Notes in the per-page CSC block. Kept for historical reference; not executed.
-
-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
-
-> **LEGACY (pre-v4.9.0).** Superseded by v4.9.0 weekly/ + CSC writer above. `snapshot/pages/<safe-title>.md` is no longer written; per-page content lands as a CSC block in `weekly/<Monday>_onenote-csc.md`. The page metadata previously kept in front-matter (page_title, section, wdpartid, webPageId, last_modified, last_status, captured_via, etc.) now lives as fields on the `_index/entities.yml` row for the page. Kept below for historical reference; not executed.
-
-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"
----
-```
-
-Below the front-matter:
-
-- 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.
-
-## Depth bar (per `evidence-thoroughness.instructions.md` v2.0.0)
-
-Per-source minimum bullet thresholds replace the v4.8 AI Narrative Summary depth bar. For OneNote pages: **≥ 10 material bullets, ≥ 4 sections populated** (must include Topics, Dates & Numbers or Decisions, Action Items or Next Steps, Artifacts).
-
-An entity that cannot meet the threshold is flagged `low_signal: true` in `_index/entities.yml` and rendered as heading + Coverage Notes only — do NOT pad.
-
-For pages with `status: body-not-exposed` / `unavailable` / `deferred`, the CSC block is the heading + `Source basis: <status>` + `Coverage Notes` explaining the failure mode + `_None surfaced._` for every other applicable section. Do NOT infer content from adjacent pages, emails, or chats.
-
-## Depth bar (legacy)
-
-> **LEGACY (pre-v4.9.0).** Superseded by the v4.9.0 depth bar above. Kept for historical reference.
-
-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.
-
-## Run report
-
-Every refresh writes `Evidence/<alias>/refresh-reports/<YYYY-MM-DD>-<HHMM>-onenote.md` with:
-
-- 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
-
-
+---
+name: "pull-onenote"
+version: "3.1.0"
+description: "USE WHEN refresh-project / bootstrap-project dispatches OneNote source AND project boundaries.onenote.section_ids list is non-empty, OR the user says \"pull OneNote for <X>\". DO NOT USE for global OneNote search or non-kushi note capture. Capability: pulls OneNote evidence as CSC blocks written to weekly/YYYY-MM-DD_onenote-csc.md, one block per page touched, upserted in _index/entities.yml. WorkIQ-primary; Playwright opt-in recovery-only fallback."
+---
+
+# Skill: pull-onenote
+
+> **v3.0.0 contract change (kushi v4.9.0, 2026-05-26):** Output shape is now **weekly CSC** (`weekly/<YYYY-MM-DD>_onenote-csc.md` + `_index/entities.yml`). WorkIQ is still PRIMARY, Playwright is still OPT-IN recovery-only — but their outputs feed CSC bullets, not verbatim `snapshot/pages/<title>.md` files. The per-page retry registry now lives as `status` / `low_signal` rows in `_index/entities.yml`. See `weekly-csc.instructions.md` and `comprehensive-structured-capture.instructions.md`.
+
+> **v2.7.0 contract change (kushi v4.7.3, 2026-05-26):** Playwright is **demoted from PRIMARY to opt-in recovery-only fallback**. WorkIQ natural-language queries by display name are now the primary path. See `..\..\instructions\workiq-onenote-query-shape.instructions.md` for the working query shapes and the empirical record. The v3.8.0 pivot to Playwright-primary was driven by HCA body-retrieval rate (1/18 on 2026-05-14) — but per-page retry registries + multi-refresh accumulation close that gap without forcing every contributor onto Edge + Conditional Access + bootstrap-profile complexity.
+
+> **v4.9.0 contracts** — This skill operates under these HARD-rule doctrines:
+> - **`comprehensive-structured-capture.instructions.md`** — CSC block shape (canonical sections, bullets only, no prose).
+> - **`weekly-csc.instructions.md`** — weekly/ + _index/ writer contract; multi-user safety.
+> - `workiq-onenote-query-shape.instructions.md` — **PRIMARY**. The only working WorkIQ phrasings for OneNote. CSC canonical prompts adapt these query shapes per `workiq-only.instructions.md` § "CSC canonical prompts (kushi v4.9.0+)".
+> - `m365-id-registry.instructions.md` — discover-once / consume-deterministically (section IDs, dual page-id schema when both observed).
+> - `evidence-thoroughness.instructions.md` (v2.0.0) — per-source minimum bullet thresholds; `low_signal: true` flag.
+> - `citation-ledger.instructions.md` — citation format.
+> - `capture-learnings.instructions.md` — every fix/discovery is logged to `plugin/learnings/<source>.md`.
+> - `cleanup-on-resolution.instructions.md` — 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/`.
+> - `evidence-layout-canonical.instructions.md` — `weekly/` + `_index/` are canonical in v4.9.0+.
+> - ~~`verbatim-by-default.instructions.md`~~ (LEGACY — superseded by CSC).
+> - ~~`snapshot-vs-stream.instructions.md`~~ (LEGACY — superseded by weekly-csc).
+
+## Gotchas
+
+- **Moved pages keep original wdsectionfileid** → if a section returns `page-body-unavailable` or zero `wdpartid` entries, the pages were authored elsewhere and moved. Open OneNote desktop, drag pages back into the target section, force-sync, retry.
+- **WorkIQ Tier C requires ONE page per call** — batching multiple pages into a single ask returns empty results or summary-mode refusal. Loop over pageIds, one WorkIQ call per page.
+- **Notebook-unavailable masquerades as auth-required** — OneNote-for-Web error dialogs ("Sorry, we ran into a problem") look like sign-in failures to the runner. Run `--preflight` first; the three-way classifier distinguishes `ok` / `auth-required` / `notebook-unavailable`. Never re-bootstrap auth for `notebook-unavailable`.
+- **Forbidden bulk-enumerate phrasings** — bulk "list my … notebooks", notebook-ID lookups, structured-field section searches, and `wdsectionfileid` filter syntax all route WorkIQ to summary mode or Graph Explorer. Only display-name content queries work. See `workiq-onenote-query-shape.instructions.md` for the canonical forbidden list.
+- **Conditional Access requires Edge channel for Playwright fallback** — if `playwrightFallback: true` and bootstrap runs on Chromium/Firefox, cookies mint but every scrape returns `auth-required`. Use `--channel msedge`. Cookie domains do NOT transfer between SPO surfaces — bootstrap MUST visit both `microsoft-my.sharepoint.com` AND `microsoft-my.sharepoint-df.com`.
+
+## v4.9.0 — Comprehensive Structured Capture (CSC) + weekly/ layout (HARD RULE; supersedes all snapshot/+stream/ guidance below)
+
+Per `comprehensive-structured-capture.instructions.md` and `weekly-csc.instructions.md`:
+
+- **Output target** (single file per source per ISO week):
+  `<engagement-root>/<project>/Evidence/<alias>/onenote/weekly/<YYYY-MM-DD>_onenote-csc.md`
+  where `<YYYY-MM-DD>` is the **Monday** of the ISO week the page was touched.
+  Empty weeks produce no file.
+
+- **Block shape (per page touched that week)**: one CSC block under `## <Page title> {#<entity-anchor>}` with canonical section order: Source basis → Coverage window → Last touched → Participants → Topics Discussed → Decisions → Dates & Numbers Shared → Action Items → Next Steps → Open Questions → Risks/Blockers/Dependencies → Customer Asks → Artifacts/Links → Coverage Notes. (Q&A and Who Said What omitted per CSC per-source applicability.) Bullets only — no prose paragraphs.
+
+- **Entity id (canonical for this source)**: `onenote://page/wdpartid=<id>` (preferred) or `onenote://page/webPageId=<id>`.
+
+- **WorkIQ prompts**: REPLACED by the CSC canonical prompts in `workiq-only.instructions.md` § "CSC canonical prompts (kushi v4.9.0+)". The Tier C per-page body prompt becomes the OneNote CSC per-page prompt. Do NOT use the v4.8 verbatim prompts.
+
+- **_index/entities.yml upsert** (per-contributor, per-source): on every write, upsert one row per page:
+  ```yaml
+  - id: 'onenote://page/wdpartid=<id>'
+    display_name: '<page title>'
+    entity_anchor: '<slug>'
+    latest_csc_file: 'weekly/<YYYY-MM-DD>_onenote-csc.md'
+    latest_csc_block_offset: <line>
+    last_touched: <ISO>
+    first_seen: <ISO>
+    weeks_touched: [<YYYY-MM-DD>, ...]
+    status: captured | body-not-exposed | unavailable | deferred  # was last_status pre-v4.9.0
+    low_signal: false | true   # set true when entity cannot meet evidence-thoroughness thresholds
+  ```
+  Path: `<engagement-root>/<project>/Evidence/<alias>/onenote/_index/entities.yml`.
+
+- **Idempotency**: same page, same week, two runs → REPLACE the block in place. Same page, different weeks → each week's file gets its own block.
+
+- **No body-fetch loop**: drop the AI Narrative Summary requirement and the dedicated verbatim `## Body (verbatim)` section. CSC bullets sourced directly from WorkIQ CSC output (or Playwright fallback output, rendered as CSC).
+
+- **Legacy `snapshot/` and `stream/` folders**: NOT written by this skill in v4.9.0. Pre-v4.9.0 folders (especially `snapshot/pages/<safe-title>.md`) on disk are left alone; readers fall back to them when `weekly/` is empty.
+
+### Source-specific notes (onenote)
+
+- WorkIQ Tier C per-page body prompt becomes the OneNote CSC per-page prompt (see `workiq-only.instructions.md` § CSC canonical prompts).
+- **KEEP Playwright as opt-in recovery-only fallback (unchanged)** — but its output now feeds CSC bullets, not `snapshot/pages/<title>.md` verbatim files. The runner produces structured page content that the skill renders into the canonical CSC block sections.
+- **Per-page retry registry stays** — but it now lives as `low_signal` / `status` fields in `_index/entities.yml` (not as a separate `one_pages[]` block). Pages that return `body-not-exposed` for ≥ 2 consecutive refreshes still escalate to Playwright when opted in.
+- **Drop `snapshot/pages/<safe-title>.md` write target.** All output goes to `weekly/<Monday>_onenote-csc.md`.
+
+Pulls **onenote** evidence in two shapes per `snapshot-vs-stream.instructions.md`:
+
+- **snapshot/** — full page bodies — one file per page with last-modified + verbatim body
+- **stream/** — page-edit events with diff summary
+
+## Tools (in order)
+
+1. **WorkIQ (natural-language by display name)** — **PRIMARY**. Use the approved query shapes from `workiq-onenote-query-shape.instructions.md`: one section per query, display names only, no enumeration verbs, no filter-syntax, no ID-lookup questions. Drives both section/page discovery and body retrieval. Pages that return `BODY-NOT-EXPOSED` are logged into `one_pages[].last_status` for retry on the next refresh — this multi-refresh accumulation is the thoroughness mechanism.
+2. **Playwright (browser-scrape, persisted profile)** — **OPT-IN RECOVERY-ONLY FALLBACK**. Only invoked when ALL of: (a) `m365Auth.oneNote.playwrightFallback: true`, (b) `one_pages[]` shows ≥ N pages with `last_status: BODY-NOT-EXPOSED` for ≥ 2 consecutive refreshes (N default 5, configurable via `m365-mutable.json#pullOnenote.playwrightThreshold`), (c) WorkIQ has been attempted in the current run. Profile lives at `~/.kushi/playwright-profile/onenote/`. Implementation: `plugin/skills/pull-onenote/runner.mjs`. See "Playwright fallback (optional)" section below.
+3. **Host (m365_*)** — not used (Graph `Notes.Read.All` denied admin consent in this tenant; also forbidden by kushi's WorkIQ-first doctrine).
+
+## Canonical CLI invocations
+
+### Primary path: WorkIQ natural-language (kushi v4.7.3+, default for all installs)
+
+Per `..\..\instructions\workiq-onenote-query-shape.instructions.md`. Resolves section IDs and pulls page bodies via display-name queries:
+
+```pwsh
+# Per-section discovery + page enumeration (also extracts wdpartid + wdsectionfileid from URL fragments):
+workiq ask -q "In the OneNote notebook '<NOTEBOOK DISPLAY NAME>', show me the pages in the section named '<SECTION DISPLAY NAME>'. Return a flat table with: page title, last modified, web URL. No commentary. Do not truncate."
+
+# Per-page body pull (one page at a time — narrow scope is mandatory):
+workiq ask -q "Open the OneNote page titled '<PAGE TITLE>' in section '<SECTION>' of notebook '<NOTEBOOK>'. Return the verbatim page body, no summary, no truncation."
+
+# Edit-event stream:
+workiq ask -q "Show me OneNote page edits in section '<SECTION>' of notebook '<NOTEBOOK>' since <ISO-DATE>. For each edit: page title, edited by, edited at, brief change summary."
+```
+
+Driver behavior:
+1. Run discovery query → parse `wdsectionfileid`, `wdpartid`, `sourcedoc` GUIDs out of the URL fragments in the response.
+2. Persist into `m365-mutable.json#knownSections.<projectKey>` per `m365-id-registry.instructions.md`. `webPageId` is left empty — it is only populated if/when Playwright fallback runs.
+3. For each enumerated page, run the body-pull query. Write snapshot files to the canonical layout. Populate `one_pages[].last_status`: `captured` on verbatim body return, `BODY-NOT-EXPOSED` on empty/partial, `workiq-degraded` on classified WorkIQ failure (per `fallback-status-reporting.instructions.md`).
+4. Pages with `BODY-NOT-EXPOSED` are surfaced in the run report and queued for retry on the next refresh. The per-page retry registry is the thoroughness mechanism — over multiple refreshes, transient non-determinism is absorbed.
+
+### Playwright fallback (OPT-IN, RECOVERY-ONLY — kushi v4.7.3+)
+
+**Do NOT bootstrap a Playwright profile on a fresh install.** This path exists only as a recovery valve for contributors whose WorkIQ body-retrieval rate stays poor across multiple refreshes. Enable explicitly:
+
+```jsonc
+// In <kushi-config-root>/user/m365-auth.json:
+"oneNote": {
+  "enabled": true,
+  "defaultNotebookName": "...",
+  "playwrightFallback": true            // OPT-IN — default false
+}
+```
+
+Once opted in, the driver auto-escalates to Playwright when `one_pages[]` shows ≥ N pages with `last_status: BODY-NOT-EXPOSED` for ≥ 2 consecutive refreshes (N default 5; configurable via `m365-mutable.json#pullOnenote.playwrightThreshold`). Until both thresholds are met, the driver MUST continue using WorkIQ. Never auto-bootstrap a profile — that is always a user-initiated action.
+
+The Playwright invocations below remain valid (cookie surfaces, channel requirements, preflight three-way classification are all empirically unchanged) — they are simply the **fallback** path now, not the default.
+
+These are the empirically validated invocations as of kushi v3.11.3 (still in force for the fallback path). 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.
+
+> **Load `references/playwright-fallback.md`** for the runner bootstrap procedure, the `write-snapshot.mjs` scrape wrapper, channel/cookie HARD rules, and diagnostics for `pages: []` runs. Load ONLY when the Playwright fallback gate (above) has tripped — do NOT preload on fresh installs.
+
+
+## Empirical contract + Pre-flight gates
+
+> **Load `references/preflight.md`** when constructing or debugging the pre-flight gate (Playwright profile check, OneNote-for-Web three-way reachability classifier, browser-URL completeness gate, no-synthesis rule).
+>
+> **Load `references/runtime-contract.md`** for the four HARD-rule empirical facts (WorkIQ-primary doctrine, non-determinism + retry registry, dual page-id schema, when browser-scrape wins).
+
+
+## Bootstrap discovery + Runner steps
+
+> **Load `references/runtime-contract.md`** for the one-time-per-project bootstrap discovery table, runner Step A (page enumeration), Step B (verbatim body fetch), Step B' (WorkIQ fallback), the per-page retry registry status enum, and the legacy `snapshot/pages/<title>.md` file shape (reader fallback only). Implementer-only — readers should not need this file.
+
+## Depth bar (per `evidence-thoroughness.instructions.md` v2.0.0)
+
+Per-source minimum bullet thresholds replace the v4.8 AI Narrative Summary depth bar. For OneNote pages: **≥ 10 material bullets, ≥ 4 sections populated** (must include Topics, Dates & Numbers or Decisions, Action Items or Next Steps, Artifacts).
+
+An entity that cannot meet the threshold is flagged `low_signal: true` in `_index/entities.yml` and rendered as heading + Coverage Notes only — do NOT pad.
+
+For pages with `status: body-not-exposed` / `unavailable` / `deferred`, the CSC block is the heading + `Source basis: <status>` + `Coverage Notes` explaining the failure mode + `_None surfaced._` for every other applicable section. Do NOT infer content from adjacent pages, emails, or chats.
+
+## Depth bar (legacy)
+
+> **LEGACY (pre-v4.9.0).** Superseded by the v4.9.0 depth bar above. Kept for historical reference.
+
+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.
+
+## Run report
+
+Every refresh writes `Evidence/<alias>/refresh-reports/<YYYY-MM-DD>-<HHMM>-onenote.md` with:
+
+- 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
+
+
 
 ## References (v4.4.7)
 
 - Name → ID resolution follows ..\..\instructions\fuzzy-disambiguation.instructions.md (universal fuzzy contract).
 - After this pull completes, the per-source verification gate runs: ..\..\instructions\per-source-verification-gate.instructions.md (retry once, then write FOLLOW-UPS.md).
-
-
-## Issue Recovery
-
-When this skill exposes a reusable defect (auth pattern, doctrine gap, layout mismatch), apply the [Issue Recovery Rule](../../instructions/issue-recovery.instructions.md): fix the smallest correct repo-owned artifact first, prefer durable fixes over per-run workarounds, then re-run the narrowest failed check. Do NOT use memory as a substitute for correcting the workflow surface.
-
-## Tools (v4.9.0 update)
-
-WorkIQ (PRIMARY) — use **CSC canonical prompts** from `workiq-only.instructions.md` § 'CSC canonical prompts (kushi v4.9.0+)'. The pre-v4.9.0 verbatim prompts are LEGACY (kept only for pull-meetings Half A). Playwright fallback unchanged in invocation, but its output is now rendered into CSC sections rather than written as a verbatim `snapshot/pages/<title>.md` file.
-
-## Changelog
-
-- **v3.0.0 (kushi v4.9.0, 2026-05-26)**: BREAKING. Output is now a single weekly CSC file per ISO week
-  (`weekly/<YYYY-MM-DD>_onenote-csc.md`) + per-contributor `_index/entities.yml`. `snapshot/pages/`
-  and `stream/` writes removed. WorkIQ prompts switched to CSC canonical prompts (Tier C per-page
-  body prompt becomes OneNote CSC per-page prompt). AI Narrative Summary requirement removed (CSC
-  bulleted sections carry the load). Per-page retry registry now lives as `low_signal` / `status`
-  fields in `_index/entities.yml`. Playwright fallback unchanged in invocation; output rendered as
-  CSC bullets, not verbatim file. Legacy snapshot/+stream/ folders left readable; no migration.
-- **v2.x.x**: prior snapshot/+stream/ + verbatim-by-default shape. See git history.
+
+
+## Issue Recovery
+
+When this skill exposes a reusable defect (auth pattern, doctrine gap, layout mismatch), apply the [Issue Recovery Rule](../../instructions/issue-recovery.instructions.md): fix the smallest correct repo-owned artifact first, prefer durable fixes over per-run workarounds, then re-run the narrowest failed check. Do NOT use memory as a substitute for correcting the workflow surface.
+
+## Tools (v4.9.0 update)
+
+WorkIQ (PRIMARY) — use **CSC canonical prompts** from `workiq-only.instructions.md` § 'CSC canonical prompts (kushi v4.9.0+)'. The pre-v4.9.0 verbatim prompts are LEGACY (kept only for pull-meetings Half A). Playwright fallback unchanged in invocation, but its output is now rendered into CSC sections rather than written as a verbatim `snapshot/pages/<title>.md` file.
+
+## Changelog
+
+## Changelog
+
+- **v3.1.0 (kushi v5.0.1, 2026-05-26)**: agentskills.io spec-compliance pass. Extracted Playwright
+  fallback (bootstrap, scrape wrapper, channel rules, diagnostics) → `references/playwright-fallback.md`;
+  pre-flight gates (three-way reachability classifier, browser-URL completeness gate) →
+  `references/preflight.md`; empirical contract + Step A/B/B'/C runner contract + legacy snapshot
+  file shape → `references/runtime-contract.md`. SKILL.md trimmed from 568 to ~200 lines. Behaviour
+  unchanged; load-on-trigger pointers added so readers pull only what each task needs. Added
+  `## Gotchas` block and `## Validation loop` per agentskills compliance doctrine.
+- **v3.0.0 (kushi v4.9.0, 2026-05-26)**: BREAKING. Output is now a single weekly CSC file per ISO week
+  (`weekly/<YYYY-MM-DD>_onenote-csc.md`) + per-contributor `_index/entities.yml`. `snapshot/pages/`
+  and `stream/` writes removed. WorkIQ prompts switched to CSC canonical prompts (Tier C per-page
+  body prompt becomes OneNote CSC per-page prompt). AI Narrative Summary requirement removed (CSC
+  bulleted sections carry the load). Per-page retry registry now lives as `low_signal` / `status`
+  fields in `_index/entities.yml`. Playwright fallback unchanged in invocation; output rendered as
+  CSC bullets, not verbatim file. Legacy snapshot/+stream/ folders left readable; no migration.
+- **v2.x.x**: prior snapshot/+stream/ + verbatim-by-default shape. See git history.
+
+## Validation loop
+
+After writing outputs:
+
+1. Run self-check targeted at this skill: `pwsh plugin/skills/self-check/run.ps1 -Targeted pull-onenote`
+2. If failures: fix and re-run the affected step (not the whole skill).
+3. Repeat until self-check exits 0.
+4. Only then update `run-log.yml` with success status.