kushi-agents 5.7.1 → 5.7.3

package/README.md

@@ -260,6 +260,7 @@ npx kushi-agents --clawpilot                       # Clawpilot only
 npx kushi-agents --vscode                          # VS Code Chat only
 
 # Install to BOTH at once (auto-detects what's present + targets both)
+# v5.7.1+: when run from inside a project dir, also refreshes <cwd>/.kushi/.
 npx kushi-agents --all-hosts
 
 # Uninstall

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kushi-agents",
-  "version": "5.7.1",
+  "version": "5.7.3",
   "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": {
@@ -43,7 +43,7 @@
   },
   "license": "MIT",
   "scripts": {
-    "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 src/multi-host-install.test.mjs src/eval-aggregator.test.mjs src/eval-runner.test.mjs src/skill-creator.test.mjs src/skill-checker.test.mjs src/hooks-dispatcher.test.mjs src/parallel-refresh.test.mjs src/otel-emit.test.mjs src/teach.test.mjs src/schema-evolve.test.mjs src/global-wiki.test.mjs src/promote.test.mjs src/doctor.test.mjs src/setup-wizard.test.mjs src/cli-no-args.test.mjs src/cli-no-args-tty.test.mjs src/per-user-files.test.mjs src/layout-portable.test.mjs src/profile-coverage.test.mjs plugin/runners/test/unit/*.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 src/multi-host-install.test.mjs src/eval-aggregator.test.mjs src/eval-runner.test.mjs src/skill-creator.test.mjs src/skill-checker.test.mjs src/hooks-dispatcher.test.mjs src/parallel-refresh.test.mjs src/otel-emit.test.mjs src/teach.test.mjs src/schema-evolve.test.mjs src/global-wiki.test.mjs src/promote.test.mjs src/doctor.test.mjs src/setup-wizard.test.mjs src/cli-no-args.test.mjs src/cli-no-args-tty.test.mjs src/per-user-files.test.mjs src/layout-portable.test.mjs src/profile-coverage.test.mjs src/get-kushi-config.test.mjs src/seed-config-derived.test.mjs plugin/runners/test/unit/*.test.mjs",
     "test:runners": "node --test plugin/runners/test/unit/*.test.mjs",
     "test:runners:integration": "node --test plugin/runners/test/integration/*.test.mjs",
     "test:integration:bootstrap": "node src/bootstrap-dryrun.integration.test.mjs",

package/plugin/learnings/cross-cutting.md

@@ -4,6 +4,89 @@ Newest on top. Format defined in [`README.md`](./README.md). Use this file when
 
 ---
 
+### 2026-05-29 — `<auto>` placeholder check was blocking fresh installs
+
+**Symptom**: After a clean `npx kushi-agents@latest --all-hosts` install, the very first command users tried (`& '.\.kushi\lib\Get-KushiConfig.ps1' -Name 'm365-auth'`) threw a placeholder error citing `<auto>`. But `<auto>` is the explicit "Kushi will resolve this at runtime from identity / OS / WorkIQ" sentinel, by design — not an unfilled placeholder.
+
+**Root cause**: `<auto>` was wrongly listed alongside `__FILL_ME_IN__` in the blocking-sentinels array of `Get-KushiConfig.ps1`. That conflated two different concepts:
+
+- **Hard-blocking placeholders** (`__FILL_ME_IN__`, `<TENANT_ID>`, `<engagement-root>`, `<ProjectA>`): values that genuinely cannot be derived without user input. These should block.
+- **Runtime-resolution sentinels** (`<auto>`, `<YYYY-MM-DD>`): values that Kushi *can* derive at use-time from `os.userInfo()`, `Date.now()`, or WorkIQ whoami. These should NOT block; they're a feature flag for lazy fill.
+
+**Fix shipped (v5.7.3, 2026-05-29)**:
+
+1. **Removed `<auto>` from blocking sentinels** in `plugin/lib/Get-KushiConfig.ps1`. Added a comment explaining why so future contributors don't add it back.
+2. **Added `applyDerivedDefaults()` to `src/seed-config.mjs`** — runs at install time on freshly-seeded user/ files (never touches preserved/edited copies):
+   - `m365-auth.json#_meta.last_reviewed` ← today (YYYY-MM-DD)
+   - `m365-auth.json#_meta.owner` ← `${os.userInfo().username}@microsoft.com`
+   - `m365-auth.json#m365Auth.sharePointContext.localProjectsRoot` ← auto-detected from `$env:OneDriveCommercial`, `~/OneDrive - Microsoft/ISE/Engagement Assets`, or other `OneDrive - <Tenant>/ISE/Engagement Assets` paths if exactly one exists
+   - `project-evidence.yml#projects_root` ← same OneDrive auto-detection
+3. **Install now prints what was auto-filled** under `Config.user/  auto-filled defaults:` so users can see exactly what Kushi figured out and what they still need to edit.
+4. **Six new unit tests** in `src/seed-config-derived.test.mjs` + an integration test in `src/get-kushi-config.test.mjs` that does a real install and asserts `Get-KushiConfig.ps1 -Name m365-auth` passes (or fails ONLY with `__FILL_ME_IN__`, never `<auto>`).
+
+**Lesson**: When a config schema mixes hard-blocking placeholders with explicit "auto-resolve" sentinels, keep them in *separate lists*. Conflating them in one validation pass is a footgun: every new lazy-fill marker becomes a fresh-install bug. Also: install-time derivation is cheaper than runtime resolution — fill what you can mechanically (today's date, OS username, env vars, well-known paths) before a single user prompt is needed.
+
+---
+
+### 2026-05-29 — `[switch]` parameter collides with same-name local var in PowerShell
+
+**Symptom**: Calling `.\.kushi\lib\Get-KushiConfig.ps1 -Name 'm365-auth' -Raw` threw at the **call site**:
+
+```
+Get-KushiConfig.ps1: Cannot convert the "{ ...full file contents... }" value of type "System.String" to type "System.Management.Automation.SwitchParameter".
+```
+
+The error wrapped the entire file content as the failed-coercion value — confusing, because the user's invocation only passed `-Name '...' -Raw` (no positional value).
+
+**Root cause**: PowerShell variables are **case-insensitive**. The script declared `[switch] $Raw` as a parameter, then used a local `$raw = Get-Content -LiteralPath $resolved -Raw` to read the file. Those are the *same variable*. The string assignment to the typed switch parameter triggered SwitchParameter coercion, which fails on any non-empty string. Crucially, the error is reported at the *call site* (the `&` invocation line), not at the assignment line — so the symptom looked like a parameter-binding bug.
+
+**Fix shipped (v5.7.2, 2026-05-29)**: Renamed the local var to `$rawText` everywhere in `Get-KushiConfig.ps1`. Audited all other `[switch]` params in `plugin/lib/*.ps1` for the same collision pattern — none found.
+
+**Why it wasn't caught**: 280 unit tests cover only `.mjs` runners. `Get-KushiConfig.ps1` and other shipped `.ps1` libs had **zero** automated test coverage. Added `src/get-kushi-config.test.mjs` (3 tests) that installs kushi into a temp dir and invokes the live shipped script via `pwsh`, asserting no SwitchParameter coercion error in stderr. Now wired into `npm test` (283 tests).
+
+**Lesson**: Any `.ps1` file shipped to users needs *integration* tests that invoke the real script via `pwsh`, not just unit tests of the JS that calls it. Avoid using `[switch]` parameter names that collide with common local variable names (`$raw`, `$path`, `$name`, `$content`) — PS case-insensitivity makes the collision invisible until something assigns a value.
+
+---
+
+### 2026-05-29 — Two issues that silently broke `bootstrap` end-to-end on Windows
+
+**Symptom**: After v5.7.0 shipped the auto-chain (bootstrap → discover → refresh), users ran the chain on Windows and saw discover return `skipped_reason: EINVAL` for every source, then refresh exit 0 with zero pulls. The runner *appeared* to be working — `status: ok`, no error message — but no boundaries were filled.
+
+**Root causes** (two stacked):
+
+1. **Node 20.12+ refuses to spawn `.cmd`/`.bat` files without `shell:true`** (CVE-2024-27980 hardening). `lib/workiq.mjs` was using `spawn(exe, args, { shell: false })` and the Windows workiq distribution ships as a `workiq.cmd` shim. Every spawn returned `EINVAL` immediately. The runner caught it and recorded `skipped_reason: EINVAL` per-source, but didn't escalate — it looked like 7 individual source-not-available skips, not one runtime-level failure.
+2. **`resolveWorkiqBin()` only checked `~/.copilot/bin/workiq.cmd`**. Users who installed WorkIQ via `npm i -g @microsoft/workiq` had it at `C:\Users\<u>\AppData\Roaming\npm\workiq.cmd` — invisible to kushi, even though `workiq --version` worked fine in their shell.
+
+**Fixes shipped (v5.7.1, 2026-05-29)**:
+
+1. **`lib/workiq.mjs` `runProcess()` routes `.cmd`/`.bat` through `cmd.exe`** with `windowsVerbatimArguments: true`. Verbatim args preserve quoting in long CSC prompts.
+2. **`resolveWorkiqBin()` searches PATH first** (with `PATHEXT`-aware `whichSync`), falls back to `~/.copilot/bin/`. So `npm`-installed workiq is now picked up automatically.
+3. **Lesson for future runners**: a per-source `skipped_reason` in JSON output isn't a substitute for a top-level error. If every source returns the SAME error code, that's a runtime failure, not 7 missing-source signals. Consider adding a `runtime_error` envelope check in discover that flips the top-level `status` to `error` if ≥N sources skip with the same `EXXX` code.
+
+**Discovered during**: Soak test of v5.7.0 in `kushi-wp` workspace — discover printed `{"status":"ok",...}` with all 7 sources `skipped_reason: EINVAL`, refresh ran clean, but no boundary was actually filled. Symptom looked like "WorkIQ has nothing for this project" until the user ran `node -e "spawn(...)"` to repro the EINVAL.
+
+---
+
+### 2026-05-29 — Two-command install (`--all-hosts` then workspace) is the wrong default
+
+**Symptom**: User runs:
+
+```
+npx kushi-agents@latest --all-hosts --profile full
+cd <repo-root>-wp
+npx kushi-agents@latest --profile full
+```
+
+…and asks: *"this is weird running both. is there a better way?"*
+
+**Root cause**: The CLI dispatched on the presence of host flags. `--all-hosts` took the `runMultiHost()` code path which did host-only installs. `npx kushi-agents` (no flag) took the legacy `main.mjs` workspace-install path. The two paths were mutually exclusive, even though the user's mental model was *"install Kushi everywhere"* — both globally and in the current repo.
+
+**Fix shipped (v5.7.1)**: After the host loop in `runMultiHost()`, detect if cwd is a recognized project (uses the existing `findProjectMarker()` from `main.mjs` — `.git`, `package.json`, `.kushi/`, `Evidence/`, etc.). If yes, also call `main({ target: 'vscode', yes: true, force: true })` to refresh the workspace install. Suppress with `--no-workspace`. From a non-project directory, prints `Workspace install skipped` and only does host install.
+
+**Result**: `npx kushi-agents@latest --all-hosts --profile full` from inside a repo now does the entire install in one shot. Help text + `docs/getting-started/install.md` updated to recommend the unified form first; legacy two-command form preserved in a `<details>` block for users on shared dev machines.
+
+---
+
 ### 2026-05-29 — `bootstrap → "fill the templates" → refresh` is the wrong default
 
 **Symptom**: User runs `bootstrap Northwind`. Runner scaffolds folders + empty `boundaries.yml` + empty `integrations.yml`. SKILL.md tells the agent to reply *"now fill these two files and run refresh"*. User runs `refresh` immediately; refresh emits a configuration-blocked report and exits 0 with zero pulls. User's reaction: *"we know we need to fill them, why did the tool stop and ask? is this not a methodical do?"*

package/plugin/lib/Get-KushiConfig.ps1

@@ -79,7 +79,10 @@ $script:RequiredFields = @{
 # Sentinel substrings that indicate "still a placeholder."
 $script:Sentinels = @(
   '__FILL_ME_IN__',
-  '<auto>',
+  # NOTE: '<auto>' is intentionally NOT in this list. It is a runtime-resolution
+  # marker meaning "Kushi will derive this from identity/env at use time" — not
+  # an unfilled placeholder. Callers that need a concrete value should resolve
+  # <auto> themselves (e.g. via WorkIQ whoami or os.userInfo()).
   '<TENANT_ID>',
   '<NOTEBOOK_ID>',
   '<NOTEBOOK_NAME>',
@@ -87,7 +90,9 @@ $script:Sentinels = @(
   '<SP_LOCAL_ROOT>',
   '<your-alias>',
   '<Your Full Name>',
-  'your.email@example.com'
+  'your.email@example.com',
+  '<engagement-root>',
+  '<ProjectA>'
 )
 
 function Test-Sentinel {
@@ -180,12 +185,12 @@ Run ``npx kushi-agents@latest`` (vscode) or ``npx kushi-agents@latest --clawpilo
 
 if ($Path) { return $resolved }
 
-$raw = Get-Content -LiteralPath $resolved -Raw
+$rawText = Get-Content -LiteralPath $resolved -Raw
 
 if (-not $AllowPlaceholders) {
   $sentinelHit = $false
   foreach ($s in $script:Sentinels) {
-    if ($raw -like "*$s*") { $sentinelHit = $true; break }
+    if ($rawText -like "*$s*") { $sentinelHit = $true; break }
   }
   if ($sentinelHit) {
     throw @"
@@ -195,16 +200,16 @@ Edit the file with your actual values, or pass -AllowPlaceholders to bypass this
   }
 }
 
-if ($Raw) { return $raw }
+if ($Raw) { return $rawText }
 
 $parsed = switch ($ext) {
   'json' {
-    $raw | ConvertFrom-Json -Depth 100
+    $rawText | ConvertFrom-Json -Depth 100
   }
   { $_ -in 'yml','yaml' } {
     if (Get-Module -ListAvailable -Name 'powershell-yaml') {
       Import-Module powershell-yaml -ErrorAction Stop
-      ConvertFrom-Yaml -Yaml $raw
+      ConvertFrom-Yaml -Yaml $rawText
     } else {
       Write-Warning "powershell-yaml not installed; required-field validation skipped. Install with: Install-Module powershell-yaml -Scope CurrentUser"
       $null
@@ -223,5 +228,5 @@ Edit the file with your actual values, or pass -AllowPlaceholders to bypass this
   }
 }
 
-if ($null -eq $parsed) { return $raw }
+if ($null -eq $parsed) { return $rawText }
 return $parsed

package/src/get-kushi-config.test.mjs

@@ -0,0 +1,92 @@
+// Regression tests for plugin/lib/Get-KushiConfig.ps1.
+//
+// History: v5.7.1 had a SwitchParameter coercion bug. The script's
+// [switch] $Raw parameter collided with a local $raw = Get-Content variable
+// (PowerShell variables are case-insensitive). Assigning a string into the
+// typed switch parameter caused "Cannot convert String to SwitchParameter"
+// at the call site whenever the script was invoked from outside its own
+// scope.
+//
+// These tests install kushi into a temp dir, then invoke the live shipped
+// Get-KushiConfig.ps1 with various flag combinations and assert that the
+// invocation succeeds with no error stream output.
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const REPO = path.resolve(HERE, '..');
+
+function makeTmp(prefix) {
+  return fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+}
+
+function freshInstall() {
+  const cwd = makeTmp('kushi-getconfig-');
+  const r = spawnSync(process.execPath, [path.join(REPO, 'bin', 'cli.mjs'), '--profile', 'full', '--skip-workiq-check', '--yes'], {
+    cwd, encoding: 'utf-8', shell: false,
+  });
+  assert.equal(r.status, 0, `installer failed: ${r.stderr || r.stdout}`);
+  return cwd;
+}
+
+function pwsh(cwd, args) {
+  return spawnSync('pwsh', ['-NoProfile', '-Command', ...args], {
+    cwd, encoding: 'utf-8', shell: false,
+  });
+}
+
+test('Get-KushiConfig.ps1 -Name m365-auth -Raw does not raise SwitchParameter coercion error', () => {
+  const cwd = freshInstall();
+  const script = path.join(cwd, '.kushi', 'lib', 'Get-KushiConfig.ps1');
+  const r = pwsh(cwd, [`& '${script}' -Name 'm365-auth' -Raw -AllowPlaceholders | Out-Null; if ($?) { 'OK' } else { 'FAIL' }`]);
+  assert.equal(r.status, 0, `pwsh exited ${r.status}; stderr=${r.stderr}`);
+  assert.match(r.stdout, /OK/, `expected OK, got stdout=${r.stdout} stderr=${r.stderr}`);
+  assert.doesNotMatch(r.stderr, /SwitchParameter/i, `SwitchParameter coercion error leaked: ${r.stderr}`);
+});
+
+test('Get-KushiConfig.ps1 -Name project-evidence -AllowPlaceholders -Raw works on fresh install', () => {
+  const cwd = freshInstall();
+  const script = path.join(cwd, '.kushi', 'lib', 'Get-KushiConfig.ps1');
+  const r = pwsh(cwd, [`& '${script}' -Name 'project-evidence' -AllowPlaceholders -Raw | Out-Null; if ($?) { 'OK' } else { 'FAIL' }`]);
+  assert.equal(r.status, 0, `pwsh exited ${r.status}; stderr=${r.stderr}`);
+  assert.match(r.stdout, /OK/, `expected OK, got stdout=${r.stdout} stderr=${r.stderr}`);
+  assert.doesNotMatch(r.stderr, /SwitchParameter/i, `SwitchParameter coercion error leaked: ${r.stderr}`);
+});
+
+test('Get-KushiConfig.ps1 -Path returns absolute resolved path', () => {
+  const cwd = freshInstall();
+  const script = path.join(cwd, '.kushi', 'lib', 'Get-KushiConfig.ps1');
+  const r = pwsh(cwd, [`& '${script}' -Name 'm365-auth' -Path`]);
+  assert.equal(r.status, 0, `pwsh exited ${r.status}; stderr=${r.stderr}`);
+  assert.match(r.stdout, /m365-auth\.json/, `expected resolved path, got stdout=${r.stdout}`);
+  assert.doesNotMatch(r.stderr, /SwitchParameter/i);
+});
+
+test('Get-KushiConfig.ps1 -Name m365-auth (no -AllowPlaceholders) passes on fresh install with auto-filled defaults', () => {
+  // Regression for: bootstrap rejected fresh installs because the template's
+  // <auto>, <YYYY-MM-DD>, and __FILL_ME_IN__ markers all triggered the
+  // placeholder check. Fix: <auto> removed from blocking sentinels (it's a
+  // runtime-resolve marker), and seed-config now mechanically fills
+  // last_reviewed (today), _meta.owner (from $env:USER), and localProjectsRoot
+  // (auto-detected from OneDrive) at install time.
+  const cwd = freshInstall();
+  const script = path.join(cwd, '.kushi', 'lib', 'Get-KushiConfig.ps1');
+  const r = pwsh(cwd, [`& '${script}' -Name 'm365-auth' -Raw | Out-Null; if ($?) { 'OK' } else { 'FAIL' }`]);
+  // Note: localProjectsRoot may still be __FILL_ME_IN__ on machines with no OneDrive,
+  // so accept either (a) clean pass, or (b) a placeholder error that mentions ONLY
+  // __FILL_ME_IN__ (not <auto>, not <YYYY-MM-DD>).
+  if (r.stdout.includes('OK')) {
+    assert.doesNotMatch(r.stderr, /SwitchParameter/i);
+    return;
+  }
+  // If it failed, the only acceptable reason is genuine __FILL_ME_IN__ on machines
+  // without an auto-detectable OneDrive root.
+  assert.match(r.stderr, /__FILL_ME_IN__/, `expected only __FILL_ME_IN__ blocker, got: ${r.stderr}`);
+  assert.doesNotMatch(r.stderr, /<auto>/, `<auto> must NOT block — it is a runtime-resolve marker`);
+});

package/src/main.mjs

@@ -231,6 +231,10 @@ function printSeedReport(r, dispDestSlash) {
     for (const f of r.seededUser)    console.log(`      - ${f} -> seeded (edit before first bootstrap)`);
     for (const f of r.preservedUser) console.log(`      - ${f} -> preserved (already exists)`);
   }
+  if (r.derived && r.derived.length) {
+    console.log(`    auto-filled defaults:`);
+    for (const d of r.derived) console.log(`      - ${d.file}#${d.field} -> ${d.value}`);
+  }
   if (r.gitignore === 'created' || r.gitignore === 'appended') {
     console.log(`    .gitignore ${r.gitignore === 'created' ? 'created' : 'appended'} -> config/user/ excluded`);
   }

package/src/seed-config-derived.test.mjs

@@ -0,0 +1,117 @@
+// Tests for applyDerivedDefaults() in seed-config.mjs.
+//
+// Verifies that mechanically-derivable fields (today's date, OS-derived
+// identity, OneDrive auto-detection) are filled at install time so a fresh
+// install passes the Get-KushiConfig.ps1 placeholder check without manual
+// editing or `@Kushi setup` rituals.
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { seedConfig } from './seed-config.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PKG = path.resolve(__dirname, '..');
+
+function tmp() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'kushi-derived-'));
+}
+
+test('applyDerivedDefaults: fills last_reviewed with today (m365-auth.json)', () => {
+  const dest = tmp();
+  try {
+    const r = seedConfig(PKG, dest);
+    assert.ok(r.seededUser.includes('m365-auth.json'));
+
+    const cfgPath = path.join(dest, 'config', 'user', 'm365-auth.json');
+    const obj = JSON.parse(fs.readFileSync(cfgPath, 'utf8'));
+    const today = new Date().toISOString().slice(0, 10);
+    assert.equal(obj._meta.last_reviewed, today, 'last_reviewed should be today');
+    assert.notEqual(obj._meta.last_reviewed, '<YYYY-MM-DD>', 'placeholder should be replaced');
+
+    assert.ok(r.derived.some((d) => d.field === '_meta.last_reviewed'), 'derived list should record last_reviewed');
+  } finally {
+    fs.rmSync(dest, { recursive: true, force: true });
+  }
+});
+
+test('applyDerivedDefaults: fills _meta.owner from OS username', () => {
+  const dest = tmp();
+  try {
+    seedConfig(PKG, dest);
+    const cfgPath = path.join(dest, 'config', 'user', 'm365-auth.json');
+    const obj = JSON.parse(fs.readFileSync(cfgPath, 'utf8'));
+    const expectedUser = (os.userInfo().username || '').toLowerCase().replace(/[^a-z0-9._-]/g, '');
+    assert.equal(obj._meta.owner, `${expectedUser}@microsoft.com`);
+    assert.notEqual(obj._meta.owner, '<alias>@microsoft.com');
+  } finally {
+    fs.rmSync(dest, { recursive: true, force: true });
+  }
+});
+
+test('applyDerivedDefaults: leaves <auto> identity markers alone (resolved at runtime)', () => {
+  const dest = tmp();
+  try {
+    seedConfig(PKG, dest);
+    const cfgPath = path.join(dest, 'config', 'user', 'm365-auth.json');
+    const obj = JSON.parse(fs.readFileSync(cfgPath, 'utf8'));
+    // <auto> in defaultLinkOwner is a runtime-resolution sentinel; seed-config
+    // must NOT preempt it (callers like pull-onenote resolve via WorkIQ whoami).
+    assert.equal(obj.m365Auth.oneNote.defaultLinkOwner, '<auto>');
+  } finally {
+    fs.rmSync(dest, { recursive: true, force: true });
+  }
+});
+
+test('applyDerivedDefaults: produces valid JSON (no syntax errors)', () => {
+  const dest = tmp();
+  try {
+    seedConfig(PKG, dest);
+    const cfgPath = path.join(dest, 'config', 'user', 'm365-auth.json');
+    const txt = fs.readFileSync(cfgPath, 'utf8');
+    assert.doesNotThrow(() => JSON.parse(txt), 'seeded m365-auth.json must be parseable');
+    assert.ok(txt.endsWith('\n'), 'should end with newline');
+  } finally {
+    fs.rmSync(dest, { recursive: true, force: true });
+  }
+});
+
+test('applyDerivedDefaults: project-evidence.yml stays parseable as YAML', () => {
+  const dest = tmp();
+  try {
+    seedConfig(PKG, dest);
+    const cfgPath = path.join(dest, 'config', 'user', 'project-evidence.yml');
+    const txt = fs.readFileSync(cfgPath, 'utf8');
+    // Sanity: top-level keys still present
+    assert.match(txt, /^alias:/m);
+    assert.match(txt, /^email:/m);
+    assert.match(txt, /^projects_root:/m);
+  } finally {
+    fs.rmSync(dest, { recursive: true, force: true });
+  }
+});
+
+test('applyDerivedDefaults: does not re-derive on reinstall when files preserved', () => {
+  const dest = tmp();
+  try {
+    seedConfig(PKG, dest);
+    const cfgPath = path.join(dest, 'config', 'user', 'm365-auth.json');
+    // Edit the seeded file as a user would
+    const obj = JSON.parse(fs.readFileSync(cfgPath, 'utf8'));
+    obj._meta.last_reviewed = '2020-01-01';
+    fs.writeFileSync(cfgPath, JSON.stringify(obj, null, 2) + '\n');
+
+    // Reinstall — file is preserved, derived must not re-run on it
+    const r2 = seedConfig(PKG, dest);
+    assert.ok(r2.preservedUser.includes('m365-auth.json'));
+    assert.equal(r2.derived.length, 0, 'derived should be empty when no files were freshly seeded');
+
+    const after = JSON.parse(fs.readFileSync(cfgPath, 'utf8'));
+    assert.equal(after._meta.last_reviewed, '2020-01-01', 'user-edited value preserved');
+  } finally {
+    fs.rmSync(dest, { recursive: true, force: true });
+  }
+});

package/src/seed-config.mjs

@@ -1,4 +1,5 @@
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import {
   CONFIG_DIR,
@@ -86,12 +87,92 @@ export function seedConfig(sourcePkgDir, destAbsolute) {
   overwriteAlways(CONFIG_DOCTRINE_FILES, sharedDir, result.doctrine);
   overwriteAlways(CONFIG_EXAMPLE_FILES, sharedDir, result.examples);
 
+  // Post-process freshly-seeded user/ files: mechanically derive defaults
+  // (today's date, OneDrive root, OS-derived identity) so a brand-new install
+  // can be used immediately without manual editing or `@Kushi setup` rituals.
+  // Only runs on files we just seeded — never touches user-edited copies.
+  result.derived = applyDerivedDefaults(userDir, result.seededUser);
+
   // .gitignore at <dest>/.gitignore — append our marker block if not already present
   result.gitignore = ensureGitignore(destAbsolute, CONFIG_GITIGNORE_LINES);
 
   return result;
 }
 
+/**
+ * Mechanically derive defaults for freshly-seeded user-config files.
+ * Only modifies files in `seededFiles` (i.e. just-created in this run).
+ * Returns a list of {file, field, value} for the seed report.
+ */
+export function applyDerivedDefaults(userDir, seededFiles) {
+  const today = new Date().toISOString().slice(0, 10);
+  const username = (os.userInfo().username || '').toLowerCase().replace(/[^a-z0-9._-]/g, '');
+  const oneDriveRoot = detectOneDriveProjectsRoot();
+  const filled = [];
+
+  if (seededFiles.includes('m365-auth.json')) {
+    const f = path.join(userDir, 'm365-auth.json');
+    try {
+      const txt = fs.readFileSync(f, 'utf8');
+      const obj = JSON.parse(txt);
+      if (obj?._meta?.last_reviewed === '<YYYY-MM-DD>') {
+        obj._meta.last_reviewed = today; filled.push({ file: 'm365-auth.json', field: '_meta.last_reviewed', value: today });
+      }
+      if (username && obj?._meta?.owner === '<alias>@microsoft.com') {
+        obj._meta.owner = `${username}@microsoft.com`; filled.push({ file: 'm365-auth.json', field: '_meta.owner', value: obj._meta.owner });
+      }
+      if (oneDriveRoot && obj?.m365Auth?.sharePointContext?.localProjectsRoot === '__FILL_ME_IN__') {
+        obj.m365Auth.sharePointContext.localProjectsRoot = oneDriveRoot;
+        filled.push({ file: 'm365-auth.json', field: 'm365Auth.sharePointContext.localProjectsRoot', value: oneDriveRoot });
+      }
+      fs.writeFileSync(f, JSON.stringify(obj, null, 2) + '\n', 'utf8');
+    } catch { /* leave file as-is on parse error */ }
+  }
+
+  if (seededFiles.includes('project-evidence.yml')) {
+    const f = path.join(userDir, 'project-evidence.yml');
+    try {
+      let txt = fs.readFileSync(f, 'utf8');
+      if (oneDriveRoot && txt.includes("projects_root: '<engagement-root>'")) {
+        txt = txt.replace("projects_root: '<engagement-root>'", `projects_root: '${oneDriveRoot}'`);
+        filled.push({ file: 'project-evidence.yml', field: 'projects_root', value: oneDriveRoot });
+      }
+      fs.writeFileSync(f, txt, 'utf8');
+    } catch { /* leave file as-is on read error */ }
+  }
+
+  return filled;
+}
+
+/**
+ * Best-effort detection of the user's "Engagement Assets" parent folder.
+ * Probes (in order):
+ *   1. $env:OneDriveCommercial/ISE/Engagement Assets   (Windows env-var)
+ *   2. ~/OneDrive - Microsoft/ISE/Engagement Assets    (canonical Microsoft consultant path)
+ *   3. ~/OneDrive - <Tenant>/ISE/Engagement Assets     (single OneDrive-* folder match)
+ * Returns the first existing path or null.
+ */
+function detectOneDriveProjectsRoot() {
+  const candidates = [];
+  if (process.env.OneDriveCommercial) {
+    candidates.push(path.join(process.env.OneDriveCommercial, 'ISE', 'Engagement Assets'));
+  }
+  candidates.push(path.join(os.homedir(), 'OneDrive - Microsoft', 'ISE', 'Engagement Assets'));
+  // Probe other OneDrive - * tenants (e.g. for non-Microsoft consultants)
+  try {
+    const home = os.homedir();
+    for (const entry of fs.readdirSync(home, { withFileTypes: true })) {
+      if (entry.isDirectory() && entry.name.startsWith('OneDrive - ') && entry.name !== 'OneDrive - Microsoft') {
+        candidates.push(path.join(home, entry.name, 'ISE', 'Engagement Assets'));
+      }
+    }
+  } catch { /* homedir not readable - skip */ }
+  for (const p of candidates) {
+    try { if (fs.statSync(p).isDirectory()) return p; } catch { /* not present */ }
+  }
+  return null;
+}
+
 function ensureGitignore(destAbsolute, lines) {
   const target = path.join(destAbsolute, '.gitignore');
   const marker = lines[0];