kushi-agents 4.4.4 → 4.8.0

package/README.md

@@ -92,6 +92,8 @@ The Evidence/ folder produced by every profile is a **stable public contract**
 | `fde-triage` | standard+ | n/a | 7-file FDE triage bundle at `Reports/triage/<YYYY-MM-DD>/`. File 07 merges across re-runs. |
 | `propose-ado` | **preview** | n/a | Read-only ADO update proposal from latest `_Consolidated/` → `ado-updates/<date>/proposed.md`. Safe to schedule. No ADO writes. |
 | `apply-ado` | **preview** | n/a | Gated apply skill. v0.1.0-preview is dry-mode only (writes `planned.jsonl`); real ADO PATCH/POST lands in v0.1.x. |
+| `vertex-link` | **preview** | n/a | One-time link of a kushi project to a vertex repo `<customer>/<initiative>` (multi-binding supported). Populates `kushi.yaml#vertex`. Re-run with `--reconfigure` to change. |
+| `emit-vertex` | **preview** | n/a | Render vertex-shaped artifacts from kushi Evidence/+State/ — weekly status, decisions, workshops, comms, living-doc diff proposals. Stages first, validates against vertex's own schemas, applies on demand. |
 
 See [Quickstart](https://gim-home.github.io/kushi/getting-started/quickstart/) for the full workflow.
 
@@ -151,6 +153,7 @@ Email is stream-only (emails ARE events). Every other source has both. `ask-proj
 |---|---|
 | 🚀 [Getting started](https://gim-home.github.io/kushi/getting-started/) | Install + quickstart — pick a target, run one `npx` command |
 | 💡 [Concepts](https://gim-home.github.io/kushi/concepts/) | Hosts, storage backends, snapshot vs stream, multi-user model |
+| 🤝 [Kushi with Vertex](docs/concepts/kushi-with-vertex.md) | Using kushi alongside the [vertex](https://github.com/commercial-software-engineering/vertex) shared note-taking platform — better weekly status, decisions, workshops, and comms |
 | 🛠️ [How-to guides](https://gim-home.github.io/kushi/how-to/) | Schedule refreshes, add contributors, switch backends, upgrade, uninstall |
 | 📖 [Reference](https://gim-home.github.io/kushi/reference/) | Verbs, CLI options, config files, path map, self-check |
 | 📋 [Changelog](CHANGELOG.md) | Release history |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "kushi-agents",
-  "version": "4.4.4",
-  "description": "Install Kushi — multi-source project evidence agent with snapshot+stream capture across Email, Teams, OneNote, SharePoint, Meetings, CRM, ADO. WorkIQ-only for M365 sources (Graph / m365_* FORBIDDEN as fallbacks; user-paste is first-class). Host-agnostic.",
+  "version": "4.8.0",
+  "description": "Install Kushi — multi-source project evidence agent with snapshot+stream capture across Email, Teams, OneNote, Loop, SharePoint, Meetings, CRM, ADO. WorkIQ-only for M365 sources (Graph / m365_* FORBIDDEN as fallbacks; user-paste is first-class). Host-agnostic.",
   "type": "module",
   "bin": {
     "kushi-agents": "./bin/cli.mjs"
@@ -41,11 +41,11 @@
   },
   "license": "MIT",
   "scripts": {
-    "test": "node --test src/check-workiq.test.mjs src/seed-config.test.mjs",
+    "test": "node --test src/check-workiq.test.mjs src/seed-config.test.mjs src/sanitize-workiq-input.test.mjs src/detect-vertex-repo.test.mjs src/vertex-validate.test.mjs src/emit-vertex.e2e.test.mjs src/config-root-resolve.test.mjs src/forbidden-workiq-phrasings.test.mjs",
     "smoke": "node scripts/smoke.mjs",
     "prepublishOnly": "npm test && npm run smoke"
   },
   "publishConfig": {
     "access": "public"
   }
-}
+}

package/plugin/agents/kushi.agent.md

@@ -1,6 +1,6 @@
 ---
 name: Kushi
-description: "Kushi — multi-source project evidence + Q&A agent. Snapshot + stream capture across Email, Teams, OneNote, SharePoint, Meetings, CRM, ADO; plus read-only natural-language Q&A over the captured evidence. WorkIQ-first for capture, citation-only for answers. Host-agnostic. USE WHEN the user says any of: PRODUCER VERBS — \"bootstrap a new project\", \"set up project evidence for <X>\", \"add me to project <X>\", \"add contributor to <X>\", \"refresh <X>\", \"do it all for <X>\", \"weekly extract for <X>\", \"regenerate state for <X>\", \"consolidate <X>\", \"status of <X>\"; OR Q&A — the message names a known project (any subfolder under the engagement root) AND asks a question about it (\"what is …\", \"what's the MACC for <X>\", \"who is the EM on <X>\", \"status of <X>\", \"summarize <X>\", \"what was decided about <X>\", \"what's in the deck for <X>\", \"what action items for <X>\", \"<project-name> + <topic>\")."
+description: "Kushi — multi-source project evidence + Q&A agent. Snapshot + stream capture across Email, Teams, OneNote, Loop, SharePoint, Meetings, CRM, ADO; plus read-only natural-language Q&A over the captured evidence. WorkIQ-first for capture, citation-only for answers. Host-agnostic. USE WHEN the user says any of: PRODUCER VERBS — \"bootstrap a new project\", \"set up project evidence for <X>\", \"add me to project <X>\", \"add contributor to <X>\", \"refresh <X>\", \"do it all for <X>\", \"weekly extract for <X>\", \"regenerate state for <X>\", \"consolidate <X>\", \"status of <X>\"; OR Q&A — the message names a known project (any subfolder under the engagement root) AND asks a question about it (\"what is …\", \"what's the MACC for <X>\", \"who is the EM on <X>\", \"status of <X>\", \"summarize <X>\", \"what was decided about <X>\", \"what's in the deck for <X>\", \"what action items for <X>\", \"<project-name> + <topic>\")."
 argument-hint: "Name a project (e.g. 'bootstrap HCA', 'refresh AGCO last 14 days', 'ask HCA what's the MACC?'). Kushi routes to the right verb prompt — never run `npx kushi-agents <verb>` in the terminal."
 tools:
   [vscode/vscodeAPI, execute/getTerminalOutput, execute/runInTerminal, read/readFile, read/terminalSelection, read/terminalLastCommand, agent, edit, search, web, browser, 'workiq/*', 'github/*']
@@ -8,7 +8,7 @@ tools:
 
 # @Kushi — Project Evidence Orchestrator
 
-Kushi is a multi-source evidence + state agentfor consulting / engineering engagements. It captures **snapshots** (current state of entities) and **streams** (timestamped events) from Email, Teams, OneNote, SharePoint, Meetings, CRM, and ADO, and renders an outcome-based **State** view.
+Kushi is a multi-source evidence + state agentfor consulting / engineering engagements. It captures **snapshots** (current state of entities) and **streams** (timestamped events) from Email, Teams, OneNote, Loop, SharePoint, Meetings, CRM, and ADO, and renders an outcome-based **State** view.
 
 ## Install profiles
 
@@ -16,7 +16,7 @@ Kushi ships in three profiles. The installed profile is recorded in `kushi-insta
 
 | Profile | What's installed | Verbs available |
 |---|---|---|
-| `core` | Aggregator only: `setup`, `pull-*`, `consolidate-evidence`, `aggregate-project`, `ask-project`, `project-status`, `self-check`, `intro` | `setup`, `aggregate`, `consolidate`, `status`, `pull`, `ask` |
+| `core` | Aggregator only: `setup`, `pull-*`, `consolidate-evidence`, `aggregate-project`, `ask-project`, `project-status`, `vertex-link`, `emit-vertex`, `self-check`, `intro` | `setup`, `aggregate`, `consolidate`, `status`, `pull`, `ask`, `vertex-link`, `emit-vertex` |
 | `standard` *(default)* | core + `bootstrap-project`, `refresh-project`, `fde-intake`, `fde-report`, `fde-triage` + FDE reference pack | core + `bootstrap`, `refresh`, `fde-intake`, `fde-report`, `fde-triage` |
 | `full` | standard + `build-state` | standard + `state` |
 | **`preview`** *(opt-in)* | standard + `propose-ado-update`, `apply-ado-update` | standard + `propose-ado`, `apply-ado` |
@@ -29,7 +29,7 @@ The Evidence/ folder produced by `aggregate` is the **public contract** between
 
 | Verb | Profile | Default window | Calls (in order) |
 |---|---|---|---|
-| `@Kushi setup` | core+ | n/a (read-only) | `setup` — functional WorkIQ ping + identity auto-fill. Idempotent; safe to re-run. Required before first bootstrap/refresh. |
+| `@Kushi setup` | core+ | n/a (read-only outbound) | `setup` — auto-EULA + functional WorkIQ ping + identity auto-fill + optional OneNote + multi-folder mailbox config + `projects_root` resolution + file-pointer footer. Idempotent; `--reconfigure` re-walks every question. Required before first bootstrap/refresh. See `instructions/identity-resolution.instructions.md` (v4.4.5 extension). |
 | `@Kushi aggregate <project>` | core+ | since last watermark | `aggregate-project` → `pull-*` (all enabled) → `consolidate-evidence`. **No build-state.** |
 | `@Kushi aggregate <project> last N days` / `since <date>` / `<from>..<to>` | core+ | as supplied | same |
 | `@Kushi bootstrap <project>` | standard+ | last 30 days | `bootstrap-project` → `pull-*` → `consolidate-evidence` → (full only) `build-state` |
@@ -40,6 +40,8 @@ The Evidence/ folder produced by `aggregate` is the **public contract** between
 | `@Kushi status <project>` | core+ | n/a | `project-status` — show run-log |
 | `@Kushi ask <project> <question>` | core+ | n/a (read-only) | `ask-project` — cited Q&A over Evidence/ (+ State/ on full) |
 | `@Kushi pull <source> for <project> [window]` | core+ | as supplied | one `pull-<source>` skill in isolation |
+| `@Kushi vertex-link <project>` | core+ | n/a (one-time mapping) | `vertex-link` — fuzzy-discovers a vertex repo, fuzzy-matches `<customer-slug>/<initiative-slug>/`, writes `kushi.yaml#vertex`. Idempotent; `--reconfigure` re-walks. |
+| `@Kushi emit-vertex <project> [--weekly\|--decisions\|--workshops\|--comms\|--living\|--all]` | core+ | weekly window for `--weekly`, else n/a | `emit-vertex` — renders vertex-shaped artifacts to `<project>/.kushi-staging/vertex/<run-ts>/`, validates via the linked vertex repo's `validate_frontmatter.py`, and (with `--apply`) copies into the vertex repo for GitDoc. Living docs become PR-style diff proposals. |
 | `@Kushi fde-intake <project>` | **standard+** | n/a (read-only) | `fde-intake` — author/update the FDE Intake document at `Reports/00-FDE-Intake-<project>.md` |
 | `@Kushi fde-report <project> [shape]` | **standard+** | n/a (read-only) | `fde-report` — one of 5 shapes: `weekly` (default) / `short` / `long` / `fitness` / `stage-readiness`. Output: `Reports/fde-<shape>-<YYYY-MM-DD>.md` |
 | `@Kushi fde-triage <project>` | **standard+** | n/a (read-only) | `fde-triage` — full 7-file triage bundle at `Reports/triage/<YYYY-MM-DD>/` |
@@ -65,14 +67,14 @@ See `instructions/snapshot-vs-stream.instructions.md` for the full rule.
 
 ## Core rules (apply to every skill)
 
-- **WorkIQ-only** (M365 sources) — `instructions/workiq-only.instructions.md` (supersedes the deprecated `workiq-first.instructions.md`). Email/Teams/OneNote/SharePoint/Meetings/Calendar-discovery are WorkIQ-only; Graph REST and `m365_*` host tools are FORBIDDEN as fallbacks. CRM/ADO remain on their direct REST paths.
+- **WorkIQ-only** (M365 sources) — `instructions/workiq-only.instructions.md` (supersedes the deprecated `workiq-only.instructions.md`). Email/Teams/OneNote/SharePoint/Meetings/Calendar-discovery are WorkIQ-only; Graph REST and `m365_*` host tools are FORBIDDEN as fallbacks. CRM/ADO remain on their direct REST paths.
 - **Canonical evidence layout** (v3.12.1+) — `instructions/evidence-layout-canonical.instructions.md`. Every per-source artifact lives under `<project>/Evidence/<alias>/<source>/{snapshot,stream,...}/`. Sibling source-output folders under `<project>/` (e.g. `<project>/email-context/`, `<project>/notes/`, `<project>/_Weekly Summaries/`) are FORBIDDEN; bootstrap/refresh auto-migrate them into `Evidence/<alias>/<source>/_legacy_*_pre-bootstrap/`.
 - **Scope & Boundaries** — `instructions/scope-boundaries.instructions.md`. Every WorkIQ ask, every `m365_*` call, every CRM/ADO probe MUST cite a boundary from `<engagement-root>/<project>/integrations.yml#boundaries.<source>`. Empty boundary = source disabled (no silent widening).
 - **Evidence Thoroughness Standard** — `instructions/evidence-thoroughness.instructions.md`
 - **Snapshot vs Stream** — `instructions/snapshot-vs-stream.instructions.md`
 - **Side-by-side config** (skeleton + live file always written together) — `instructions/side-by-side-config.instructions.md`
 - **Engagement-root resolution** — `instructions/engagement-root-resolution.instructions.md`
-- **Conditional `az login`** (skip if no CRM/ADO) — `instructions/az-auth-conditional.instructions.md`
+- **Conditional `az login`** (skip if no CRM/ADO) — `instructions/auth-and-retry.instructions.md`
 - **Auth pre-flight, retry, error logging** (mandatory before every external call) — `instructions/auth-and-retry.instructions.md`
 - **Citation Ledger** (every assertion cites source) — `instructions/citation-ledger.instructions.md`
 - **Answer-from-Evidence** (read-only Q&A doctrine for `ask-project`) — `instructions/answer-from-evidence.instructions.md`
@@ -88,7 +90,7 @@ When a user message arrives:
 
 1. Identify the **verb** (setup / aggregate / bootstrap / refresh / state / consolidate / status / pull / **ask** / fde-intake / fde-report / fde-triage).
    - If the message starts with an explicit producer verb → use it.
-   - **setup** dispatches immediately on `setup`, `verify workiq`, `who am I to kushi`, `fix my install`, `setup kushi`.
+   - **setup** dispatches immediately on `setup`, `setup --reconfigure`, `verify workiq`, `who am I to kushi`, `fix my install`, `setup kushi`.
    - Else if the message contains a known project name AND a question shape (interrogative, "status of", "summarize", bare `<project> <topic>`) → `ask`.
    - Else → ask the user to clarify.
 2. **Profile check**: confirm the chosen verb is listed in `kushi-install.json#verbs`. If not, surface: *"Verb `<verb>` requires the `<profile>` profile. Re-install with `npx kushi-agents --clawpilot --profile <profile> --force`."* and stop.
@@ -103,14 +105,23 @@ When a user message arrives:
 
 ## Configuration layout
 
+**Config root** is resolved by `Get-KushiConfig` / `loadKushiConfig`. Two install layouts are first-class (v4.7.2+):
+
+| Install command                         | `<kushi-config-root>`                    |
+|-----------------------------------------|------------------------------------------|
+| `npx kushi-agents` (vscode, default)    | `<workspace>/.kushi/config/`             |
+| `npx kushi-agents --clawpilot`          | `~/.copilot/m-skills/kushi/config/`      |
+
+> **Never** treat a missing `<workspace>/.kushi/` as "Kushi isn't installed"
+> and prompt the user to install or overwrite. Always probe via the helper —
+> the Clawpilot install lives outside the workspace. See
+> `instructions/kushi-config-root.instructions.md`.
+
 ```
-<workspace>/.kushi/config/user/project-evidence.yml     ← personal: alias, engagement_root, active_projects (seeded by installer; never overwritten)
-<workspace>/.kushi/config/shared/integrations.yml         ← optional global CRM/ADO defaults (seeded by installer; never overwritten)
-<workspace>/.kushi/config/                  ← per-machine, per-user M365 config + per-project shared ADO/CRM connection (v4.4.0+, replaces legacy `<engagement-root>/.project-evidence/`)
-   m365/m365-auth.json
-   m365/m365-mutable.json
-   crm/config.yml
-   ado/config.yml
+<kushi-config-root>/user/project-evidence.yml     ← personal: alias, engagement_root, active_projects (seeded by installer; never overwritten)
+<kushi-config-root>/shared/integrations.yml       ← optional global CRM/ADO defaults (seeded by installer; never overwritten)
+<kushi-config-root>/user/m365-auth.json           ← per-machine, per-user M365 config (v4.4.0+)
+<kushi-config-root>/user/m365-mutable.json
 <engagement-root>/<project>/integrations.yml       ← project-shared (all contributors)
 <engagement-root>/<project>/Evidence/contributors.yml
 <engagement-root>/<project>/Evidence/<alias>/.settings.yml ← per-(project × user)
@@ -143,6 +154,8 @@ Top-level orchestrator skills (called directly by verbs):
 | `fde-triage` | **standard+** | Read-only generator of the full 7-file FDE triage bundle. |
 | `propose-ado-update` | **preview** | Read-only generator of `ado-updates/<date>/proposed.md` for an ADO Initiative (FDE Status Summary field + Discussion comment). No ADO writes. Safe to schedule. |
 | `apply-ado-update` | **preview** | Gated apply skill — the only code path authorized to write to ADO. v0.1.0-preview is dry-mode only (writes `planned.jsonl`). Governed by `update-ledger.instructions.md`. |
+| `vertex-link` | core+ | One-time mapping of a kushi project to a vertex repo's `<customer-slug>/<initiative-slug>/`. Writes `kushi.yaml#vertex` with multi-binding support. |
+| `emit-vertex` | core+ | Renders vertex-shaped artifacts (status updates, decisions, workshops, comms; PR-style diffs for living docs) from `Evidence/`+`State/`. Stages then validates against the linked vertex repo's own `validate_frontmatter.py`. `--apply` copies into vertex repo; GitDoc handles commits. |
 
 Per-source pull skills (called by `bootstrap-project` / `refresh-project`, or directly via `pull <source>`):
 
@@ -152,8 +165,9 @@ Per-source pull skills (called by `bootstrap-project` / `refresh-project`, or di
 | `pull-teams` | Teams chats + channels | ✅ | ✅ |
 | `pull-meetings` | Calendar + transcripts | ✅ | ✅ |
 | `pull-onenote` | OneNote sections | ✅ | ✅ |
+| `pull-loop` | Microsoft Loop workspaces + pages | ✅ | ✅ |
 | `pull-sharepoint` | SharePoint / OneDrive | ✅ | ✅ |
-| `pull-misc` | User-curated `external-links.txt` (Loop, web, files, PDFs, GitHub) | ✅ | ✅ |
+| `pull-misc` | User-curated `external-links.txt` (web, files, PDFs, GitHub) | ✅ | ✅ |
 | `pull-crm` | Dataverse engagement record | ✅ | ✅ |
 | `pull-ado` | Azure DevOps work items | ✅ | ✅ |
 

package/plugin/config/studios.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "version": "1.0.0",
+  "description": "Studio registry for kushi. A 'studio' is an organizational unit that owns distribution lists, report recipients, and other per-org defaults. Borrowed shape from vertex/.vertex/scripts/studios.json (status_email namespace) and extended for kushi (report_recipients, fde_distro, brand).",
+  "studios": {
+    "_default": {
+      "display_name": "Default (no studio)",
+      "status_email": {
+        "automation_to": "",
+        "bcc_recipients": ""
+      },
+      "report_recipients": {
+        "fde_report_to": "",
+        "fde_report_cc": ""
+      },
+      "brand": {
+        "name": "",
+        "color_hex": ""
+      }
+    },
+    "studio-13": {
+      "display_name": "Studio 13",
+      "status_email": {
+        "automation_to": "\"Status Updates - Studio 13\" <status-updates-studio-13@microsoft.com>",
+        "bcc_recipients": "\"Americas Studio 13 LT\" <americas-studio-13-lt@microsoft.com>"
+      },
+      "report_recipients": {
+        "fde_report_to": "",
+        "fde_report_cc": ""
+      },
+      "brand": {
+        "name": "Studio 13",
+        "color_hex": ""
+      }
+    }
+  }
+}

package/plugin/config/studios.schema.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Kushi Studio Registry",
+  "type": "object",
+  "required": ["version", "studios"],
+  "properties": {
+    "version": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$" },
+    "description": { "type": "string" },
+    "studios": {
+      "type": "object",
+      "patternProperties": {
+        "^[a-z0-9][a-z0-9-]*$|^_default$": {
+          "type": "object",
+          "required": ["display_name"],
+          "properties": {
+            "display_name": { "type": "string" },
+            "status_email": {
+              "type": "object",
+              "properties": {
+                "automation_to": { "type": "string" },
+                "bcc_recipients": { "type": "string" }
+              }
+            },
+            "report_recipients": {
+              "type": "object",
+              "properties": {
+                "fde_report_to": { "type": "string" },
+                "fde_report_cc": { "type": "string" }
+              }
+            },
+            "brand": {
+              "type": "object",
+              "properties": {
+                "name": { "type": "string" },
+                "color_hex": { "type": "string", "pattern": "^(#[0-9a-fA-F]{6})?$" }
+              }
+            }
+          },
+          "additionalProperties": true
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/plugin/instructions/auth-and-retry.instructions.md

@@ -7,7 +7,7 @@ description: "Auth pre-flight, token reuse, retry, and structured error logging
 
 Every kushi skill that calls an external service (Graph / m365_*, WorkIQ, Dataverse / CRM, ADO, SharePoint) MUST follow this. Do not skip the pre-flight just because "auth probably works".
 
-> **See also:** `azure-auth-patterns.instructions.md` for concrete PowerShell patterns implementing this doctrine (token acquisition, host-specific SharePoint tokens, ADO tenant validation, `$LASTEXITCODE` discipline, WorkIQ retry code).
+> **See also:** `auth-and-retry.instructions.md` for concrete PowerShell patterns implementing this doctrine (token acquisition, host-specific SharePoint tokens, ADO tenant validation, `$LASTEXITCODE` discipline, WorkIQ retry code).
 
 ---
 
@@ -149,3 +149,270 @@ If a source is partially broken, the run summary table MUST display the status p
 | onenote | partial | 0 | Run `workiq accept-eula` once, then re-run `kushi pull onenote <project>` |
 | meetings | partial | 2 | Transcripts not generated for YYYY-MM-DD meetings; reconstructed from chat. To get transcripts on future meetings, enable Teams transcription before joining. |
 ```
+
+
+<!-- merged from auth-and-retry.instructions.md (v4.4.9) -->
+## Conditional az login (CRM/ADO only)
+
+The skill calls `az account get-access-token` only when CRM (Dataverse) or ADO are configured. WorkIQ does not require `az login`. Most M365-only users will never need to run `az login`.
+
+## Decision logic
+
+```
+crm_enabled = Test-Path <workspace>/.kushi/config/shared/integrations.yml
+ado_enabled = Test-Path <workspace>/.kushi/config/shared/integrations.yml
+
+if (NOT crm_enabled AND NOT ado_enabled):
+    Skip az check entirely. Display "az sign-in skipped (no CRM/ADO configured)".
+else:
+    Try `az account show` (no browser pop-up).
+    If signed-in: continue.
+    If NOT signed-in: prompt user with command suggestion (NOT auto-launch):
+        "az login --tenant 72f988bf-86f1-41af-91ab-2d7cd011db47"
+        After they sign in, re-run.
+    If signed-in but token request fails (403, etc.): SOFT WARNING.
+        - CRM/ADO sources will be skipped this run.
+        - All M365 sources via WorkIQ continue normally.
+        - Append a `## Auth Notes` section to the run summary listing what was skipped.
+```
+
+## Tenant ID
+
+The Microsoft tenant ID for ADO + CRM JIT auth is `72f988bf-86f1-41af-91ab-2d7cd011db47`. If you suggest `az login`, ALWAYS include `--tenant 72f988bf-86f1-41af-91ab-2d7cd011db47`.
+
+## Never block on az failures
+
+If `az login` fails or token acquisition fails:
+- Display the error.
+- Mark CRM/ADO sources as `❌ skipped (auth)` in the run summary.
+- CONTINUE the rest of the run. Never abort the whole bootstrap/refresh just because CRM is unreachable.
+
+<!-- merged from auth-and-retry.instructions.md (v4.4.9) -->
+## Concrete PowerShell patterns
+
+This file is the **concrete** companion to:
+
+- `auth-and-retry.instructions.md` — pre-flight, token reuse, retry, error-log schema, path cascade.
+- `auth-and-retry.instructions.md` — when to require `az login` (only if CRM/ADO are configured).
+- `workiq-only.instructions.md` — WorkIQ is the ONLY path for in-scope M365 sources (supersedes the deprecated `workiq-only.instructions.md`).
+
+Where those files describe **what** to do, this one shows **how** in PowerShell. Skill authors implementing `pull-crm`, `pull-ado`, `pull-sharepoint`, and any other external-service caller MUST follow the patterns here. Silent 401 loops and "no evidence found" misreports almost always come from skipping one of these.
+
+---
+
+## 1. Session pre-check (always run first)
+
+Before any token acquisition, verify the Azure CLI session and capture the active identity:
+
+```powershell
+$accountJson = az account show --output json --only-show-errors 2>&1
+if ($LASTEXITCODE -ne 0) {
+    throw "Azure CLI session not found. Run: az login --tenant 72f988bf-86f1-41af-91ab-2d7cd011db47"
+}
+$account = $accountJson | ConvertFrom-Json
+Write-Host "Active tenant: $($account.tenantId) | Account: $($account.user.name)"
+```
+
+Per `az-auth-conditional`: if neither CRM nor ADO is enabled for this engagement, **skip this entire section** and proceed directly to WorkIQ. M365-only users never need `az login`.
+
+---
+
+## 2. Token acquisition — per service
+
+Acquire each token **once per run** (per `auth-and-retry.instructions.md §2`). The tenant ID for Microsoft is `72f988bf-86f1-41af-91ab-2d7cd011db47` — pull it from config when possible, fall back to this literal only for the `az login --tenant` suggestion text.
+
+### 2.1 CRM / Dataverse
+
+```powershell
+$crmConfig   = (Get-Content "$workspace\.kushi\config\shared\integrations.yml" -Raw | ConvertFrom-Yaml).crm  # v4.4.0+ — was <engagement-root>\.project-evidence\crm\config.yml
+$tenant      = $crmConfig.tenantId
+$crmBaseUrl  = $crmConfig.baseUrl
+$crmToken    = (az account get-access-token --tenant $tenant --resource $crmBaseUrl --query accessToken -o tsv --only-show-errors 2>&1).Trim()
+if ($LASTEXITCODE -ne 0 -or [string]::IsNullOrWhiteSpace($crmToken)) {
+    throw "Failed to get CRM token (exit $LASTEXITCODE). Run: az login --tenant $tenant"
+}
+$crmHeaders = @{
+    Authorization      = "Bearer $crmToken"
+    Accept             = 'application/json'
+    'OData-Version'    = '4.0'
+    'OData-MaxVersion' = '4.0'
+    Prefer             = 'odata.include-annotations="OData.Community.Display.V1.FormattedValue"'
+}
+```
+
+### 2.2 Azure DevOps
+
+ADO's resource is the constant `499b84ac-1321-427f-aa17-267ca6975798` (Visual Studio Team Services). Read it from config — never hardcode:
+
+```powershell
+$adoConfig = (Get-Content "$workspace\.kushi\config\shared\integrations.yml" -Raw | ConvertFrom-Yaml).ado  # v4.4.0+ — was <engagement-root>\.project-evidence\ado\config.yml
+$tenant    = $adoConfig.tenantId
+$adoRes    = $adoConfig.resource   # 499b84ac-1321-427f-aa17-267ca6975798
+$adoToken  = (az account get-access-token --tenant $tenant --resource $adoRes --query accessToken -o tsv --only-show-errors 2>&1).Trim()
+if ($LASTEXITCODE -ne 0 -or [string]::IsNullOrWhiteSpace($adoToken)) {
+    throw "Failed to get ADO token (exit $LASTEXITCODE). Run: az login --tenant $tenant"
+}
+$adoHeaders = @{ Authorization = "Bearer $adoToken"; Accept = 'application/json'; 'Content-Type' = 'application/json' }
+```
+
+### 2.3 SharePoint / OneDrive — **host-specific** (critical)
+
+SharePoint tokens are bound to a hostname. **Do not assume the configured default host applies to every link.** Personal sites, customer tenants, and `*-df` preview hosts all need their own tokens.
+
+Derive the resource from the target URL's origin and acquire the token for that exact host:
+
+```powershell
+$targetUrl  = '<sharepoint-or-onedrive-url>'
+$targetUri  = [Uri]$targetUrl
+$spResource = "$($targetUri.Scheme)://$($targetUri.Host)"
+$spToken    = (az account get-access-token --tenant $tenant --resource $spResource --query accessToken -o tsv --only-show-errors 2>&1).Trim()
+if ($LASTEXITCODE -ne 0 -or [string]::IsNullOrWhiteSpace($spToken)) {
+    throw "Failed to get SharePoint token for host $spResource (exit $LASTEXITCODE). Run: az login --tenant $tenant"
+}
+$spHeaders = @{ Authorization = "Bearer $spToken"; Accept = 'application/json' }
+```
+
+Hosts commonly seen in this workspace: `microsoft-my.sharepoint.com`, `microsoft-my.sharepoint-df.com`, `microsofteur-my.sharepoint.com`, customer tenant `*.sharepoint.com`.
+
+#### SharePoint URL traps — browser vs. canonical API
+
+A raw browser-facing SharePoint URL is often the **wrong endpoint** for bearer-token retrieval:
+
+- `/_layouts/15/Doc.aspx?...`, `?web=1`, and Office share links (`/:x:/`, `/:p:/`, `/:w:/`, `/:b:/`) are browser shells or share URLs — **not** the canonical file-read API.
+- A raw `401` from those URLs does NOT prove Azure CLI auth is broken.
+- **For share links** → prefer Microsoft Graph `shares/{shareId}/driveItem` with `Prefer: redeemSharingLink`.
+- **For direct file paths** under `/personal/.../Documents/...` → prefer SharePoint REST `_api/web/GetFileByServerRelativePath(...)` on the exact host.
+- If the canonical API then returns `403 accessDenied` or SharePoint `UnauthorizedAccessException`, treat it as a **real permission / sharing problem** — do not chase it as a token-host mismatch. Record `errors[]` with `signature: blocked-host-or-permissions-401` per `auth-and-retry.instructions.md §4`.
+
+### 2.4 Microsoft Graph / `m365_*` proxies — narrow carve-outs ONLY
+
+**Do not use Microsoft Graph or `m365_*` host tools for in-scope M365 sources** (Email / Teams human-readable threads / OneNote bodies / SharePoint content / meeting transcripts / calendar discovery). Per `workiq-only.instructions.md` (v3.11.0+), these are WorkIQ-only. Graph / `m365_*` have a near-100% failure rate in this workspace and pollute the coverage trail.
+
+The ONLY allowed Graph / `m365_*` calls inside kushi pull-* skills are:
+
+1. **`m365_list_chat_messages(chatId)`** — parallel structured-data dump in `pull-teams` and `pull-meetings`. Writes `chat-messages.json`. Runs in parallel with the WorkIQ human-readable thread pull; NEVER a substitute. If it fails, the WorkIQ artifact still stands and the JSON dump is skipped.
+2. **`m365_download_file(itemId)`** for **binary media only** in `pull-meetings`: `recording.mp4` (when a SharePoint Stream URL is found and size < 200MB) and chat `attachments/<original-name>`. WorkIQ does not return binaries, so this carve-out is required for media survival.
+3. **CRM / ADO** — direct REST via Azure CLI tokens (sections 2.1 and 2.2 of this file). Out of WorkIQ scope.
+
+```powershell
+if (-not (Get-Command workiq -ErrorAction SilentlyContinue)) {
+    throw "workiq CLI not found on PATH. M365 source queries cannot proceed. See: https://gim-home.github.io/kushi/getting-started/install-workiq/"
+}
+# Prefer the canonical WorkIQ prompts codified in workiq-only.instructions.md.
+# Do NOT improvise. Do NOT fall back to m365_* for in-scope sources.
+```
+
+For the allowed carve-outs (`m365_list_chat_messages`, `m365_download_file` for binaries): no `az` token is needed — these go through the Clawpilot M365 proxy authenticated via `m_m365_status` / `m_m365_sign_in`.
+
+---
+
+## 3. ADO tenant validation (before any ADO call)
+
+Allowed tenants are config-driven, not hardcoded. Validate before the first ADO call:
+
+```powershell
+# $account from Section 1
+$adoConfig      = (Get-Content "$workspace\.kushi\config\shared\integrations.yml" -Raw | ConvertFrom-Yaml).ado  # v4.4.0+
+$allowedTenants = @($adoConfig.allowedTenantIds)
+$currentTenant  = $account.tenantId
+if ($allowedTenants.Count -gt 0 -and $allowedTenants -notcontains $currentTenant) {
+    throw "Current tenant '$currentTenant' is not allowed for ADO. Allowed: $($allowedTenants -join ', '). Run: az login --tenant $($allowedTenants[0])"
+}
+```
+
+If validation fails, record `errors[]` with `signature: ado-tenant-mismatch` and mark the ADO source `❌ skipped (auth)` per `auth-and-retry §4` — do not abort the whole run.
+
+---
+
+## 4. Mandatory $LASTEXITCODE pattern
+
+Check `$LASTEXITCODE` immediately after every `az` invocation. Never proceed with a null or empty result. Always pipe `2>&1` so stderr is captured into error messages, and use `--only-show-errors` on token calls to keep informational banners out of the token value:
+
+```powershell
+$result = az <command> --output json --only-show-errors 2>&1
+if ($LASTEXITCODE -ne 0) {
+    throw "az command failed (exit $LASTEXITCODE): $result"
+}
+```
+
+---
+
+## 5. WorkIQ availability + retry (concrete)
+
+Per `workiq-only.instructions.md` and `auth-and-retry.instructions.md §3`. Before the first WorkIQ call per run:
+
+```powershell
+if (-not (Get-Command workiq -ErrorAction SilentlyContinue)) {
+    throw "workiq CLI not found on PATH. WorkIQ queries cannot proceed. See install-workiq.md."
+}
+```
+
+Retry loop (transient errors only — throttling is NOT a retry case):
+
+```powershell
+$maxRetries = 2
+$attempt    = 0
+$output     = $null
+do {
+    $attempt++
+    $output = (workiq ask -q $query 2>&1 | Out-String).Trim()
+    $isTransient = ($LASTEXITCODE -ne 0) -or ($output -match '^(Error:\s+Unexpected error|Server error)')
+    $isThrottled = ($output -match 'tooManyRequests|More than 3 retries performed|high demand')
+    if ($isThrottled) {
+        # Do NOT retry the same query. Narrow once if possible, else record and continue.
+        throw "WorkIQ throttled — record 'throttled-tooManyRequests' and move on per auth-and-retry §3."
+    }
+    if (-not $isTransient) { break }
+    if ($attempt -gt $maxRetries) {
+        throw "WorkIQ failed after $attempt attempt(s): $output"
+    }
+    Start-Sleep -Seconds (3 * $attempt)
+} while ($true)
+```
+
+---
+
+## 6. Token reuse + mid-run 401 recovery
+
+Per `auth-and-retry §2`: acquire each token once, reuse it. On HTTP 401 mid-run, **re-acquire once** and retry the failed call. If still 401, record `errors[]` with `signature: token-401-after-reacquire` and stop calling that service.
+
+```powershell
+# Mid-run 401 — re-acquire then retry once
+$crmToken = (az account get-access-token --tenant $tenant --resource $crmBaseUrl --query accessToken -o tsv --only-show-errors 2>&1).Trim()
+$crmHeaders.Authorization = "Bearer $crmToken"
+# retry the failed call ONCE
+```
+
+---
+
+## 7. Failure signature reference
+
+Maintained alongside `auth-and-retry §3` (canonical) — quick lookup:
+
+| Symptom | Likely cause | Recovery |
+|---------|--------------|----------|
+| `az account show` non-zero | Not logged in | `az login --tenant 72f988bf-86f1-41af-91ab-2d7cd011db47` |
+| Token empty / whitespace | Expired session or parse issue | Re-login, re-acquire |
+| HTTP 401 on API call | Token expired mid-run | Re-acquire once (§6), retry once |
+| HTTP 401 on SharePoint URL | Token for wrong host | Re-acquire for exact URL origin (§2.3); if still 401, record `blocked-host-or-permissions-401` |
+| Browser SP URL 401, but Graph shares / SP REST 403 | Wrong retrieval surface; canonical API exposed real permission failure | Stop retrying browser URL; classify as share/permission problem |
+| OneNote via Graph 401/40001 | Wrong path | Switch to WorkIQ, narrowest query first (`one_sectionFileId`) |
+| ADO tenant mismatch | Wrong-tenant session | `az login --tenant <allowed>` (§3) |
+| Dataverse 400 OData | Invalid field / filter | Revert to known-good query; add filters one at a time |
+| WorkIQ exits non-zero (transient) | Server hiccup | Retry pattern (§5), max 2 retries |
+| WorkIQ `tooManyRequests` | Throttling | Narrow scope once; else record `throttled-tooManyRequests` and stop |
+| WorkIQ "Sorry, I can't" | Blocked/copyright | Record `skipped-blocked`, continue |
+
+---
+
+## 8. Config source of truth
+
+| Service | Config file (engagement-scoped) |
+|---------|---------------------------------|
+| Dynamics 365 / CRM | `<workspace>/.kushi/config/shared/integrations.yml` |
+| Azure DevOps | `<workspace>/.kushi/config/shared/integrations.yml` |
+| Microsoft Graph / M365 / OneNote | `<workspace>/.kushi/config/user/m365-mutable.json` + `<workspace>/.kushi/config/user/m365-auth.json` |
+| WorkIQ CLI path | `<workspace>/.kushi/config/user/project-evidence.yml` (workspace-scoped) |
+| Global integrations (optional) | `<workspace>/.kushi/config/shared/integrations.yml` |
+
+Always read tenant IDs, resource URLs, org URLs, and allowed-tenant lists from these files at the start of each run. **Never hardcode them in skills or prompts.** The only acceptable literal in instructions/prompts is the public Microsoft tenant ID `72f988bf-86f1-41af-91ab-2d7cd011db47` in the user-facing `az login --tenant ...` suggestion text.