kushi-agents 5.9.0 → 5.9.1

package/bin/cli.mjs

@@ -103,22 +103,47 @@ if (args.length > 0 && args[0] === 'lint') {
   process.exit(0);
 }
 
+// ── one-shot wiki verb (v5.9.1+) ─────────────────────────────────────────────
+// `kushi wiki` — deterministic do-the-wiki: resolve root, init if missing,
+// print path + status + clickable file:// URL. Idempotent across
+// "create wiki" / "do wiki" / "refresh wiki" / "update wiki".
+if (args.length > 0 && args[0] === 'wiki') {
+  const cliMod = await import('../src/global-wiki-cli.mjs');
+  await cliMod.runWiki();
+  process.exit(0);
+}
+
 // ── global verb (v5.3.0+) ────────────────────────────────────────────────────
 if (args.length > 0 && args[0] === 'global') {
   const sub = args[1] || '';
-  const validSubs = ['init', 'status', 'ask', 'lint'];
+  const validSubs = ['init', 'status', 'ask', 'lint', 'migrate', 'set-root', 'show-root'];
   if (!validSubs.includes(sub)) {
-    console.error('\n  Usage: kushi global init           Scaffold ~/.kushi-global/State/');
-    console.error('         kushi global status         Show counts + freshness');
-    console.error('         kushi global ask <question> Ask the global wiki');
-    console.error('         kushi global lint           Lint the global wiki\n');
+    console.error('\n  Usage: kushi global init                    Scaffold State/ at the resolved root');
+    console.error('         kushi global status                  Show counts + freshness');
+    console.error('         kushi global ask <question>          Ask the global wiki');
+    console.error('         kushi global lint                    Lint the global wiki');
+    console.error('         kushi global show-root               Show how the root path is resolved');
+    console.error('         kushi global set-root <path> [--scope workspace|home]');
+    console.error('                                              Persist root (workspace shared by default,');
+    console.error('                                              falls back to ~/.kushi/config.json)');
+    console.error('         kushi global migrate <new-path>      Copy wiki to a new root + persist setting\n');
+    console.error('  Tip: Set the root to a OneDrive-synced SharePoint folder to share');
+    console.error('       the wiki across a team. See docs/how-to/wiki-on-sharepoint.md.\n');
     process.exit(1);
   }
-  const { runGlobalInit, runGlobalStatus, runGlobalAsk, runGlobalLint } = await import('../src/global-wiki-cli.mjs');
-  if (sub === 'init') await runGlobalInit();
-  else if (sub === 'status') await runGlobalStatus();
-  else if (sub === 'ask') await runGlobalAsk(args.slice(2).join(' '));
-  else if (sub === 'lint') await runGlobalLint();
+  const cliMod = await import('../src/global-wiki-cli.mjs');
+  if (sub === 'init') await cliMod.runGlobalInit();
+  else if (sub === 'status') await cliMod.runGlobalStatus();
+  else if (sub === 'ask') await cliMod.runGlobalAsk(args.slice(2).join(' '));
+  else if (sub === 'lint') await cliMod.runGlobalLint();
+  else if (sub === 'migrate') await cliMod.runGlobalMigrate(args[2]);
+  else if (sub === 'set-root') {
+    const scopeIdx = args.indexOf('--scope');
+    const scope = scopeIdx > 0 && args[scopeIdx + 1] ? args[scopeIdx + 1] : null;
+    const target = args.find((a, i) => i >= 2 && !a.startsWith('--') && args[i - 1] !== '--scope');
+    await cliMod.runGlobalSetRoot(target, { scope });
+  }
+  else if (sub === 'show-root') await cliMod.runGlobalShowRoot();
   process.exit(0);
 }
 
