kushi-agents 5.7.6 → 5.8.1

package/bin/cli.mjs

@@ -206,6 +206,8 @@ if (args.includes('--help') || args.includes('-h')) {
     --yes, -y           Skip the project-root check
     --no-settings       Skip .vscode/settings.json update (vscode workspace target only)
     --no-instructions   Skip .github/copilot-instructions.md merge   (vscode workspace target only)
+    --no-prompt         Skip the post-install m365-auth quickstart (3 fields that
+                        make 'kushi discover' fast). Also disabled by KUSHI_NO_PROMPT=1.
 
   WorkIQ (REQUIRED — Kushi cannot pull evidence without it):
     --with-workiq           Auto-install WorkIQ via winget (Windows) / brew (macOS)
@@ -281,6 +283,7 @@ if (wantsVscode || wantsAllHosts || wantsUninstall) {
     uninstall: wantsUninstall,
     profile: getFlag('--profile'),
     includeWorkspace: !args.includes('--no-workspace'),
+    noPrompt: args.includes('--no-prompt'),
   }).catch((err) => {
     console.error(`\n  ${err.message}\n`);
     process.exit(1);
@@ -300,6 +303,7 @@ if (wantsVscode || wantsAllHosts || wantsUninstall) {
     yes: args.includes('--yes') || args.includes('-y'),
     noSettings: args.includes('--no-settings'),
     noInstructions: args.includes('--no-instructions'),
+    noPrompt: args.includes('--no-prompt'),
     target,
     profile: getFlag('--profile'),
     withWorkiq: args.includes('--with-workiq'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kushi-agents",
-  "version": "5.7.6",
+  "version": "5.8.1",
   "description": "Install Kushi — multi-source project evidence agent with Comprehensive Structured Capture (CSC) into weekly-only files across Email, Teams, OneNote, Loop, SharePoint, Meetings, CRM, ADO. Meetings retain a sibling verbatim/ audit folder. WorkIQ-only for M365 sources (Graph / m365_* FORBIDDEN as fallbacks; user-paste is first-class). Host-agnostic.",
   "type": "module",
   "bin": {

package/plugin/learnings/cross-cutting.md

@@ -4,6 +4,42 @@ Newest on top. Format defined in [`README.md`](./README.md). Use this file when
 
 ---
 
+### 2026-05-29 — Bounded queries beat broad semantic search by 10×
+
+**Symptom**: Even after v5.7.6 (5 min timeouts + honest "WorkIQ buffers stdout" heartbeat copy), discover still hit 7 × `WORKIQ_TIMEOUT` for some users — 21+ minutes per run with zero results. The host (GitHub Copilot Chat in particular) couldn't wait that long and bailed out with "discover hung" before the runner even returned its envelope.
+
+**Root cause** (discovered while sketching v5.8.0): WorkIQ defaults to mailbox-wide / tenant-wide *semantic* search when given a free-text question like *"Find Outlook mail folders related to project X"*. With no folder list, no date window, and no notebook scope, it scans the entire mailbox/tenant via LLM-driven matching — which is unboundedly slow on large mailboxes. The config schema *already had* `emailContext.folders`, `dateFloor`, `includeSubfolders`, `oneNote.defaultNotebookName`, and `sharePointContext.localProjectsRoot` — but `discover.mjs` never read them. The runner built the same broad prompt for everyone, regardless of how much config the user had filled in.
+
+**Insight**: WorkIQ has two query modes, gated by how specific your prompt is.
+
+| Prompt shape                                       | Mode             | Wall time/source |
+|----------------------------------------------------|------------------|------------------|
+| "Find folders related to project X"                | semantic search  | 60–180s          |
+| "In folders ['1. FDE', '99. FDE Not Active'], find folders matching 'X' received after 2026-03-30" | Graph filter     | 5–15s            |
+
+The user has the data to write the bounded prompt. Until v5.8.0, the runner just didn't.
+
+**Fix shipped (v5.8.0, 2026-05-29)**:
+
+1. **`plugin/runners/lib/m365-auth.mjs`** — new helper. `loadM365Auth()` probes the Get-KushiConfig path order (workspace user → workspace shared → ~/.copilot/m-skills/... → runner-relative). `scopeForSource(m365Auth, source)` returns per-source hint object (folders/dateFloor for email; dateFloor + chat/channel toggle for teams; notebookName for onenote; localProjectsRoot for sharepoint; null for crm/ado which use integrations.yml).
+
+2. **`discover.mjs::buildPrompt`** rewritten to inject the scope. Email gets `Restrict your search to ONLY these Outlook mail folders: ...`, Teams gets `Constraints: only consider messages from 2026-03-30 onward`, OneNote gets `Restrict your search to OneNote notebook "ISE Work"`, etc. Empty scope → unscoped prompt (legacy fallback, non-breaking).
+
+3. **`bootstrap.mjs --lookback-days N`** + **`--interactive`** — first-time-setup ergonomics. Without these, users had to hand-edit `.kushi/config/user/m365-auth.json` and many never did. `--interactive` walks them through the 3 fields that matter (folders, dateFloor, notebook) in <30 seconds. `--lookback-days 60` is the one-flag scripted equivalent.
+
+4. **Templates updated** with concrete copy-paste examples — `m365-auth.example.json` now reads as a finished FDE-consultant config, not an abstract schema. `_alternative_examples` block shows the 3 most common mailbox layouts.
+
+**Doctrine**: When a runner builds a WorkIQ prompt, **read the config first**. Every field in `m365-auth.json` that constrains the search space should be reflected in the prompt. If the field is empty, document that the prompt will run unscoped — never silently fall through. If config exists but isn't being used, that's a bug equivalent to ignoring user input.
+
+**Test counts**: 293 → 302. New file: `plugin/runners/test/unit/discover-scope.test.mjs` (9 tests covering scope plumbing + sentinel stripping + disabled-in-config + log-line assertions).
+
+**Don't repeat**:
+- Don't ship a runner that ignores half its config schema.
+- Don't assume WorkIQ "isn't fast enough" without checking if the prompt is bounded — broadness, not transport latency, is usually the cost.
+- Don't make users hand-edit JSON for fields that meaningfully change perceived performance — provide an interactive path.
+
+---
+
 ### 2026-05-29 — WorkIQ stdout is fully-buffered through the Windows spawn chain
 
 **Symptom**: After v5.7.5 added intelligent heartbeats, user re-ran discover. Heartbeats showed `...waiting for first byte (10s/180s, no output yet)` for 170+ seconds, then `✗ TIMEOUT after 180045ms (received 0 bytes before kill)`. Yet running `workiq.cmd ask -q "..."` directly from PowerShell returned 4 emails in 29 seconds.

package/plugin/runners/bootstrap.mjs

@@ -28,20 +28,198 @@ import {
 import { writeAtomic, pathExists } from './lib/evidence.mjs';
 
 function parseArgs(argv) {
-  const args = { force: false, dryRun: false };
+  const args = { force: false, dryRun: false, lookbackDays: null, interactive: false };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === '--project') args.project = argv[++i];
     else if (a === '--alias') args.alias = argv[++i];
     else if (a === '--force') args.force = true;
     else if (a === '--dry-run') args.dryRun = true;
+    else if (a === '--lookback-days') args.lookbackDays = Number(argv[++i]);
+    else if (a === '--interactive' || a === '-i') args.interactive = true;
     else if (a === '--help' || a === '-h') args.help = true;
   }
   return args;
 }
 
 function help() {
-  return `Usage: node bootstrap.mjs --project <P> --alias <A> [--force] [--dry-run]`;
+  return [
+    'Usage: node bootstrap.mjs --project <P> --alias <A> [options]',
+    '',
+    'Options:',
+    '  --interactive       Prompt for the 3 fields that most affect discover speed',
+    '                      (email folders, look-back days, OneNote notebook) and',
+    '                      stamp them into .kushi/config/user/m365-auth.json. Non-',
+    '                      destructive: existing values are shown as defaults.',
+    '  --lookback-days N   Non-interactive: stamp dateFloor = today − N days into',
+    '                      emailContext / teamsChatContext / calendarContext.',
+    '                      Speeds up discover by ~10× because WorkIQ runs a Graph',
+    '                      filter instead of a mailbox-wide semantic search.',
+    '                      Recommended: 60–90.',
+    '  --force             Overwrite existing template files AND existing dateFloor.',
+    '  --dry-run           Print planned changes without writing.',
+  ].join('\n');
+}
+
+/** Compute ISO date string (YYYY-MM-DD) for today − N days, in local time. */
+function isoDateNDaysAgo(n) {
+  const d = new Date();
+  d.setDate(d.getDate() - n);
+  return d.toISOString().slice(0, 10);
+}
+
+/**
+ * Stamp a dateFloor (computed from --lookback-days) into the workspace's
+ * m365-auth.json under emailContext / teamsChatContext / calendarContext.
+ * Probes in Get-KushiConfig order: workspace .kushi/config/{user,shared}/.
+ * Non-destructive: skips fields that already have a non-empty, non-sentinel
+ * value unless --force is passed.
+ *
+ * @returns {Promise<{ updated: string|null, fields: string[], skipped: string[], reason?: string }>}
+ */
+async function stampDateFloor({ workspace, lookbackDays, force, dryRun }) {
+  const dateFloor = isoDateNDaysAgo(lookbackDays);
+  const candidates = [
+    path.join(workspace, '.kushi', 'config', 'user', 'm365-auth.json'),
+    path.join(workspace, '.kushi', 'config', 'shared', 'm365-auth.json'),
+  ];
+  let target = null;
+  for (const p of candidates) {
+    if (await pathExists(p)) { target = p; break; }
+  }
+  if (!target) {
+    return { updated: null, fields: [], skipped: [], reason: 'm365-auth-not-found' };
+  }
+  const txt = await fs.readFile(target, 'utf8');
+  let parsed;
+  try { parsed = JSON.parse(txt); } catch (e) {
+    return { updated: null, fields: [], skipped: [], reason: `parse-error: ${e.message}` };
+  }
+  parsed.m365Auth ??= {};
+  const ctxs = [
+    ['emailContext', parsed.m365Auth.emailContext ??= {}],
+    ['teamsChatContext', parsed.m365Auth.teamsChatContext ??= {}],
+    ['calendarContext', parsed.m365Auth.calendarContext ??= {}],
+  ];
+  const fields = [];
+  const skipped = [];
+  const isSentinel = (s) => !s || s === '<auto>' || /__FILL_ME_IN__/.test(s) || /^<[A-Za-z][^>]*>$/.test(s);
+  for (const [name, ctx] of ctxs) {
+    const cur = ctx.dateFloor;
+    if (!isSentinel(cur) && !force) { skipped.push(`${name}.dateFloor=${cur}`); continue; }
+    ctx.dateFloor = dateFloor;
+    fields.push(`${name}.dateFloor`);
+  }
+  if (!dryRun && fields.length > 0) {
+    await writeAtomic(target, JSON.stringify(parsed, null, 2) + '\n', { skipIfUnchanged: true });
+  }
+  return { updated: target, fields, skipped, dateFloor };
+}
+
+/**
+ * Interactive setup for the 3 fields that most affect discover speed.
+ * Prompts on stderr (TTY only). Reads workspace m365-auth.json, shows current
+ * values as defaults, writes back atomically. Re-running is safe: each prompt
+ * defaults to the current value, so pressing Enter keeps everything.
+ *
+ * Fields:
+ *   1. emailContext.folders        — comma-separated. Speeds up discover most.
+ *   2. lookback days → dateFloor   — number. Stamped into 3 contexts.
+ *   3. oneNote.defaultNotebookName — string. Defaults to "ISE Work".
+ *
+ * @returns {Promise<{ updated: string|null, fields: string[], reason?: string }>}
+ */
+async function interactiveSetup({ workspace, dryRun }) {
+  // TTY check — interactive only makes sense with a real terminal.
+  if (!process.stdin.isTTY || !process.stderr.isTTY) {
+    return { updated: null, fields: [], reason: 'not-a-tty (use --lookback-days for non-interactive)' };
+  }
+
+  const target = path.join(workspace, '.kushi', 'config', 'user', 'm365-auth.json');
+  if (!await pathExists(target)) {
+    return { updated: null, fields: [], reason: 'm365-auth-not-found' };
+  }
+  let parsed;
+  try { parsed = JSON.parse(await fs.readFile(target, 'utf8')); }
+  catch (e) { return { updated: null, fields: [], reason: `parse-error: ${e.message}` }; }
+  parsed.m365Auth ??= {};
+  const m = parsed.m365Auth;
+  m.emailContext ??= {};
+  m.teamsChatContext ??= {};
+  m.calendarContext ??= {};
+  m.oneNote ??= {};
+
+  const readline = await import('node:readline/promises');
+  const rl = readline.createInterface({ input: process.stdin, output: process.stderr, terminal: true });
+  const ask = async (q, def) => {
+    const ans = (await rl.question(`${q} ${def != null ? `[${def}]` : ''} > `)).trim();
+    return ans === '' ? def : ans;
+  };
+
+  const fields = [];
+  process.stderr.write('\n┌─ Kushi setup (3 prompts that make discover fast) ─\n');
+  process.stderr.write(`│ Editing: ${target}\n`);
+  process.stderr.write('│ Press Enter to keep the current value (shown in brackets).\n');
+  process.stderr.write('└──────────────────────────────────────────────────\n\n');
+
+  // 1. Email folders (REQUIRED for fast discover)
+  process.stderr.write('[1/3] Email folders to scope discover (REQUIRED for speed)\n');
+  process.stderr.write('      Examples: "1. FDE, 99. FDE Not Active"  (Microsoft FDE consultant)\n');
+  process.stderr.write('                "Inbox, Archive, Projects"     (generic)\n');
+  process.stderr.write('                "Inbox"                        (everything in inbox)\n');
+  const curFolders = Array.isArray(m.emailContext.folders) ? m.emailContext.folders.join(', ') : '';
+  const foldersAns = await ask('      Comma-separated folder names', curFolders || '(none — will scan whole mailbox, slow)');
+  if (foldersAns && foldersAns !== '(none — will scan whole mailbox, slow)') {
+    const arr = foldersAns.split(',').map(s => s.trim()).filter(Boolean);
+    m.emailContext.folders = arr;
+    if (m.emailContext.includeSubfolders == null) m.emailContext.includeSubfolders = true;
+    fields.push(`emailContext.folders=[${arr.join(', ')}]`);
+  }
+
+  // 2. Look-back days → dateFloor
+  process.stderr.write('\n[2/3] Look-back window (days back from today)\n');
+  process.stderr.write('      Stamps dateFloor into email/teams/calendar contexts.\n');
+  process.stderr.write('      Smaller = faster discover. Recommended: 60 (active) / 90 (setup).\n');
+  const curFloor = m.emailContext.dateFloor;
+  const defaultDays = curFloor && /^\d{4}-\d{2}-\d{2}$/.test(curFloor)
+    ? Math.max(1, Math.round((Date.now() - Date.parse(curFloor)) / 86400000))
+    : 60;
+  const daysAns = await ask('      Look-back days', defaultDays);
+  const days = Number(daysAns);
+  if (Number.isFinite(days) && days > 0 && days <= 3650) {
+    const floor = isoDateNDaysAgo(days);
+    m.emailContext.dateFloor = floor;
+    m.teamsChatContext.dateFloor = floor;
+    m.calendarContext.dateFloor = floor;
+    fields.push(`dateFloor=${floor} (${days} days)`);
+  } else {
+    process.stderr.write(`      ⚠ Invalid number "${daysAns}" — skipping dateFloor.\n`);
+  }
+
+  // 3. OneNote notebook
+  process.stderr.write('\n[3/3] OneNote notebook to scope discover (optional)\n');
+  process.stderr.write('      Default for Microsoft consultants: "ISE Work"\n');
+  const curNb = m.oneNote.defaultNotebookName || '';
+  const nbAns = await ask('      Notebook name', curNb || 'ISE Work');
+  if (nbAns && nbAns !== curNb) {
+    m.oneNote.defaultNotebookName = nbAns;
+    if (m.oneNote.enabled == null) m.oneNote.enabled = true;
+    fields.push(`oneNote.defaultNotebookName="${nbAns}"`);
+  }
+
+  rl.close();
+
+  if (fields.length === 0) {
+    process.stderr.write('\nNo changes.\n\n');
+    return { updated: null, fields: [], reason: 'no-changes' };
+  }
+  if (!dryRun) {
+    await writeAtomic(target, JSON.stringify(parsed, null, 2) + '\n', { skipIfUnchanged: true });
+  }
+  process.stderr.write(`\n✓ ${dryRun ? '[dry-run] would write' : 'wrote'} ${fields.length} field(s) to ${target}:\n`);
+  for (const f of fields) process.stderr.write(`    • ${f}\n`);
+  process.stderr.write('\n');
+  return { updated: target, fields };
 }
 
 function emit(obj) { process.stdout.write(JSON.stringify(obj) + '\n'); }
@@ -128,6 +306,27 @@ async function main() {
   await ensureFile(path.join(aliasRoot(args.project, args.alias), 'external-links.local.yml'), YAML.stringify({ links: [] }), { dryRun: args.dryRun, force: args.force, log });
   await ensureFile(path.join(aliasRoot(args.project, args.alias), '_ledger.yml'), YAML.stringify({ entries: {} }), { dryRun: args.dryRun, force: args.force, log });
 
+  // Optional: stamp dateFloor into workspace m365-auth.json (--lookback-days N).
+  // Workspace = current working directory (where the user runs bootstrap from).
+  let dateFloorReport = null;
+  if (Number.isFinite(args.lookbackDays) && args.lookbackDays > 0) {
+    dateFloorReport = await stampDateFloor({
+      workspace: process.cwd(),
+      lookbackDays: args.lookbackDays,
+      force: args.force,
+      dryRun: args.dryRun,
+    });
+  }
+
+  // Optional: interactive m365-auth setup (--interactive). Prompts on stderr.
+  let interactiveReport = null;
+  if (args.interactive) {
+    interactiveReport = await interactiveSetup({
+      workspace: process.cwd(),
+      dryRun: args.dryRun,
+    });
+  }
+
   emit({
     status: 'ok',
     project: root,
@@ -135,6 +334,8 @@ async function main() {
     created: log.created.map(p => path.relative(root, p) || '.'),
     existed: log.existed.map(p => path.relative(root, p) || '.'),
     dry_run: args.dryRun,
+    ...(dateFloorReport ? { date_floor: dateFloorReport } : {}),
+    ...(interactiveReport ? { interactive: interactiveReport } : {}),
   });
   return 0;
 }

package/plugin/runners/discover.mjs

@@ -20,6 +20,7 @@ import YAML from 'yaml';
 import { projectRoot, evidenceRoot, aliasRoot, projectSharedFile, userFile } from './lib/layout.mjs';
 import { writeAtomic, pathExists } from './lib/evidence.mjs';
 import { ask as workiqAsk, resolveWorkiqBin } from './lib/workiq.mjs';
+import { loadM365Auth, scopeForSource } from './lib/m365-auth.mjs';
 
 const ALL_SOURCES = ['email', 'teams', 'meetings', 'onenote', 'sharepoint', 'crm', 'ado'];
 
@@ -44,8 +45,18 @@ function help() {
 
 function emit(obj) { process.stdout.write(JSON.stringify(obj) + '\n'); }
 
+/** Compact one-line description of the active scope for the run-log header. */
+function describeScope(source, scope) {
+  if (!scope || scope.enabled === false) return null;
+  const parts = [];
+  if (source === 'email' && scope.folders?.length) parts.push(`${scope.folders.length} folder(s)`);
+  if (scope.dateFloor) parts.push(`from ${scope.dateFloor}`);
+  if (source === 'onenote' && scope.notebookName) parts.push(`notebook "${scope.notebookName}"`);
+  return parts.length ? 'scope: ' + parts.join(', ') : null;
+}
+
 /** Deterministic prompt — asks WorkIQ for CSC blocks per source. */
-function buildPrompt(source, projectName) {
+function buildPrompt(source, projectName, scope = null) {
   const intros = {
     email: `Find Outlook mail folders related to project "${projectName}".`,
     teams: `Find Microsoft Teams 1:1 and group chats related to project "${projectName}".`,
@@ -64,17 +75,57 @@ function buildPrompt(source, projectName) {
     crm: 'request_id, incident_number, title, confidence',
     ado: 'engagement_id, work_item_id, title, confidence',
   };
-  return [
-    intros[source],
-    '',
-    'Return ONLY a list of structured-capture blocks of the form:',
-    '> [block: discovery]',
-    `> source: ${source}`,
-    ...fields[source].split(', ').map(f => `> ${f.split(' ')[0]}: <value>`),
-    '',
-    'One block per match. No prose. No commentary. If you find nothing, return an empty response.',
-    'Skip low-confidence matches.',
-  ].join('\n');
+  const lines = [intros[source]];
+
+  // Inject scope hints from m365-auth.json. Bounded queries (folder list +
+  // date floor) let WorkIQ use Graph filters instead of mailbox-wide semantic
+  // search, typically dropping query time from 60–180s to 5–15s.
+  if (scope && scope.enabled !== false) {
+    if (source === 'email') {
+      if (Array.isArray(scope.folders) && scope.folders.length > 0) {
+        lines.push('');
+        lines.push('Restrict your search to ONLY these Outlook mail folders:');
+        for (const f of scope.folders) {
+          lines.push(`  • "${f}"${scope.includeSubfolders ? ' (and all subfolders)' : ''}`);
+        }
+        lines.push('Do NOT scan any other mailbox folders.');
+      }
+      if (scope.dateFloor) lines.push(`Only consider mail received on or after ${scope.dateFloor}.`);
+    } else if (source === 'teams') {
+      const conds = [];
+      if (scope.dateFloor) conds.push(`only consider messages from ${scope.dateFloor} onward`);
+      if (scope.includeChats === false) conds.push('skip 1:1/group chats; channel posts only');
+      if (scope.includeChannels === false) conds.push('skip channel posts; chats only');
+      if (conds.length) { lines.push(''); lines.push(`Constraints: ${conds.join('; ')}.`); }
+    } else if (source === 'meetings') {
+      if (scope.dateFloor) {
+        lines.push('');
+        lines.push(`Only consider meeting series with occurrences on or after ${scope.dateFloor}.`);
+      }
+    } else if (source === 'onenote') {
+      if (scope.notebookName) {
+        lines.push('');
+        lines.push(`Restrict your search to OneNote notebook "${scope.notebookName}".`);
+      }
+    } else if (source === 'sharepoint') {
+      if (scope.localProjectsRoot) {
+        lines.push('');
+        lines.push(`The user's local SharePoint sync root is "${scope.localProjectsRoot}". Match site URLs against subfolders if useful.`);
+      }
+    }
+  }
+
+  lines.push('');
+  lines.push('Return ONLY a list of structured-capture blocks of the form:');
+  lines.push('> [block: discovery]');
+  lines.push(`> source: ${source}`);
+  for (const f of fields[source].split(', ')) {
+    lines.push(`> ${f.split(' ')[0]}: <value>`);
+  }
+  lines.push('');
+  lines.push('One block per match. No prose. No commentary. If you find nothing, return an empty response.');
+  lines.push('Skip low-confidence matches.');
+  return lines.join('\n');
 }
 
 /** Pull discovery rows out of CSC blocks, scoped to source. */
@@ -201,12 +252,16 @@ async function main() {
   let boundsDirty = false;
   let integDirty = false;
 
-  // Stream per-source progress to stderr so users (and host watchdogs) see the runner is alive.
-  // stdout is reserved for the final JSON envelope. Heartbeat ticks every 10s during long
-  // workiq calls keep the runner visibly alive — Copilot Chat / Cursor watchdogs typically
-  // kill processes silent on output for 30–60s.
+  // Load m365-auth.json scope hints. Empty/missing config falls back to
+  // unscoped queries (legacy behavior, no breaking change).
+  const m365 = await loadM365Auth();
   const log = (msg) => process.stderr.write(`[discover] ${msg}\n`);
   log(`workiq: ${workiqBin}`);
+  if (m365.path) {
+    log(`m365-auth: ${m365.path}${m365.error ? ` (parse error: ${m365.error})` : ''}`);
+  } else {
+    log('m365-auth: not found — running unscoped queries (slower, broader)');
+  }
   log(`sources: ${sourcesToRun.join(', ')} (timeout ${args.timeoutMs}ms each)`);
 
   const total = sourcesToRun.length;
@@ -214,12 +269,19 @@ async function main() {
   let idx = 0;
   for (const source of sourcesToRun) {
     idx++;
-    const prompt = buildPrompt(source, path.basename(root));
+    const scope = scopeForSource(m365.config, source);
+    if (scope?.enabled === false) {
+      log(`[${idx}/${total}] ${source}: disabled in m365-auth.json — skipping`);
+      sourceResults.push({ source, asked: false, found: 0, accepted: [], skipped_reason: 'disabled-in-config' });
+      continue;
+    }
+    const prompt = buildPrompt(source, path.basename(root), scope);
     let rows = [];
     let asked = true;
     let skipReason = null;
     const t0 = Date.now();
-    log(`[${idx}/${total}] ${source}: querying workiq (${args.timeoutMs}ms budget)...`);
+    const scopeNote = describeScope(source, scope);
+    log(`[${idx}/${total}] ${source}: querying workiq (${args.timeoutMs}ms budget${scopeNote ? ', ' + scopeNote : ''})...`);
     const onHeartbeat = ({ elapsedMs, stdoutBytes }) => {
       const sec = Math.round(elapsedMs / 1000);
       const budget = Math.round(args.timeoutMs / 1000);

package/plugin/runners/lib/m365-auth.mjs

@@ -0,0 +1,112 @@
+// plugin/runners/lib/m365-auth.mjs
+// Load m365Auth config (shared/user/install probe order) and convert it into
+// per-source scope hints that runners inject into WorkIQ prompts.
+//
+// Why scope hints matter: WorkIQ defaults to mailbox-wide / tenant-wide semantic
+// search, which can take 60–180s per query. Anchoring queries to specific
+// folders (e.g. "1. FDE") and a date floor turns them into bounded Graph
+// filters and typically returns in 5–15s.
+
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Resolve and load m365-auth.json. Probe order matches Get-KushiConfig.ps1.
+ *
+ * @param {object} opts
+ * @param {string} [opts.workspace] - workspace root (default: cwd)
+ * @returns {Promise<{ config: object, path: string|null, error?: string }>}
+ *   `config` is the `m365Auth` sub-object (always defined, may be empty).
+ */
+export async function loadM365Auth({ workspace = process.cwd() } = {}) {
+  const home = process.env.USERPROFILE || process.env.HOME || '';
+  // Runner installs in <workspace>/.kushi/runners/lib/, so two levels up = .kushi/.
+  const runnerInstallRoot = path.resolve(__dirname, '..', '..');
+  const candidates = [
+    path.join(workspace, '.kushi', 'config', 'user', 'm365-auth.json'),
+    path.join(workspace, '.kushi', 'config', 'shared', 'm365-auth.json'),
+    path.join(home, '.copilot', 'm-skills', 'kushi', 'config', 'user', 'm365-auth.json'),
+    path.join(home, '.copilot', 'm-skills', 'kushi', 'config', 'shared', 'm365-auth.json'),
+    path.join(runnerInstallRoot, 'config', 'user', 'm365-auth.json'),
+    path.join(runnerInstallRoot, 'config', 'shared', 'm365-auth.json'),
+  ];
+  for (const p of candidates) {
+    try {
+      const txt = await fs.readFile(p, 'utf8');
+      const parsed = JSON.parse(txt);
+      return { config: parsed?.m365Auth || {}, path: p };
+    } catch (e) {
+      if (e.code === 'ENOENT') continue;
+      // Found but unparseable — return so callers can warn-and-fallback.
+      return { config: {}, path: p, error: e.message };
+    }
+  }
+  return { config: {}, path: null };
+}
+
+/**
+ * Build a per-source scope hint object from m365Auth config.
+ * Returns null when source is unscoped (crm, ado) — those use integrations.yml.
+ *
+ * Sentinels (`__FILL_ME_IN__`, `<...>`) are stripped from string fields.
+ */
+export function scopeForSource(m365Auth, source) {
+  if (!m365Auth || typeof m365Auth !== 'object') return null;
+  const cleanStr = (s) => (typeof s === 'string' && !looksLikeSentinel(s) ? s : null);
+  const cleanArr = (a) => (Array.isArray(a) ? a.map(cleanStr).filter(Boolean) : []);
+
+  switch (source) {
+    case 'email': {
+      const ec = m365Auth.emailContext || {};
+      if (ec.enabled === false) return { enabled: false };
+      return {
+        enabled: true,
+        folders: cleanArr(ec.folders),
+        includeSubfolders: ec.includeSubfolders !== false,
+        dateFloor: cleanStr(ec.dateFloor),
+      };
+    }
+    case 'teams': {
+      const tc = m365Auth.teamsChatContext || {};
+      if (tc.enabled === false) return { enabled: false };
+      return {
+        enabled: true,
+        dateFloor: cleanStr(tc.dateFloor),
+        includeChats: tc.scope?.includeChats !== false,
+        includeChannels: tc.scope?.includeChannels !== false,
+      };
+    }
+    case 'meetings': {
+      const cc = m365Auth.calendarContext || {};
+      if (cc.enabled === false) return { enabled: false };
+      return { enabled: true, dateFloor: cleanStr(cc.dateFloor) };
+    }
+    case 'onenote': {
+      const on = m365Auth.oneNote || {};
+      if (on.enabled === false) return { enabled: false };
+      return {
+        enabled: true,
+        notebookName: cleanStr(on.defaultNotebookName),
+        notebookId: cleanStr(on.defaultNotebookId),
+      };
+    }
+    case 'sharepoint': {
+      const sp = m365Auth.sharePointContext || {};
+      if (sp.enabled === false) return { enabled: false };
+      return { enabled: true, localProjectsRoot: cleanStr(sp.localProjectsRoot) };
+    }
+    default:
+      return null;
+  }
+}
+
+function looksLikeSentinel(s) {
+  if (!s) return true;
+  if (s === '<auto>') return true; // runtime-resolution marker, not a real value
+  if (/__FILL_ME_IN__/.test(s)) return true;
+  if (/^<[A-Za-z][^>]*>$/.test(s)) return true; // matches <TENANT_ID>, <ProjectA>, etc.
+  return false;
+}

package/plugin/runners/test/unit/discover-scope.test.mjs

@@ -0,0 +1,159 @@
+// plugin/runners/test/unit/discover-scope.test.mjs
+// v5.8.0 — assert that m365-auth.json scope hints flow into discover prompts.
+// Tightening prompts (folder list, dateFloor, notebook name) drops query time
+// from 60–180s to 5–15s by giving WorkIQ enough hints to run a bounded
+// Graph filter instead of a mailbox-wide semantic search.
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+import { loadM365Auth, scopeForSource } from '../../lib/m365-auth.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const RUNNER = path.resolve(__dirname, '..', '..', 'discover.mjs');
+const BOOTSTRAP = path.resolve(__dirname, '..', '..', 'bootstrap.mjs');
+
+async function makeWorkspaceWithM365(m365Json) {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'kushi-scope-'));
+  const cfgDir = path.join(tmp, '.kushi', 'config', 'user');
+  await fs.mkdir(cfgDir, { recursive: true });
+  await fs.writeFile(path.join(cfgDir, 'm365-auth.json'), JSON.stringify(m365Json, null, 2));
+  return tmp;
+}
+
+test('scopeForSource: email pulls folders + dateFloor + includeSubfolders', () => {
+  const m365 = {
+    emailContext: {
+      enabled: true,
+      folders: ['1. FDE', '99. FDE Not Active'],
+      includeSubfolders: true,
+      dateFloor: '2026-03-01',
+    },
+  };
+  const s = scopeForSource(m365, 'email');
+  assert.equal(s.enabled, true);
+  assert.deepEqual(s.folders, ['1. FDE', '99. FDE Not Active']);
+  assert.equal(s.includeSubfolders, true);
+  assert.equal(s.dateFloor, '2026-03-01');
+});
+
+test('scopeForSource: strips sentinel placeholders from folders + dateFloor', () => {
+  const m365 = {
+    emailContext: {
+      enabled: true,
+      folders: ['Inbox', '__FILL_ME_IN__', '<ProjectA>'],
+      dateFloor: '__FILL_ME_IN__',
+    },
+  };
+  const s = scopeForSource(m365, 'email');
+  assert.deepEqual(s.folders, ['Inbox'], 'sentinels removed');
+  assert.equal(s.dateFloor, null, 'sentinel dateFloor nulled');
+});
+
+test('scopeForSource: returns { enabled: false } when source disabled', () => {
+  assert.equal(scopeForSource({ emailContext: { enabled: false } }, 'email').enabled, false);
+  assert.equal(scopeForSource({ oneNote: { enabled: false } }, 'onenote').enabled, false);
+});
+
+test('scopeForSource: onenote + sharepoint + meetings + teams shapes', () => {
+  const m365 = {
+    oneNote: { enabled: true, defaultNotebookName: 'ISE Work', defaultNotebookId: '0-ABC123' },
+    sharePointContext: { enabled: true, localProjectsRoot: 'C:\\OneDrive\\Engagements' },
+    calendarContext: { enabled: true, dateFloor: '2026-03-01' },
+    teamsChatContext: {
+      enabled: true,
+      dateFloor: '2026-03-01',
+      scope: { includeChats: true, includeChannels: false },
+    },
+  };
+  assert.equal(scopeForSource(m365, 'onenote').notebookName, 'ISE Work');
+  assert.equal(scopeForSource(m365, 'onenote').notebookId, '0-ABC123');
+  assert.equal(scopeForSource(m365, 'sharepoint').localProjectsRoot, 'C:\\OneDrive\\Engagements');
+  assert.equal(scopeForSource(m365, 'meetings').dateFloor, '2026-03-01');
+  const t = scopeForSource(m365, 'teams');
+  assert.equal(t.dateFloor, '2026-03-01');
+  assert.equal(t.includeChats, true);
+  assert.equal(t.includeChannels, false);
+});
+
+test('scopeForSource: returns null for unscoped sources (crm, ado)', () => {
+  assert.equal(scopeForSource({}, 'crm'), null);
+  assert.equal(scopeForSource({}, 'ado'), null);
+});
+
+test('loadM365Auth: returns empty config + null path when no file present', async () => {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'kushi-scope-empty-'));
+  const r = await loadM365Auth({ workspace: tmp });
+  // Could find none, OR could fall through to ~/.copilot/m-skills/.../m365-auth.json
+  // if the developer has one. Either way, config must always be a dict.
+  assert.equal(typeof r.config, 'object');
+});
+
+test('loadM365Auth: reads workspace .kushi/config/user/m365-auth.json', async () => {
+  const tmp = await makeWorkspaceWithM365({
+    m365Auth: {
+      emailContext: { enabled: true, folders: ['1. FDE'] },
+    },
+  });
+  const r = await loadM365Auth({ workspace: tmp });
+  assert.deepEqual(r.config.emailContext.folders, ['1. FDE']);
+  assert.match(r.path, /m365-auth\.json$/);
+});
+
+test('discover: prompt includes folder list when emailContext.folders is configured', async () => {
+  const tmp = await makeWorkspaceWithM365({
+    m365Auth: {
+      emailContext: { enabled: true, folders: ['1. FDE', '99. FDE Not Active'], includeSubfolders: true, dateFloor: '2026-03-01' },
+    },
+  });
+  // Bootstrap a project inside tmp so discover finds it.
+  const bs = spawnSync(process.execPath, [BOOTSTRAP, '--project', 'scope-proj', '--alias', 'alice'], { cwd: tmp, encoding: 'utf8' });
+  assert.equal(bs.status, 0, bs.stderr);
+
+  // Use a shim that echoes the exact prompt back so we can inspect it.
+  const shim = path.join(tmp, process.platform === 'win32' ? 'echo-shim.cmd' : 'echo-shim');
+  const shimBody = process.platform === 'win32'
+    ? '@echo off\r\necho.\r\nexit /b 0\r\n' // empty stdout is fine; we only check stderr [discover] log
+    : '#!/bin/sh\necho ""\nexit 0\n';
+  await fs.writeFile(shim, shimBody);
+  if (process.platform !== 'win32') await fs.chmod(shim, 0o755);
+
+  const r = spawnSync(process.execPath, [RUNNER, '--project', 'scope-proj', '--alias', 'alice', '--source', 'email'], {
+    cwd: tmp, encoding: 'utf8', env: { ...process.env, KUSHI_WORKIQ_BIN: shim },
+  });
+  assert.equal(r.status, 0, r.stderr);
+  // The [discover] log must announce that m365-auth was found AND show scope summary.
+  assert.match(r.stderr, /m365-auth: .*m365-auth\.json/, `expected m365-auth path in log, got: ${r.stderr}`);
+  assert.match(r.stderr, /scope:.*2 folder\(s\).*from 2026-03-01/,
+    `expected scope summary in log, got: ${r.stderr}`);
+});
+
+test('discover: source is skipped when m365-auth.json sets enabled=false', async () => {
+  const tmp = await makeWorkspaceWithM365({
+    m365Auth: { emailContext: { enabled: false } },
+  });
+  const bs = spawnSync(process.execPath, [BOOTSTRAP, '--project', 'disabled-proj', '--alias', 'alice'], { cwd: tmp, encoding: 'utf8' });
+  assert.equal(bs.status, 0, bs.stderr);
+
+  const shim = path.join(tmp, process.platform === 'win32' ? 'should-not-call.cmd' : 'should-not-call');
+  const shimBody = process.platform === 'win32'
+    ? '@echo off\r\necho FAIL_SHOULD_NOT_BE_CALLED 1>&2\r\nexit /b 99\r\n'
+    : '#!/bin/sh\necho FAIL_SHOULD_NOT_BE_CALLED >&2\nexit 99\n';
+  await fs.writeFile(shim, shimBody);
+  if (process.platform !== 'win32') await fs.chmod(shim, 0o755);
+
+  const r = spawnSync(process.execPath, [RUNNER, '--project', 'disabled-proj', '--alias', 'alice', '--source', 'email'], {
+    cwd: tmp, encoding: 'utf8', env: { ...process.env, KUSHI_WORKIQ_BIN: shim },
+  });
+  assert.equal(r.status, 0, r.stderr);
+  const lastLine = r.stdout.trim().split('\n').filter(Boolean).pop();
+  const json = JSON.parse(lastLine);
+  assert.equal(json.sources[0].skipped_reason, 'disabled-in-config');
+  assert.equal(json.sources[0].asked, false);
+  assert.doesNotMatch(r.stderr, /FAIL_SHOULD_NOT_BE_CALLED/, 'shim must not have been called');
+});

package/plugin/skills/bootstrap-project/SKILL.md

@@ -11,10 +11,33 @@ Delegates to the deterministic scaffold runner **`plugin/runners/bootstrap.mjs`*
 ## Invoke
 
 ```
-node plugin/runners/bootstrap.mjs --project <P> --alias <A> [--force] [--dry-run]
+node plugin/runners/bootstrap.mjs --project <P> --alias <A> [--interactive] [--lookback-days N] [--force] [--dry-run]
 ```
 
-Stdout JSON: `{ status, project, alias, created[], existed[] }`. Idempotent — re-runs report `existed[]` and write nothing.
+Stdout JSON: `{ status, project, alias, created[], existed[], date_floor?, interactive? }`. Idempotent — re-runs report `existed[]` and write nothing.
+
+### `--interactive` (recommended for first-time users)
+
+Prompts the user for the 3 fields that most affect discover speed:
+1. **Email folders** — comma-separated. Inline FDE-style examples shown.
+2. **Look-back days** — numeric. Stamped as `dateFloor` into email/teams/calendar contexts.
+3. **OneNote notebook name** — defaults to `"ISE Work"` for Microsoft consultants.
+
+Prompts on stderr (TTY only). Existing values are shown as defaults — pressing Enter keeps them. Refuses if not running in a TTY (use `--lookback-days` instead for non-interactive flows).
+
+### `--lookback-days N` (non-interactive equivalent)
+
+Stamps `dateFloor = today − N days` into the workspace's `m365-auth.json` under `emailContext`, `teamsChatContext`, and `calendarContext`. With a date floor set, WorkIQ runs a bounded Microsoft Graph filter (5–15s/source) instead of a mailbox-wide semantic search (60–180s/source). Recommended values: `60` for active engagements, `90` for setup/triage, `30` for tight focus.
+
+Non-destructive: skips fields that already have a non-empty, non-sentinel `dateFloor` unless `--force` is also passed. The flag has no effect if `.kushi/config/user/m365-auth.json` does not exist (the `date_floor.reason` field will say `m365-auth-not-found`).
+
+```
+# Interactive (first-time setup, recommended):
+node plugin/runners/bootstrap.mjs --project "C:\...\hca" --alias ushak --interactive
+
+# Non-interactive (CI / scripted):
+node plugin/runners/bootstrap.mjs --project "C:\...\hca" --alias ushak --lookback-days 60
+```
 
 ## What gets scaffolded
 

package/plugin/templates/init/m365-auth.example.json

@@ -1,56 +1,88 @@
-{
-  "m365Auth": {
-    "defaultTenantId": "<azure-tenant-id>",
-    "resources": {
-      "graph": "https://graph.microsoft.com",
-      "sharePoint": "https://microsoft-my.sharepoint.com",
-      "dataverse": "https://iscrm.crm.dynamics.com"
-    },
-    "oneNote": {
-      "defaultNotebookName": "<default-notebook-name>",
-      "defaultNotebookId": "<default-notebook-id>",
-      "defaultSectionResolverUrl": "https://<tenant>-my.sharepoint.com/personal/<user>/_layouts/Doc.aspx?sourcedoc={<notebook-guid>}",
-      "defaultNotebookRootLink": "onenote:https://<tenant>-my.sharepoint.com/personal/<user>/Documents/<notebook-path>/",
-      "defaultLinkOwner": "<default-link-owner>"
-    },
-    "emailContext": {
-      "enabled": true,
-      "workiqOnly": true,
-      "dateFloor": "2026-01-01",
-      "folders": [
-        "Inbox/<primary-project-folder>",
-        "Inbox/<secondary-project-folder>"
-      ],
-      "includeSubfolders": true,
-      "sourceCoverageLabel": "<mailbox-scope-label>",
-      "matchingPolicy": {
-        "mode": "hybrid",
-        "rankingOrder": [
-          "exact",
-          "prefix",
-          "contains"
-        ],
-        "minConfidenceForFolderScopedSearch": "high",
-        "fallbackToFullRootScanWhenAmbiguous": true
-      }
-    },
-    "teamsChatContext": {
-      "enabled": true,
-      "workiqOnly": true,
-      "dateFloor": "2026-01-01",
-      "scope": {
-        "includeChats": true,
-        "includeChannels": true
-      },
-      "matchingPolicy": {
-        "mode": "thread-first",
-        "rankingOrder": [
-          "exact",
-          "prefix",
-          "contains"
-        ],
-        "fallbackToBroaderSearchWhenAmbiguous": true
-      }
-    }
-  }
-}
+{
+  "_meta": {
+    "owner": "ushak@microsoft.com",
+    "purpose": "EXAMPLE — concrete values you can copy-paste into your own m365-auth.json. This file is shipped for reference only and is NOT loaded by kushi. Edit `.kushi/config/user/m365-auth.json` (the per-user config seeded by the installer) with the values from this example, then save.",
+    "audience": "Microsoft Industry Solutions consultants",
+    "schema_version": "1.0",
+    "last_reviewed": "2026-05-29"
+  },
+  "m365Auth": {
+    "defaultTenantId": "72f988bf-86f1-41af-91ab-2d7cd011db47",
+    "resources": {
+      "graph": "https://graph.microsoft.com",
+      "sharePoint": "https://microsoft-my.sharepoint.com",
+      "dataverse": "https://iscrm.crm.dynamics.com"
+    },
+    "oneNote": {
+      "enabled": true,
+      "defaultNotebookName": "ISE Work",
+      "defaultNotebookId": "",
+      "defaultSectionResolverUrl": "",
+      "defaultNotebookRootLink": "",
+      "defaultLinkOwner": "ushak@microsoft.com"
+    },
+
+    "_emailContext_HOWTO": "Setting `folders` is the single biggest discover/refresh speedup. List the 1–4 parent folders that hold ALL your project mail. With `includeSubfolders: true`, every folder under each one is included. WorkIQ then runs a bounded Graph filter (5–15s) instead of a mailbox-wide semantic search (60–180s). Pair with `dateFloor` for further speedup.",
+    "emailContext": {
+      "enabled": true,
+      "dateFloor": "2026-03-01",
+      "folders": [
+        "1. FDE",
+        "99. FDE Not Active"
+      ],
+      "includeSubfolders": true,
+      "sourceCoverageLabel": "FDE consultant — active + archived engagement folders",
+      "matchingPolicy": {
+        "mode": "hybrid",
+        "rankingOrder": ["exact", "prefix", "contains"],
+        "minConfidenceForFolderScopedSearch": "high",
+        "fallbackToFullRootScanWhenAmbiguous": true,
+        "alwaysFuzzy": true
+      }
+    },
+
+    "_teamsChatContext_HOWTO": "Setting `dateFloor` keeps Teams discovery scoped to the active engagement window. 90 days back is a good default — older chats rarely yield new project boundaries.",
+    "teamsChatContext": {
+      "enabled": true,
+      "dateFloor": "2026-03-01",
+      "scope": { "includeChats": true, "includeChannels": true },
+      "matchingPolicy": {
+        "mode": "thread-first",
+        "rankingOrder": ["exact", "prefix", "contains"],
+        "fallbackToBroaderSearchWhenAmbiguous": true,
+        "alwaysFuzzy": true
+      }
+    },
+
+    "_calendarContext_HOWTO": "Setting `dateFloor` filters meeting series. 90 days back is the default; reduce to 30 days for tight engagements.",
+    "calendarContext": {
+      "enabled": true,
+      "dateFloor": "2026-03-01",
+      "matchingPolicy": {
+        "mode": "subject-and-body-keywords",
+        "rankingOrder": ["exact", "prefix", "contains"],
+        "alwaysFuzzy": true
+      }
+    },
+
+    "_sharePointContext_HOWTO": "`localProjectsRoot` should point at the local sync root for your engagement library. kushi uses it to match project folder names against on-disk paths.",
+    "sharePointContext": {
+      "enabled": true,
+      "localProjectsRoot": "C:\\Users\\ushak\\OneDrive - Microsoft\\ISE\\Engagement Assets",
+      "matchingPolicy": {
+        "mode": "fuzzy-folder-name",
+        "rankingOrder": ["exact", "prefix", "contains"],
+        "alwaysFuzzy": true
+      }
+    }
+  },
+
+  "_alternative_examples": {
+    "_comment": "Other realistic shapes. Pick the one that matches your mailbox layout — copy the `folders` array into the active config above.",
+    "single-project-team-member": ["Inbox/Northwind", "Archive/Northwind"],
+    "dedicated-project-folders": ["Projects/HCA", "Projects/AbnAmro", "Projects/JohnDeere"],
+    "everything-in-inbox": ["Inbox"],
+    "fde-consultant-active-only": ["1. FDE"],
+    "fde-consultant-active-plus-archive": ["1. FDE", "99. FDE Not Active"]
+  }
+}

package/plugin/templates/init/m365-auth.template.json

@@ -29,8 +29,14 @@
     "emailContext": {
       "enabled": true,
       "dateFloor": "",
+      "_dateFloor_note": "ISO date 'YYYY-MM-DD'. Empty = no floor (slower). Recommended: set to 90 days ago. Example: \"2026-03-01\".",
       "folders": [],
-      "_folders_note": "Empty array = scan the FULL mailbox (slower, every run). For faster runs, supply specific folder names: [\"Inbox\", \"Archive\", \"Projects/Northwind\"]. Subfolders included when includeSubfolders=true.",
+      "_folders_note": "Empty array = scan the FULL mailbox (slow, every run). For fast queries, list the parent folders that contain ALL your project mail. Subfolders included when includeSubfolders=true. Example for a Microsoft consultant: [\"1. FDE\", \"99. FDE Not Active\", \"Inbox\"].",
+      "_folders_examples": {
+        "fde-consultant": ["1. FDE", "99. FDE Not Active"],
+        "generic": ["Inbox", "Archive", "Projects"],
+        "single-project": ["Inbox/Northwind"]
+      },
       "includeSubfolders": true,
       "sourceCoverageLabel": "",
       "matchingPolicy": {
@@ -44,6 +50,7 @@
     "teamsChatContext": {
       "enabled": true,
       "dateFloor": "",
+      "_dateFloor_note": "ISO date 'YYYY-MM-DD'. Empty = no floor. Recommended: 90 days ago. Example: \"2026-03-01\".",
       "scope": { "includeChats": true, "includeChannels": true },
       "matchingPolicy": {
         "mode": "thread-first",
@@ -54,6 +61,8 @@
     },
     "calendarContext": {
       "enabled": true,
+      "dateFloor": "",
+      "_dateFloor_note": "ISO date 'YYYY-MM-DD'. Empty = no floor. Recommended: 90 days ago. Example: \"2026-03-01\".",
       "matchingPolicy": {
         "mode": "subject-and-body-keywords",
         "rankingOrder": ["exact", "prefix", "contains"],

package/src/main.mjs

@@ -17,6 +17,7 @@ import { installRunnerDeps } from './install-runner-deps.mjs';
 import { mergeSettings } from './settings.mjs';
 import { mergeCopilotInstructions } from './copilot-instructions.mjs';
 import { seedConfig } from './seed-config.mjs';
+import { runM365Quickstart } from './quickstart-m365.mjs';
 import { checkWorkIQ, pingWorkIQ, tryInstallWorkIQ } from './check-workiq.mjs';
 import {
   resolveProfile,
@@ -115,6 +116,15 @@ async function installVscode(options, resolved, version) {
   const seedRes = seedConfig(PKG_ROOT, fullDest);
   printSeedReport(seedRes, `${dest}/`);
 
+  // v5.8.1: prompt for the 3 fields that most affect discover speed.
+  // Skips silently when --no-prompt is set, when not running in a TTY, or
+  // when all 3 fields are already populated (re-install case).
+  const noPrompt = options.noPrompt || process.env.KUSHI_NO_PROMPT === '1';
+  const qs = await runM365Quickstart({ destRoot: fullDest, noPrompt });
+  if (qs.ran === false && qs.reason && !['already-populated', 'no-prompt-flag'].includes(qs.reason)) {
+    console.log(`  Quickstart skipped: ${qs.reason}`);
+  }
+
   if (!options.noSettings) {
     const { created, keysAdded, keysUnchanged } = mergeSettings(
       projectRoot,

package/src/multi-host.mjs

@@ -299,6 +299,7 @@ export async function runMultiHost(opts) {
           force: true,
           profile: opts.profile,
           skipWorkiqCheck: true,
+          noPrompt: opts.noPrompt,
         });
       } catch (err) {
         console.error(`  Workspace install failed: ${err.message}`);

package/src/quickstart-m365.mjs

@@ -0,0 +1,129 @@
+// src/quickstart-m365.mjs
+// Post-install interactive prompt for the 3 fields that most affect kushi
+// `discover` wall time (folders, dateFloor via lookback-days, OneNote notebook).
+// Runs at the end of `installWorkspace()` when the destination just got a fresh
+// m365-auth.json seed. Skips silently when not a TTY or when --no-prompt is set.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const SENTINELS = [/__FILL_ME_IN__/, /^<[A-Za-z][^>]*>$/, /^<auto>$/];
+function looksLikeSentinel(s) {
+  if (!s) return true;
+  return SENTINELS.some((re) => re.test(s));
+}
+
+function isoDateNDaysAgo(n) {
+  const d = new Date();
+  d.setDate(d.getDate() - n);
+  return d.toISOString().slice(0, 10);
+}
+
+/**
+ * Run the 3-question quickstart. Returns a small report object:
+ *   { ran: bool, reason?: string, file?: string, fields?: string[] }
+ *
+ * @param {object} opts
+ * @param {string} opts.destRoot   - absolute path to .kushi/ (the workspace install root)
+ * @param {boolean} [opts.force]   - overwrite existing non-empty values
+ * @param {boolean} [opts.noPrompt]- skip prompting (CI / scripted installs)
+ */
+export async function runM365Quickstart({ destRoot, force = false, noPrompt = false } = {}) {
+  if (noPrompt) return { ran: false, reason: 'no-prompt-flag' };
+  if (!process.stdin.isTTY || !process.stderr.isTTY) return { ran: false, reason: 'not-a-tty' };
+
+  const target = path.join(destRoot, 'config', 'user', 'm365-auth.json');
+  if (!fs.existsSync(target)) return { ran: false, reason: 'm365-auth-not-found' };
+
+  let parsed;
+  try { parsed = JSON.parse(fs.readFileSync(target, 'utf8')); }
+  catch (e) { return { ran: false, reason: `parse-error: ${e.message}` }; }
+  parsed.m365Auth ??= {};
+  const m = parsed.m365Auth;
+  m.emailContext ??= {};
+  m.teamsChatContext ??= {};
+  m.calendarContext ??= {};
+  m.oneNote ??= {};
+
+  // Skip silently if all 3 fields are already populated and --force not passed.
+  const foldersSet = Array.isArray(m.emailContext.folders) && m.emailContext.folders.length > 0;
+  const floorSet = !looksLikeSentinel(m.emailContext.dateFloor);
+  const notebookSet = !looksLikeSentinel(m.oneNote.defaultNotebookName);
+  if (foldersSet && floorSet && notebookSet && !force) {
+    return { ran: false, reason: 'already-populated' };
+  }
+
+  const readline = await import('node:readline/promises');
+  const rl = readline.createInterface({ input: process.stdin, output: process.stderr, terminal: true });
+  const ask = async (q, def) => {
+    const ans = (await rl.question(`${q} ${def != null && def !== '' ? `[${def}]` : ''} > `)).trim();
+    return ans === '' ? def : ans;
+  };
+
+  process.stderr.write('\n  ┌─ Quickstart: 3 questions that make `kushi discover` fast ──\n');
+  process.stderr.write(`  │ Editing: ${target}\n`);
+  process.stderr.write('  │ Press Enter at any prompt to skip (you can always edit the file later).\n');
+  process.stderr.write('  └────────────────────────────────────────────────────────────\n\n');
+
+  const fields = [];
+
+  // 1. Email folders
+  process.stderr.write('  [1/3] Which Outlook mail folders contain your project mail?\n');
+  process.stderr.write('        Examples:\n');
+  process.stderr.write('          • "1. FDE, 99. FDE Not Active"  (Microsoft FDE consultant)\n');
+  process.stderr.write('          • "Inbox, Archive, Projects"     (generic)\n');
+  process.stderr.write('          • "Inbox"                        (everything in inbox)\n');
+  const curFolders = Array.isArray(m.emailContext.folders) ? m.emailContext.folders.join(', ') : '';
+  const foldersAns = await ask('        Comma-separated folder names', curFolders);
+  if (foldersAns && foldersAns !== curFolders) {
+    const arr = foldersAns.split(',').map(s => s.trim()).filter(Boolean);
+    m.emailContext.folders = arr;
+    if (m.emailContext.includeSubfolders == null) m.emailContext.includeSubfolders = true;
+    if (m.emailContext.enabled == null) m.emailContext.enabled = true;
+    fields.push(`emailContext.folders=[${arr.join(', ')}]`);
+  } else if (!foldersAns) {
+    process.stderr.write('        (skipped — discover will scan the whole mailbox, which can take minutes per source)\n');
+  }
+
+  // 2. Look-back days
+  process.stderr.write('\n  [2/3] How many days back should discover scan? (smaller = faster)\n');
+  process.stderr.write('        Recommended: 60 for active engagements, 90 for setup.\n');
+  const curFloor = m.emailContext.dateFloor;
+  const defaultDays = curFloor && /^\d{4}-\d{2}-\d{2}$/.test(curFloor)
+    ? Math.max(1, Math.round((Date.now() - Date.parse(curFloor)) / 86400000))
+    : 60;
+  const daysAns = await ask('        Look-back days', defaultDays);
+  const days = Number(daysAns);
+  if (Number.isFinite(days) && days > 0 && days <= 3650) {
+    const floor = isoDateNDaysAgo(days);
+    m.emailContext.dateFloor = floor;
+    m.teamsChatContext.dateFloor = floor;
+    m.calendarContext.dateFloor = floor;
+    fields.push(`dateFloor=${floor} (${days} days)`);
+  } else {
+    process.stderr.write(`        ⚠ "${daysAns}" is not a valid number 1–3650 — skipping dateFloor.\n`);
+  }
+
+  // 3. OneNote notebook
+  process.stderr.write('\n  [3/3] Which OneNote notebook holds your project notes?\n');
+  process.stderr.write('        Default for Microsoft consultants: "ISE Work"\n');
+  const curNb = m.oneNote.defaultNotebookName || '';
+  const nbAns = await ask('        Notebook name', curNb || 'ISE Work');
+  if (nbAns && nbAns !== curNb) {
+    m.oneNote.defaultNotebookName = nbAns;
+    if (m.oneNote.enabled == null) m.oneNote.enabled = true;
+    fields.push(`oneNote.defaultNotebookName="${nbAns}"`);
+  }
+
+  rl.close();
+
+  if (fields.length === 0) {
+    process.stderr.write('\n  ⓘ No changes — m365-auth.json left as seeded. Edit it later to enable bounded discover.\n\n');
+    return { ran: true, reason: 'no-changes', file: target, fields: [] };
+  }
+  fs.writeFileSync(target, JSON.stringify(parsed, null, 2) + '\n');
+  process.stderr.write(`\n  ✓ Wrote ${fields.length} field(s) to ${target}:\n`);
+  for (const f of fields) process.stderr.write(`      • ${f}\n`);
+  process.stderr.write('\n');
+  return { ran: true, file: target, fields };
+}