@@ -262,6 +287,11 @@ if (args.includes('--help') || args.includes('-h')) {
     lint <project>          Run wiki-lint checks on State/
 
   Workspace lifecycle (v5.9.0+):
+    wiki                           One-shot: resolve global wiki root, scaffold
+                                   if missing, print status + clickable file://
+                                   link to the wiki index. Idempotent —
+                                   "do wiki" / "refresh wiki" / "create wiki"
+                                   all map here.
     uninstall [--keep-config]      Remove <cwd>/.kushi/ (preserves Evidence/, State/).
                                    --keep-config preserves config/user/ identity files.
     upgrade                        npm i -g kushi-agents@latest then re-seed assets

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kushi-agents",
-  "version": "5.9.0",
+  "version": "5.9.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/instructions/global-wiki.instructions.md

@@ -17,8 +17,13 @@ The global wiki is a personal, cross-engagement knowledge base that lives **outs
 ### 1. Location
 
 - **Default:** `~/.kushi-global/State/` (`$HOME` on POSIX, `$env:USERPROFILE` on Windows).
-- **Override:** `$KUSHI_GLOBAL_ROOT` environment variable (absolute path; tilde-expanded). Tests MUST set this to `.testtmp/.kushi-global/` — never touch the real path.
-- The global root is **per-user**, never per-project, never per-host.
+- **Resolution chain (v5.9.1+, first non-empty wins):**
+  1. `$KUSHI_GLOBAL_ROOT` env var (absolute path; tilde-expanded). Tests MUST set this to `.testtmp/.kushi-global/` — never touch the real path.
+  2. **`<workspace>/.kushi/config/shared/kushi.yml` → `globalRoot`** (workspace-shared, team-shareable, committed)
+  3. `~/.kushi/config.json` → `globalRoot` (per-user, per-machine)
+  4. Default `~/.kushi-global/`
+- The global root is **per-user OR per-team** (workspace-shared scope), never per-project, never per-host.
+- Inspect with `kushi global show-root`. Set with `kushi global set-root <path> [--scope workspace|home]` (default scope = workspace if a `.kushi/` is found above cwd, else home).
 
 ### 2. Shape
 

package/plugin/skills/global-wiki/SKILL.md

@@ -1,12 +1,21 @@
 ---
 name: "global-wiki"
 version: "1.0.0"
-description: "USE WHEN the user says 'init global wiki', 'kushi global init/status/ask/lint', 'show me my global wiki', or wants to manage the cross-engagement knowledge base at ~/.kushi-global/State/. DO NOT USE for promoting individual pages (use promote) or for project-scoped Q&A (use ask-project). Capability: scaffold + status + ask + lint over the per-user global wiki; honors $KUSHI_GLOBAL_ROOT for tests."
+description: "USE WHEN the user says 'init global wiki', 'kushi global init/status/ask/lint/show-root/set-root', 'show me my global wiki', or wants to manage the cross-engagement knowledge base. DO NOT USE for promoting individual pages (use promote) or for project-scoped Q&A (use ask-project). Capability: scaffold + status + ask + lint + show-root + set-root over the global wiki; resolves location via 4-tier chain (env > workspace shared > home config > default ~/.kushi-global/State/)."
 ---
 
 # Skill: global-wiki
 
-Manages the per-user global wiki at `$KUSHI_GLOBAL_ROOT` (default `~/.kushi-global/State/`). Structurally identical to a project `State/` wiki but tagged `scope: global` in every page's frontmatter. Holds cross-engagement patterns that consultants want to keep across projects.
+Manages the global wiki at the resolved root (default `~/.kushi-global/State/`). Structurally identical to a project `State/` wiki but tagged `scope: global` in every page's frontmatter. Holds cross-engagement patterns that consultants want to keep across projects.
+
+**Location resolution (v5.9.1+, first non-empty wins):**
+
+1. `$KUSHI_GLOBAL_ROOT` env var (override; ideal for tests + temp redirection)
+2. `<workspace>/.kushi/config/shared/kushi.yml → globalRoot` (team-shareable, committed)
+3. `~/.kushi/config.json → globalRoot` (per-user, per-machine)
+4. Default `~/.kushi-global/`
+
+Use `kushi global show-root` to inspect the chain.
 
 See `plugin/instructions/global-wiki.instructions.md` for the full doctrine and `multi-wiki-routing.instructions.md` for how readers + writers route between project and global.
 
@@ -27,14 +36,14 @@ See `plugin/instructions/global-wiki.instructions.md` for the full doctrine and
 
 ## Step checklist
 
-- [ ] Step 1 — Resolve `$KUSHI_GLOBAL_ROOT` (env override) or fall back to `~/.kushi-global/`.
+- [ ] Step 1 — Resolve the global root via the 4-tier chain (env → workspace shared → home config → default).
 - [ ] Step 2 — Dispatch to the requested sub-operation.
 - [ ] Step 3 — Print a one-line summary + paths.
 - [ ] Step 4 — Append a `log.md` entry on init / lint / ask-fileback.
 
 ### Step 1 — Resolve global root
 
-Read `$env:KUSHI_GLOBAL_ROOT`. If unset, default to `$env:USERPROFILE/.kushi-global/` on Windows or `$HOME/.kushi-global/` on POSIX. Tests MUST set `$env:KUSHI_GLOBAL_ROOT='.testtmp/.kushi-global'` and NEVER touch the real path.
+Resolve via 4-tier chain: `$KUSHI_GLOBAL_ROOT` → `<workspace>/.kushi/config/shared/kushi.yml#globalRoot` → `~/.kushi/config.json#globalRoot` → default `~/.kushi-global/`. Tests MUST set `$env:KUSHI_GLOBAL_ROOT='.testtmp/.kushi-global'` and NEVER touch the real path. See `src/global-wiki.mjs#resolveGlobalRoot` for the canonical implementation.
 
 ### Step 2 — Sub-operations
 

package/plugin/templates/init/kushi.template.yml

@@ -0,0 +1,27 @@
+# Kushi — shared workspace settings.
+#
+# Seeded by the installer on first install. Never overwritten on upgrade
+# (unless you pass --force). Safe to commit — these are team-wide settings,
+# not per-contributor identity.
+#
+# Resolution order (first non-empty wins):
+#   1. $env:KUSHI_GLOBAL_ROOT                                  (env override)
+#   2. <workspace>/.kushi/config/shared/kushi.yml → globalRoot (THIS FILE)
+#   3. ~/.kushi/config.json → globalRoot                       (home fallback)
+#   4. ~/.kushi-global/                                        (default)
+#
+# Edit with:  kushi global set-root <path>
+# Or hand-edit this file directly.
+
+# Global wiki root.
+#
+# Path to the team's shared kushi global wiki. State/ is created underneath.
+#
+#   null  → fall back to the home config file or the default ~/.kushi-global/.
+#   path  → use this directory.
+#
+# Tip: set this to a OneDrive-synced SharePoint folder so every contributor
+# on the team picks up the same wiki path automatically (when they pull the
+# repo, this file already names the synced location).
+# See docs/how-to/wiki-on-sharepoint.md.
+globalRoot: null

package/plugin/templates/user-config.json

@@ -0,0 +1,20 @@
+{
+  "_meta": {
+    "purpose": "Per-user, per-machine kushi settings. Lives at ~/.kushi/config.json.",
+    "scope": "machine-user",
+    "version_managed_by": "kushi-agents npm install (seed-once)",
+    "edit_with": "kushi global set-root <path>   (or edit this file directly)"
+  },
+
+  "globalRoot": null,
+
+  "_docs": {
+    "globalRoot": [
+      "Path to the global wiki root. State/ is created underneath.",
+      "null  → kushi falls back to ~/.kushi-global/",
+      "Tip   → set this to a OneDrive-synced SharePoint folder to share the wiki",
+      "        across a team. See docs/how-to/wiki-on-sharepoint.md.",
+      "Override (per-shell): set $env:KUSHI_GLOBAL_ROOT — env always wins."
+    ]
+  }
+}

package/src/constants.mjs

@@ -92,6 +92,7 @@ export const CONFIG_USER_SEED_FILES = [
  */
 export const CONFIG_SHARED_SEED_FILES = [
   { template: 'init/integrations.template.yml', target: 'integrations.yml' },
+  { template: 'init/kushi.template.yml',        target: 'kushi.yml'        },
 ];
 
 /**

package/src/global-wiki-cli.mjs

@@ -4,10 +4,60 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
-import { globalInit, globalStatus, globalAsk, globalLint, promote, resolveGlobalRoot } from './global-wiki.mjs';
+import os from 'node:os';
+import { spawnSync } from 'node:child_process';
+import {
+  globalInit, globalStatus, globalAsk, globalLint, promote,
+  resolveGlobalRoot, explainGlobalRoot, writeUserConfig, userConfigPath,
+  findWorkspaceSharedConfig, writeWorkspaceSharedConfig,
+} from './global-wiki.mjs';
 
-export async function runGlobalInit() {
-  const result = globalInit();
+/**
+ * Persist the global wiki root.
+ *  - If we're inside a workspace (a .kushi/config/shared/ exists somewhere
+ *    above cwd), write to <workspace>/.kushi/config/shared/kushi.yml. This
+ *    is the team-shared, committed location — the right answer when the
+ *    whole team should pick up the same wiki path.
+ *  - Otherwise, fall back to the per-user home file ~/.kushi/config.json.
+ *  - On Windows, also setx KUSHI_GLOBAL_ROOT as a courtesy for tools that
+ *    read the env var directly. The config file is the source of truth.
+ *
+ * Set `scope: 'home'` or `scope: 'workspace'` to force one tier.
+ */
+function persistGlobalRootEnv(rootPath, { scope = 'auto', cwd = process.cwd() } = {}) {
+  const target = path.resolve(rootPath);
+  let where;
+  let chosenScope;
+
+  const wsFile = findWorkspaceSharedConfig(cwd);
+  if (scope === 'workspace' || (scope === 'auto' && wsFile)) {
+    if (!wsFile) {
+      return { method: 'workspace', ok: false, message: `No .kushi/config/shared/kushi.yml found above ${cwd}. Run install in this workspace first, or use --scope home.` };
+    }
+    writeWorkspaceSharedConfig(wsFile, { globalRoot: target });
+    where = wsFile; chosenScope = 'workspace';
+  } else {
+    const cfg = writeUserConfig({ globalRoot: target });
+    where = cfg.path; chosenScope = 'home';
+  }
+
+  let envNote = '';
+  if (process.platform === 'win32') {
+    const r = spawnSync('setx', ['KUSHI_GLOBAL_ROOT', target], { encoding: 'utf8' });
+    envNote = r.status === 0
+      ? ' (also set $env:KUSHI_GLOBAL_ROOT for User scope — visible in new shells)'
+      : '';
+  }
+  return {
+    method: 'config-file',
+    scope: chosenScope,
+    ok: true,
+    message: `Wrote globalRoot to ${where}.${envNote}`,
+  };
+}
+
+export async function runGlobalInit({ root, persistEnv = false } = {}) {
+  const result = globalInit(root ? { root } : {});
   console.log('');
   console.log(`  Global wiki root: ${result.root}`);
   console.log(`  State dir       : ${result.state}`);
@@ -17,11 +67,188 @@ export async function runGlobalInit() {
   if (result.skipped.length) {
     console.log(`  Skipped (${result.skipped.length} already present)`);
   }
+  if (persistEnv && root) {
+    const env = persistGlobalRootEnv(result.root);
+    console.log('');
+    console.log(`  ${env.ok ? '✓' : '⚠'} ${env.message}`);
+  }
   console.log('');
   console.log("  Next: 'kushi global status' or 'kushi promote <project> <page>'");
   console.log('');
 }
 
+/**
+ * Migrate the existing global wiki from current root to a new path.
+ * Copies State/ contents, then persists KUSHI_GLOBAL_ROOT to the new location.
+ * Does NOT delete the old root — user can remove it manually after verifying.
+ */
+export async function runGlobalMigrate(newRootArg, { persistEnv = true } = {}) {
+  if (!newRootArg || !newRootArg.trim()) {
+    console.error('\n  Usage: kushi global migrate <new-root-path>\n');
+    console.error('  Example (OneDrive-synced SharePoint):\n');
+    console.error('    kushi global migrate "C:\\Users\\you\\Microsoft\\TeamWiki - Documents\\KushiWiki"\n');
+    process.exitCode = 1;
+    return;
+  }
+  const newRoot = path.resolve(newRootArg.trim());
+  const oldRoot = resolveGlobalRoot();
+  console.log('');
+  console.log(`  Migrating global wiki:`);
+  console.log(`    from: ${oldRoot}`);
+  console.log(`    to  : ${newRoot}`);
+  console.log('');
+
+  const oldState = path.join(oldRoot, 'State');
+  if (!fs.existsSync(oldState)) {
+    console.log(`  ⚠ No existing State/ at ${oldState} — initializing fresh at ${newRoot}.`);
+    const result = globalInit({ root: newRoot });
+    console.log(`  ✓ Created ${result.created.length} file(s) at ${result.state}`);
+  } else {
+    fs.mkdirSync(newRoot, { recursive: true });
+    const newState = path.join(newRoot, 'State');
+    let copied = 0, skipped = 0;
+    const copyTree = (src, dst) => {
+      fs.mkdirSync(dst, { recursive: true });
+      for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+        const sp = path.join(src, entry.name);
+        const dp = path.join(dst, entry.name);
+        if (entry.isDirectory()) copyTree(sp, dp);
+        else if (entry.isFile()) {
+          if (fs.existsSync(dp)) { skipped++; continue; }
+          fs.copyFileSync(sp, dp);
+          copied++;
+        }
+      }
+    };
+    copyTree(oldState, newState);
+    console.log(`  ✓ Copied ${copied} file(s); skipped ${skipped} that already existed at target.`);
+  }
+
+  if (persistEnv) {
+    const env = persistGlobalRootEnv(newRoot);
+    console.log('');
+    console.log(`  ${env.ok ? '✓' : '⚠'} ${env.message}`);
+  }
+
+  console.log('');
+  console.log(`  Verify with: kushi global status`);
+  console.log(`  Old root preserved at: ${oldRoot}`);
+  console.log(`  Once verified, you can delete the old State/ folder there.`);
+  console.log('');
+}
+
+export async function runGlobalSetRoot(newRootArg, opts = {}) {
+  if (!newRootArg || !newRootArg.trim()) {
+    console.error('\n  Usage: kushi global set-root <path> [--scope workspace|home]\n');
+    console.error('  Persists the global wiki root.');
+    console.error('  Default scope = workspace if a .kushi/ is found above cwd, else home.');
+    console.error('  Effect is immediate — no shell restart needed.\n');
+    process.exitCode = 1;
+    return;
+  }
+  const newRoot = path.resolve(newRootArg.trim());
+  const env = persistGlobalRootEnv(newRoot, { scope: opts.scope || 'auto' });
+  console.log('');
+  console.log(`  Target: ${newRoot}`);
+  console.log(`  Scope : ${env.scope || '(none)'}`);
+  console.log(`  ${env.ok ? '✓' : '⚠'} ${env.message}`);
+  if (!fs.existsSync(path.join(newRoot, 'State'))) {
+    console.log('');
+    console.log(`  Note: ${newRoot}/State/ does not exist yet. Run \`kushi global init\` to create it.`);
+  }
+  console.log('');
+}
+
+/**
+ * Show the resolution chain for the global wiki root: env var → config file → default.
+ * Helps users figure out why kushi is reading/writing where it is.
+ */
+export async function runGlobalShowRoot() {
+  const explain = explainGlobalRoot();
+  console.log('');
+  console.log(`  Resolved global root: ${explain.resolved}`);
+  console.log(`  Winning source      : ${explain.winner ? explain.winner.source : 'default'}`);
+  console.log('');
+  console.log('  Resolution chain (first non-empty wins):');
+  for (const s of explain.sources) {
+    const mark = explain.winner && explain.winner.source === s.source ? '→' : ' ';
+    const val = s.value ? s.value : '(unset)';
+    console.log(`    ${mark} [${s.source}] ${s.key}`);
+    console.log(`        ${val}`);
+  }
+  console.log('');
+  console.log(`  Config file (home): ${userConfigPath()}`);
+  console.log('  Change with: kushi global set-root <path>     (workspace shared if available, else home)');
+  console.log('               kushi global set-root <path> --scope home');
+  console.log('  Or override: $env:KUSHI_GLOBAL_ROOT = "..."   (env var wins for current shell)');
+  console.log('');
+}
+
+
+function expandIfTilde(p) {
+  if (typeof p !== 'string') return p;
+  if (p.startsWith('~')) {
+    const home = process.env.USERPROFILE || process.env.HOME || os.homedir();
+    return path.join(home, p.slice(1).replace(/^[\\/]/, ''));
+  }
+  return p;
+}
+
+/**
+ * One-shot deterministic "do the wiki" verb.
+ *
+ * - Resolves the global root via the 4-tier chain (env > workspace shared > home > default).
+ * - If the State/ scaffold is missing, runs `globalInit` to create it.
+ * - Prints the resolved root, winning source, status counts, and a clickable
+ *   `file://` URL so the user can open the wiki immediately.
+ * - Idempotent: safe to re-run on every "do wiki" / "refresh wiki" / "create wiki".
+ */
+export async function runWiki() {
+  const explain = explainGlobalRoot();
+  const winner = explain.winner;
+  const root = winner ? expandIfTilde(winner.value) : explain.resolved;
+  const stateDir = path.join(root, 'State');
+  const initiallyMissing = !fs.existsSync(stateDir);
+
+  console.log('');
+  console.log(`  Wiki root      : ${root}`);
+  console.log(`  Winning source : ${winner ? winner.source : 'default'}`);
+
+  let initResult = null;
+  if (initiallyMissing) {
+    initResult = globalInit({ root });
+    console.log(`  Scaffold       : created ${initResult.created.length} file(s)`);
+  } else {
+    initResult = globalInit({ root });
+    if (initResult.created.length) {
+      console.log(`  Scaffold       : top-up — added ${initResult.created.length} missing file(s)`);
+    } else {
+      console.log(`  Scaffold       : already present (${initResult.skipped.length} files intact)`);
+    }
+  }
+
+  const status = globalStatus({ root });
+  console.log('');
+  console.log(`  Pages          : ${status.counts.pages}`);
+  console.log(`  Answers        : ${status.counts.answers}`);
+  console.log(`  Reports        : ${status.counts.reports}`);
+  console.log(`  Open review    : ${status.counts.review_items}`);
+  if (status.newest_iso) console.log(`  Newest entry   : ${status.newest_iso}`);
+
+  const indexFile = path.join(stateDir, 'index.md');
+  const fileUrl = 'file:///' + indexFile.replace(/\\/g, '/').replace(/^\/+/, '');
+  console.log('');
+  console.log(`  Open the wiki  : ${fileUrl}`);
+  console.log(`  Local path     : ${indexFile}`);
+  console.log('');
+  console.log('  Next:');
+  console.log('    kushi global ask <question>           Ask the wiki');
+  console.log('    kushi promote <project> <page>        Promote a project page');
+  console.log('    kushi global lint                     Privacy + freshness scan');
+  console.log('    kushi global show-root                Inspect the resolution chain');
+  console.log('');
+}
+
 export async function runGlobalStatus() {
   const status = globalStatus();
   console.log('');

package/src/global-wiki.mjs

@@ -85,18 +85,150 @@ Open items that need your attention. Populated by:
 
 const SCAFFOLD_DIRS = ['answers', 'reports'];
 
+// ───────────────────────────────────────────────────────────────────────────
+// Per-user config file
+//
+// Kushi has TWO levels of config that can carry settings like `globalRoot`:
+//
+//   workspace/shared : <cwd>/.kushi/config/shared/kushi.yml
+//                      Team-shared (committed). Seeded by installer.
+//                      Found by walking up from cwd looking for .kushi/.
+//
+//   home (per-user)  : ~/.kushi/config.json
+//                      Last-resort fallback when not inside a workspace.
+//                      Also seeded by installer.
+//
+// Resolution order for the global wiki root:
+//   1. $KUSHI_GLOBAL_ROOT          (env override; tests, ad-hoc redirects)
+//   2. workspace shared kushi.yml  (team-shared persistent setting)
+//   3. ~/.kushi/config.json        (per-machine persistent setting)
+//   4. ~/.kushi-global/            (default)
+//
+// The shared file follows the same seed-once contract as integrations.yml:
+// preserved on every reinstall unless --force.
+
+export function userConfigPath(env = process.env) {
+  const home = env.USERPROFILE || env.HOME || os.homedir();
+  return path.join(home, '.kushi', 'config.json');
+}
+
+export function readUserConfig(env = process.env) {
+  const f = userConfigPath(env);
+  if (!fs.existsSync(f)) return {};
+  try { return JSON.parse(fs.readFileSync(f, 'utf8')) || {}; }
+  catch { return {}; }
+}
+
+export function writeUserConfig(patch, env = process.env) {
+  const f = userConfigPath(env);
+  fs.mkdirSync(path.dirname(f), { recursive: true });
+  const cur = readUserConfig(env);
+  const next = { ...cur, ...patch };
+  fs.writeFileSync(f, JSON.stringify(next, null, 2) + '\n', 'utf8');
+  return { path: f, config: next };
+}
+
+/**
+ * Walk up from cwd to find the nearest workspace `.kushi/config/shared/kushi.yml`.
+ * Returns absolute path or null.
+ */
+export function findWorkspaceSharedConfig(startDir = process.cwd()) {
+  let dir = path.resolve(startDir);
+  const root = path.parse(dir).root;
+  while (true) {
+    const candidate = path.join(dir, '.kushi', 'config', 'shared', 'kushi.yml');
+    if (fs.existsSync(candidate)) return candidate;
+    if (dir === root) return null;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * Tiny tolerant reader for the shared kushi.yml file. Only reads top-level
+ * scalar keys (globalRoot today). Avoids adding a YAML dep to src/.
+ *
+ *   globalRoot: 'C:\path\to\wiki'   → "C:\\path\\to\\wiki"
+ *   globalRoot: null                 → null (treated as unset)
+ *   globalRoot: ~                    → null (yaml shorthand for null)
+ *   globalRoot:                      → null (empty value)
+ */
+export function readWorkspaceSharedConfig(file) {
+  if (!file || !fs.existsSync(file)) return {};
+  const txt = fs.readFileSync(file, 'utf8');
+  const obj = {};
+  for (const rawLine of txt.split(/\r?\n/)) {
+    const line = rawLine.replace(/\s+#.*$/, '').trim();
+    if (!line || line.startsWith('#')) continue;
+    const m = line.match(/^([A-Za-z_][\w-]*)\s*:\s*(.*)$/);
+    if (!m) continue;
+    const key = m[1];
+    let val = m[2].trim();
+    if (val === '' || val === '~' || val.toLowerCase() === 'null') { obj[key] = null; continue; }
+    if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+      val = val.slice(1, -1);
+    }
+    obj[key] = val;
+  }
+  return obj;
+}
+
+export function writeWorkspaceSharedConfig(file, patch) {
+  let txt = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+  for (const [k, v] of Object.entries(patch)) {
+    const valStr = (v === null || v === undefined || v === '')
+      ? 'null'
+      : (/^[\w./\\:~+\-]+$/.test(String(v)) ? String(v) : `'${String(v).replace(/'/g, "''")}'`);
+    const re = new RegExp(`^${k}\\s*:.*$`, 'm');
+    if (re.test(txt)) txt = txt.replace(re, `${k}: ${valStr}`);
+    else txt += (txt.endsWith('\n') ? '' : '\n') + `${k}: ${valStr}\n`;
+  }
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, txt, 'utf8');
+  return { path: file };
+}
+
 // ───────────────────────────────────────────────────────────────────────────
 // Resolution
 
-export function resolveGlobalRoot(env = process.env) {
+export function resolveGlobalRoot(env = process.env, opts = {}) {
   const override = env.KUSHI_GLOBAL_ROOT;
   if (override && override.trim()) {
     return path.resolve(expandTilde(override.trim(), env));
   }
+  const wsFile = findWorkspaceSharedConfig(opts.cwd || process.cwd());
+  if (wsFile) {
+    const ws = readWorkspaceSharedConfig(wsFile);
+    if (ws.globalRoot && typeof ws.globalRoot === 'string' && ws.globalRoot.trim()) {
+      return path.resolve(expandTilde(ws.globalRoot.trim(), env));
+    }
+  }
+  const cfg = readUserConfig(env);
+  if (cfg.globalRoot && typeof cfg.globalRoot === 'string' && cfg.globalRoot.trim()) {
+    return path.resolve(expandTilde(cfg.globalRoot.trim(), env));
+  }
   const home = env.USERPROFILE || env.HOME || os.homedir();
   return path.join(home, '.kushi-global');
 }
 
+/**
+ * Returns the full resolution chain so `kushi global show-root` can display it.
+ */
+export function explainGlobalRoot(env = process.env, opts = {}) {
+  const home = env.USERPROFILE || env.HOME || os.homedir();
+  const wsFile = findWorkspaceSharedConfig(opts.cwd || process.cwd());
+  const wsVal = wsFile ? (readWorkspaceSharedConfig(wsFile).globalRoot || null) : null;
+  const sources = [
+    { source: 'env',       key: 'KUSHI_GLOBAL_ROOT',                        value: env.KUSHI_GLOBAL_ROOT || null },
+    { source: 'workspace', key: wsFile ? `${wsFile} → globalRoot` : '(no workspace .kushi/config/shared/kushi.yml found)', value: wsVal, file: wsFile },
+    { source: 'home',      key: `${userConfigPath(env)} → globalRoot`,      value: readUserConfig(env).globalRoot || null },
+    { source: 'default',   key: '~/.kushi-global',                          value: path.join(home, '.kushi-global') },
+  ];
+  const winner = sources.find(s => s.value && String(s.value).trim());
+  return { resolved: resolveGlobalRoot(env, opts), winner, sources };
+}
+
 function expandTilde(p, env) {
   if (p.startsWith('~')) {
     const home = env.USERPROFILE || env.HOME || os.homedir();

package/src/seed-config.mjs

@@ -99,6 +99,34 @@ export function seedConfig(sourcePkgDir, destAbsolute) {
   return result;
 }
 
+/**
+ * Seed ~/.kushi/config.json (per-user, per-machine settings) using the same
+ * seed-once contract as workspace user/ files: copied only if absent, preserved
+ * on reinstall unless `force: true` is passed.
+ *
+ *   - Lives at <home>/.kushi/config.json (NOT inside a workspace .kushi/).
+ *   - Template ships at plugin/templates/user-config.json.
+ *   - Currently holds `globalRoot` (path to the global wiki). Designed to grow.
+ *
+ * @param {string} sourcePkgDir  – root of the npm package
+ * @param {{ force?: boolean, home?: string }} [opts]
+ * @returns {{ path: string, action: 'seeded'|'preserved'|'overwritten'|'no-template' }}
+ */
+export function seedGlobalUserConfig(sourcePkgDir, opts = {}) {
+  const home = opts.home || os.homedir();
+  const dst = path.join(home, '.kushi', 'config.json');
+  const src = path.join(sourcePkgDir, PLUGIN_SOURCE_DIR, 'templates', 'user-config.json');
+  if (!fs.existsSync(src)) return { path: dst, action: 'no-template' };
+  fs.mkdirSync(path.dirname(dst), { recursive: true });
+
+  const exists = fs.existsSync(dst);
+  if (exists && !opts.force) {
+    return { path: dst, action: 'preserved' };
+  }
+  fs.cpSync(src, dst, { force: true });
+  return { path: dst, action: exists ? 'overwritten' : 'seeded' };
+}
+
 /**
  * Mechanically derive defaults for freshly-seeded user-config files.
  * Only modifies files in `seededFiles` (i.e. just-created in this run).

package/src/setup-wizard.mjs

@@ -73,6 +73,17 @@ export async function runSetupWizard({ args = [] } = {}) {
   const root  = (await p.ask('  Where is your engagement root?', detectedRoot, 'KUSHI_WIZARD_ROOT')) || detectedRoot;
   const hosts = (await p.ask('  Install for clawpilot / vscode / both?', detectedHosts, 'KUSHI_WIZARD_HOSTS')) || detectedHosts;
   const wantGlobal = (await p.ask('  Enable global wiki at ~/.kushi-global/?', 'y', 'KUSHI_WIZARD_GLOBAL')) || 'y';
+  let globalRootChoice = '';
+  if (/^y/i.test(wantGlobal)) {
+    const envRoot = process.env.KUSHI_GLOBAL_ROOT || '';
+    const defaultRoot = envRoot || '(default ~/.kushi-global/)';
+    globalRootChoice = (await p.ask(
+      '  Global wiki path? (Enter for default; or a OneDrive-synced SharePoint folder for team sharing)',
+      defaultRoot,
+      'KUSHI_WIZARD_GLOBAL_ROOT',
+    )) || defaultRoot;
+    if (globalRootChoice === '(default ~/.kushi-global/)') globalRootChoice = '';
+  }
   const wantWorkspace = (await p.ask(
     `  Scaffold current directory (${cwd}) as a kushi workspace?${cwdHasKushi ? ' (already present)' : ''}`,
     defaultWorkspace,
@@ -85,6 +96,7 @@ export async function runSetupWizard({ args = [] } = {}) {
     engagementRoot: root,
     hosts: hosts.toLowerCase(),
     globalWiki: /^y/i.test(wantGlobal),
+    globalWikiRoot: globalRootChoice ? globalRootChoice.trim() : '',
     workspaceInstall: /^y/i.test(wantWorkspace),
     workspacePath: cwd,
   };
@@ -128,7 +140,7 @@ export async function runSetupWizard({ args = [] } = {}) {
   if (answers.globalWiki) {
     try {
       const { runGlobalInit } = await import('./global-wiki-cli.mjs');
-      await runGlobalInit();
+      await runGlobalInit({ root: answers.globalWikiRoot || undefined, persistEnv: !!answers.globalWikiRoot });
     } catch (err) {
       console.error(`  global init skipped: ${err.message}`);
     }