kushi-agents 4.2.3 → 4.4.0

package/.github/copilot-instructions.kushi.md

@@ -2,9 +2,9 @@
 
 This workspace has [Kushi](https://gim-home.github.io/kushi/) installed under `.kushi/`. Kushi captures multi-source project evidence (Email, Teams, OneNote, SharePoint, Meetings, CRM, ADO) via **WorkIQ** and answers cited questions over the captured evidence.
 
-### Routing — no `@Kushi` prefix required
+### Routing — verbs are prompts
 
-When the user types any of the following verbs followed by a project name, route to the corresponding Kushi prompt in `.kushi/prompts/` (no `@Kushi` needed):
+Every Kushi verb is a **prompt file** in `.kushi/prompts/<verb>.prompt.md` with `agent: kushi` in its frontmatter. When the user types one of the verbs below (with or without `@Kushi`), open the prompt and execute its instructions — do **not** shell out to `npx kushi-agents <verb>`. The `kushi-agents` npm package is the installer that put `.kushi/` on disk; it does not run verbs.
 
 | Verb                       | Prompt to run    |
 | -------------------------- | ---------------- |
@@ -21,6 +21,8 @@ When the user types any of the following verbs followed by a project name, route
 
 Project Q&A also auto-dispatches when the user names a known project under the engagement root **and** asks a question about it — no prefix needed.
 
+If a prompt file is missing for a verb the user typed, tell them "the `<verb>` prompt isn't installed in this profile" — do not shell out to reinstall. Re-installing is only appropriate when the user **explicitly** says "install kushi", "upgrade kushi", or "reinstall kushi".
+
 ### Hard rules (enforced by Kushi skills)
 
 - **WorkIQ-first** for all M365 sources. `m365_*` / Microsoft Graph calls are only allowed as a classified fallback after a documented WorkIQ failure.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kushi-agents",
-  "version": "4.2.3",
+  "version": "4.4.0",
   "description": "Install Kushi — multi-source project evidence agent with snapshot+stream capture across Email, Teams, OneNote, SharePoint, Meetings, CRM, ADO. WorkIQ-only for M365 sources (Graph / m365_* FORBIDDEN as fallbacks; user-paste is first-class). Host-agnostic.",
   "type": "module",
   "bin": {
@@ -10,8 +10,6 @@
     "bin/",
     "src/",
     "plugin/",
-    ".github/config/m365-auth.json.example",
-    ".github/config/m365-mutable.json.example",
     ".github/copilot-instructions.kushi.md"
   ],
   "engines": {
@@ -43,7 +41,7 @@
   },
   "license": "MIT",
   "scripts": {
-    "test": "node --test src/check-workiq.test.mjs",
+    "test": "node --test src/check-workiq.test.mjs src/seed-config.test.mjs",
     "smoke": "node scripts/smoke.mjs",
     "prepublishOnly": "npm test && npm run smoke"
   },

package/plugin/agents/kushi.agent.md

@@ -1,11 +1,14 @@
 ---
+name: Kushi
 description: "Kushi — multi-source project evidence + Q&A agent. Snapshot + stream capture across Email, Teams, OneNote, SharePoint, Meetings, CRM, ADO; plus read-only natural-language Q&A over the captured evidence. WorkIQ-first for capture, citation-only for answers. Host-agnostic. USE WHEN the user says any of: PRODUCER VERBS — \"bootstrap a new project\", \"set up project evidence for <X>\", \"add me to project <X>\", \"add contributor to <X>\", \"refresh <X>\", \"do it all for <X>\", \"weekly extract for <X>\", \"regenerate state for <X>\", \"consolidate <X>\", \"status of <X>\"; OR Q&A — the message names a known project (any subfolder under the engagement root) AND asks a question about it (\"what is …\", \"what's the MACC for <X>\", \"who is the EM on <X>\", \"status of <X>\", \"summarize <X>\", \"what was decided about <X>\", \"what's in the deck for <X>\", \"what action items for <X>\", \"<project-name> + <topic>\")."
-tools: ["*"]
+argument-hint: "Name a project (e.g. 'bootstrap HCA', 'refresh AGCO last 14 days', 'ask HCA what's the MACC?'). Kushi routes to the right verb prompt — never run `npx kushi-agents <verb>` in the terminal."
+tools:
+  [vscode/vscodeAPI, execute/getTerminalOutput, execute/runInTerminal, read/readFile, read/terminalSelection, read/terminalLastCommand, agent, edit, search, web, browser, 'workiq/*', 'github/*']
 ---
 
 # @Kushi — Project Evidence Orchestrator
 
-Kushi is a multi-source evidence + state agent for consulting / engineering engagements. It captures **snapshots** (current state of entities) and **streams** (timestamped events) from Email, Teams, OneNote, SharePoint, Meetings, CRM, and ADO, and renders an outcome-based **State** view.
+Kushi is a multi-source evidence + state agentfor consulting / engineering engagements. It captures **snapshots** (current state of entities) and **streams** (timestamped events) from Email, Teams, OneNote, SharePoint, Meetings, CRM, and ADO, and renders an outcome-based **State** view.
 
 ## Install profiles
 
@@ -95,8 +98,8 @@ When a user message arrives:
 ## Configuration layout
 
 ```
-<workspace>/.kushi/config/project-evidence.yml     ← personal: alias, engagement_root, active_projects (seeded by installer; never overwritten)
-<workspace>/.kushi/config/integrations.yml         ← optional global CRM/ADO defaults (seeded by installer; never overwritten)
+<workspace>/.kushi/config/user/project-evidence.yml     ← personal: alias, engagement_root, active_projects (seeded by installer; never overwritten)
+<workspace>/.kushi/config/shared/integrations.yml         ← optional global CRM/ADO defaults (seeded by installer; never overwritten)
 <engagement-root>/.project-evidence/                ← per-machine, per-user M365 + CRM + ADO config (OneDrive-synced)
    m365/m365-auth.json
    m365/m365-mutable.json

package/plugin/instructions/azure-auth-patterns.instructions.md

@@ -227,7 +227,7 @@ Maintained alongside `auth-and-retry §3` (canonical) — quick lookup:
 | Dynamics 365 / CRM | `<engagement-root>/.project-evidence/crm/config.yml` |
 | Azure DevOps | `<engagement-root>/.project-evidence/ado/config.yml` |
 | Microsoft Graph / M365 / OneNote | `<engagement-root>/.project-evidence/m365/m365-mutable.json` + `<engagement-root>/.project-evidence/m365/m365-auth.json` |
-| WorkIQ CLI path | `<workspace>/.kushi/config/project-evidence.yml` (workspace-scoped) |
-| Global integrations (optional) | `<workspace>/.kushi/config/integrations.yml` |
+| WorkIQ CLI path | `<workspace>/.kushi/config/user/project-evidence.yml` (workspace-scoped) |
+| Global integrations (optional) | `<workspace>/.kushi/config/shared/integrations.yml` |
 
 Always read tenant IDs, resource URLs, org URLs, and allowed-tenant lists from these files at the start of each run. **Never hardcode them in skills or prompts.** The only acceptable literal in instructions/prompts is the public Microsoft tenant ID `72f988bf-86f1-41af-91ab-2d7cd011db47` in the user-facing `az login --tenant ...` suggestion text.

package/plugin/instructions/bootstrap-status-format.instructions.md

@@ -79,6 +79,30 @@ Use these exact strings everywhere (table cells, run-log, narrative):
 - `ado-not-complete` — engagement record not found yet OR ADO linkage missing
 - `completed-with-coverage-gaps` — final outcome with explicit gaps recorded
 
+## Multi-contributor safety (kushi v4.4.0+)
+
+`<project>/bootstrap-status.md` is shared across all contributors via OneDrive. Per `multi-user-shared-files.instructions.md`:
+
+1. **Before writing**, scan `<project>/` for sibling conflict copies (e.g. `bootstrap-status-conflict-<alias>-<host>.md` or OneDrive's `bootstrap-status (Stan's conflicted copy *)`). If any exist, merge their content into the canonical file (taking the most recent per-source row) and delete the conflict copies. Log this in the per-user bootstrap report under `## Conflict copies merged`.
+2. **Preserve other contributors' attribution.** Read the existing file; the `## Contributors who have bootstrapped this project` section MUST keep one row per alias that has ever written it. Update only the row matching the current alias.
+3. **Per-source rows** in `## Context Artifact Status` reflect the most recent discovery across all contributors. Add a trailing `Discovered by` column showing which alias performed the latest discovery (cross-referenced from each alias's `m365-mutable.json` via `Get-KushiConfig`).
+4. **The final one-line status** is for the most recent run only and may be overwritten by any contributor.
+
+### Required `## Contributors who have bootstrapped this project` section
+
+Append this section immediately after `## Bootstrap Status`:
+
+```
+## Contributors who have bootstrapped this project
+
+| Alias | Display Name | Last Run | Mode | Outcome |
+|---|---|---|---|---|
+| ushak | Usha Kandregula | 2026-05-20 07:42 EDT | bootstrap | bootstrap-complete-with-coverage-gaps |
+| stand | Stan Doe       | 2026-05-18 16:01 EDT | refresh   | refresh-complete |
+```
+
+Preserve every existing row except the one matching your alias.
+
 ## Sections to AVOID in bootstrap-status
 
 Do NOT keep these in `bootstrap-status.md` (they belong elsewhere or become stale):

package/plugin/instructions/engagement-root-resolution.instructions.md

@@ -11,9 +11,9 @@ The **engagement-root** is the parent folder that contains all of the user's eng
 
 Resolve `<engagement-root>` in this order — first match wins:
 
-1. **`<workspace>/.kushi/config/project-evidence.yml`** — read `engagement_root:` field (preferred).
+1. **`<workspace>/.kushi/config/user/project-evidence.yml`** — read `engagement_root:` field (preferred).
 2. **`customer_workspace/FDEDocs/`** — if the user's workspace has this symlink, follow it. Common in FDE-style installs.
-3. **Ask the user** once and persist the answer to `<workspace>/.kushi/config/project-evidence.yml engagement_root`.
+3. **Ask the user** once and persist the answer to `<workspace>/.kushi/config/user/project-evidence.yml engagement_root`.
 
 ## Live config location
 
@@ -43,7 +43,7 @@ Once `<engagement-root>` is known, individual projects are subfolders:
 Project name resolution (always fuzzy):
 
 1. Match against keys in `<engagement-root>/.project-evidence/m365/m365-mutable.json m365Mutable.knownSections`.
-2. Match against `active_projects:` in `<workspace>/.kushi/config/project-evidence.yml`.
+2. Match against `active_projects:` in `<workspace>/.kushi/config/user/project-evidence.yml`.
 3. Match against actual subfolder names under `<engagement-root>`.
 
 Case-insensitive; ranking `exact > prefix > contains`. Multiple plausible candidates → ask user to pick. Zero candidates AND verb is `bootstrap` → create the folder. Zero candidates AND verb is anything else → ask user.

package/plugin/instructions/identity-resolution.instructions.md

@@ -1,6 +1,6 @@
 ---
 applyTo: "**"
-description: "Identity auto-resolution — Kushi never asks the user for alias / email / display_name. On the first bootstrap (or whenever those fields are <auto> / placeholder in .kushi/config/project-evidence.yml), Kushi resolves them from WorkIQ in a single call, persists them, and continues. Skipped entirely if the user has set explicit values."
+description: "Identity auto-resolution — Kushi never asks the user for alias / email / display_name. On the first bootstrap (or whenever those fields are <auto> / placeholder in .kushi/config/user/project-evidence.yml), Kushi resolves them from WorkIQ in a single call, persists them, and continues. Skipped entirely if the user has set explicit values."
 ---
 
 # Identity Resolution — Don't Ask, Probe
@@ -9,7 +9,7 @@ Kushi must not prompt the user for `alias`, `email`, or `display_name`. These ar
 
 ## When to resolve
 
-On the **first step of every prompt** that reads contributor identity (bootstrap, refresh, aggregate, ask, fde-*, propose-ado, apply-ado), check `<workspace>/.kushi/config/project-evidence.yml`:
+On the **first step of every prompt** that reads contributor identity (bootstrap, refresh, aggregate, ask, fde-*, propose-ado, apply-ado), check `<workspace>/.kushi/config/user/project-evidence.yml`:
 
 * If `alias`, `email`, or `display_name` is **missing**, set to `<auto>`, or matches a placeholder pattern (`<your-alias>`, `<Your Full Name>`, `your.email@example.com`) → **resolve from WorkIQ**.
 * If all three are explicit non-placeholder values → **skip**. Respect the user's override.
@@ -32,9 +32,9 @@ Map the response:
 
 ## After resolution
 
-1. **Persist back** to `<workspace>/.kushi/config/project-evidence.yml` (preserving comments + indentation). The user sees the resolved values on next open; no surprise.
+1. **Persist back** to `<workspace>/.kushi/config/user/project-evidence.yml` (preserving comments + indentation). The user sees the resolved values on next open; no surprise.
 2. **Echo back** to the user, one line:
-   > ✓ Identity: `Alex Smith <alex@microsoft.com>` (alias=`alex`). Edit `.kushi/config/project-evidence.yml` to override.
+   > ✓ Identity: `Alex Smith <alex@microsoft.com>` (alias=`alex`). Edit `.kushi/config/user/project-evidence.yml` to override.
 3. **Continue** the prompt.
 
 ## Failure modes

package/plugin/instructions/multi-user-shared-files.instructions.md

@@ -0,0 +1,87 @@
+---
+applyTo: "**/SKILL.md,**/*.prompt.md,**/Evidence/run-log.yml,**/integrations.yml,**/bootstrap-status.md,**/OPEN-QUESTIONS-DRAFT.md,**/State/09_open-questions.md,**/Evidence/contributors.yml"
+---
+
+# Multi-user shared-file safety
+
+## Why this exists
+
+A Kushi engagement folder (`<engagement-root>/<project>/`) is shared across all contributors via OneDrive. Several artifacts inside it are **logically shared** — every contributor reads and writes the same path:
+
+| Shared artifact | Path | Writers |
+|---|---|---|
+| Per-project integrations | `<project>/integrations.yml` | `bootstrap-project`, `propose-ado-update`, `apply-ado-update`, every `pull-*` that discovers an ID |
+| Bootstrap status snapshot | `<project>/bootstrap-status.md` | `bootstrap-project` (every run, any contributor) |
+| Open questions draft | `<project>/OPEN-QUESTIONS-DRAFT.md` (or `State/09_open-questions.md` on full profile) | `bootstrap-project`, `consolidate-evidence`, `build-state`, `propose-ado-update` |
+| Run log | `<project>/Evidence/run-log.yml` | every `pull-*`, `bootstrap-project`, `refresh-project`, `fde-*` |
+| Contributors list | `<project>/Evidence/contributors.yml` | every `pull-*` (first time an alias touches the project) |
+
+Without rules, two contributors running concurrently produce one of:
+- OneDrive conflict-copy (`*-conflict-<alias>-<host>.yml`) — silent loss until manually merged.
+- Last-writer-wins overwrite — silent loss of the other contributor's data.
+
+This doctrine codifies the contract every writer must honor. It is **not** a substitute for proper locking, but it makes concurrent runs eventually consistent and recoverable.
+
+## Universal rules (apply to every shared artifact)
+
+1. **Read-modify-write, never blind-write.** Before writing any shared artifact, the skill MUST read the current file, merge its new contribution, and write the merged result. Blind overwrite is forbidden.
+2. **Detect and absorb conflict-copies.** Before reading the canonical file, glob for sibling files matching `<basename>-conflict-*` or `<basename> (<host>'s conflicted copy *)`. If any exist, merge their contents into the canonical file, then delete the conflict copies. Log the merge in the run report.
+3. **Stamp every contribution.** Every line / block / list-entry that a skill adds must carry its alias (from `project-evidence.yml`) and an ISO timestamp so future readers (and the merge logic above) can deterministically reconcile.
+4. **Idempotent appends.** Re-running the same skill in the same window MUST NOT duplicate prior entries. Use a `(alias, source, window_key)` tuple as the dedupe key.
+5. **Never delete another contributor's contribution.** A skill may only modify or remove entries it created (matched by alias). Cleanup of other aliases' entries is reserved for `consolidate-evidence`.
+
+## Per-artifact contracts
+
+### `<project>/integrations.yml`
+
+- **Pattern**: read-modify-write with alias stamp on changed fields.
+- Whenever a skill discovers a new ID (CRM `record_id`, ADO `engagement_id`, OneNote `section_file_id`, etc.), it MUST:
+  1. Read the current file.
+  2. If the target field is non-empty AND differs from the discovered value, write the discovered value into a sibling key `<field>_proposed_<alias>` and add a Q-row to `OPEN-QUESTIONS-DRAFT.md` for human reconciliation. Do not overwrite.
+  3. If the target field is empty (or matches), write the value and append a comment line: `# resolved by <alias> on <YYYY-MM-DD>` immediately above the changed key.
+- The `last_discovery_attempt` / `last_discovery_result` keys MAY be overwritten by any alias (they are intentionally last-writer-wins; the value is "the most recent attempt by anyone").
+
+### `<project>/bootstrap-status.md`
+
+- **Pattern**: full rewrite is permitted, but the file MUST carry a `## Contributors who have bootstrapped this project` section listing every alias that has ever written it, with their last-run timestamp.
+- Before rewriting, the skill MUST read the existing Contributors section and preserve every entry whose alias differs from the current alias. Update only its own alias row.
+- The per-source status tables (`OneNote`, `Email`, `Teams`, etc.) reflect the **most recent** discovery across all contributors. Skills MUST cross-reference `m365-mutable.json` (which is per-user) — when a row shows discovered IDs, also note which alias performed the discovery in a trailing `(by <alias>)` cell.
+
+### `<project>/OPEN-QUESTIONS-DRAFT.md` and `<project>/State/09_open-questions.md`
+
+- **Pattern**: append-only with dedup.
+- Every question row carries `[asked by <alias> on <YYYY-MM-DD>]` as the trailing column.
+- Before appending a new question, the skill MUST scan existing rows for a question whose normalized text (lowercased, whitespace-collapsed) matches. If a match exists, do not append a duplicate; instead, append `, <alias> on <date>` to the existing row's attribution.
+- Rows are removed only by an explicit `resolve-open-question` action (out of scope here) — never by another `bootstrap` / `refresh` run.
+
+### `<project>/Evidence/run-log.yml`
+
+- **Pattern**: structured append + max() merge.
+- Run history (`runs:` list) is append-only. Every entry carries `alias:` and `run_at:`.
+- Per-source watermarks (`sources.<source>.watermark`) use **max()** merge: when writing, the skill reads the current value and writes `max(current, new)`. Never overwrite with an older watermark.
+- Per-source errors (`sources.<source>.errors[]`) are append-only with `alias` + `at` on every entry; dedup on `(alias, code, at)`.
+
+### `<project>/Evidence/contributors.yml`
+
+- **Pattern**: append-only, alias-keyed.
+- The first time an alias runs against the project, append `{ alias, display_name, email, first_seen: <YYYY-MM-DD> }`. Subsequent runs MUST NOT modify the entry.
+- `last_seen` MAY be updated by any run, max()-merged.
+
+## Implementation guidance for skill authors
+
+- Read `<workspace>/.kushi/config/user/project-evidence.yml` to get your alias via `Get-KushiConfig -Name 'project-evidence'`. Never hardcode aliases.
+- For YAML merges, use `Get-Content -Raw | ConvertFrom-Yaml`, mutate, then `ConvertTo-Yaml`. Preserve comments where possible by line-based merging when structure permits.
+- For Markdown table merges in `OPEN-QUESTIONS-DRAFT.md`, parse the body to a list of rows, dedup by normalized question text, re-emit.
+- On any merge conflict the skill cannot resolve deterministically, write the alternative as a sibling-key `<field>_proposed_<alias>` (for YAML) or a `> Disagreement: <alias-A> says ..., <alias-B> says ...` callout (for Markdown) and add a Q-row to `OPEN-QUESTIONS-DRAFT.md`.
+
+## Out of scope
+
+- True file locking (filesystem advisory locks, OneDrive's checkout API) — relies on platform support Kushi can't assume.
+- Server-side merge service — Kushi is local-only by design.
+
+## Related doctrine
+
+- `evidence-layout-canonical.instructions.md` — what lives where under `Evidence/`.
+- `run-reports.instructions.md` — per-user run narrative (always under `Evidence/<alias>/`, no concurrency risk).
+- `bootstrap-status-format.instructions.md` — format contract for the shared status artifact.
+- `citation-ledger.instructions.md` — every assertion in shared artifacts must carry a citation; alias attribution is the citation for shared-file entries.

package/plugin/instructions/run-reports.instructions.md

@@ -24,7 +24,7 @@ Critical for multi-user projects: each contributor's runs are independent, and e
   YYYY-MM-DD-HHmm_<mode>.md
 ```
 
-- `<alias>` — the contributor running the skill (from `<workspace>/.kushi/config/project-evidence.yml#alias`).
+- `<alias>` — the contributor running the skill (from `<workspace>/.kushi/config/user/project-evidence.yml#alias`).
 - `<mode>` — one of `bootstrap`, `refresh`, `force-refresh`, `consolidate`.
 - Timestamp uses the **start time** of the run, in local time, format `YYYY-MM-DD-HHmm` (no seconds, no timezone — local-time prefix is enough for chronological sort).
 

package/plugin/instructions/side-by-side-config.instructions.md

@@ -5,20 +5,23 @@ description: "Side-by-side config rule — whenever the skill creates or changes
 
 # Side-by-side config rule (HARD RULE)
 
-Whenever the skill creates, changes, or extends any template in `<KUSHI_ROOT>/plugin/templates/init/`, it MUST also write the corresponding live file under `<engagement-root>/.project-evidence/`.
+Whenever the skill creates, changes, or extends any template in `<KUSHI_ROOT>/plugin/templates/init/`, it MUST also write the corresponding live file in the workspace under `<workspace>/.kushi/config/user/` (for per-contributor identity + paths) or `<workspace>/.kushi/config/shared/` (for team-owned config the team commits).
 
 Templates stay generic; the live file gets the actual filled-in fact. Never leave the user with only the template — that's a half-done config.
 
-## The two layers
+## The three layers
 
 | Layer | Where | Lifecycle |
 |---|---|---|
 | Template (generic) | `<KUSHI_ROOT>/plugin/templates/init/*.template.{json,yml}` | Ships with kushi, never edited per-user |
-| Live filled | `<engagement-root>/.project-evidence/*.{json,yml}` | Per-user, OneDrive-synced, edited by skill + user |
+| Live shared | `<workspace>/.kushi/config/shared/*.{json,yml}` | Team-owned, committed; doctrine files overwrite on install, others seed-once |
+| Live user | `<workspace>/.kushi/config/user/*.{json,yml}` | Per-contributor, gitignored; seed-once and preserved across upgrades |
+
+Skills read configs via `<install-dest>/lib/Get-KushiConfig.ps1` which resolves `user/` first, then `shared/`.
 
 ## Discover → upsert immediately
 
-Any time the skill discovers a high-confidence fact about a project (folder id, chat id, OneNote section id, CRM record id, ADO WI id, stakeholder hint, alias) — upsert it into the live mutable file (`<engagement-root>/.project-evidence/m365/m365-mutable.json` under `m365Mutable.knownSections.<project>.<source>`) **in the same turn it was discovered**, with `discoveredOn: <today>` and `confidence: high|medium|low`.
+Any time the skill discovers a high-confidence fact about a project (folder id, chat id, OneNote section id, CRM record id, ADO WI id, stakeholder hint, alias) — upsert it into the live mutable file (`<workspace>/.kushi/config/user/m365-mutable.json` under `m365Mutable.knownSections.<project>.<source>`) **in the same turn it was discovered**, with `discoveredOn: <today>` and `confidence: high|medium|low`.
 
 Don't wait until the end of the run.
 
@@ -38,19 +41,22 @@ End every bootstrap / fix-up turn by listing the live config files (path + size
 ## Live config locations
 
 ```
-<engagement-root>/.project-evidence/
-   m365/
-      m365-auth.json          ← stable (OneDrive-synced, hand-edited mostly)
-      m365-mutable.json       ← discovered hints, auto-updated by skill
-   crm/
-      config.yml              ← Dataverse env URL, tenant, schema
-   ado/
-      config.yml              ← organization, projects, queries
-   project-evidence.yml       ← (optional) per-engagement override of personal config
+<workspace>/.kushi/config/
+   shared/                      ← committed; doctrine + team defaults
+      azuredevops.json          ← ADO org/project/field-map doctrine (overwritten on install)
+      dynamics365.json          ← CRM env/schema doctrine (overwritten on install)
+      rsi-program-catalog.json  ← RSI segment reference (overwritten on install)
+      integrations.yml          ← optional team CRM/ADO defaults (seed-once)
+      *.example                 ← reference scaffolds (overwritten on install)
+   user/                        ← gitignored; per-contributor
+      project-evidence.yml      ← your alias, engagement-root, active projects (seed-once)
+      m365-auth.json            ← your tenant, default notebook, mailbox folders (seed-once)
+      m365-mutable.json         ← discovered hints, auto-updated by skill (seed-once)
 ```
 
-## Why outside the kushi repo
+## Why side-by-side
 
-- **Multi-machine portability** — OneDrive-synced beside engagement folders, follows the user wherever they install kushi.
-- **Discoverability** — user can see/edit it next to their engagement work and inside their workspace at `<workspace>/.kushi/config/`, not buried in an OS-hidden home directory.
-- **Repo-safe** — kushi is meant to be GitHub-published; live filled configs MUST never be committed.
+- **Self-contained** — everything Kushi needs to run lives under `.kushi/`. No `.github/config/` split, no `~/.copilot/` scatter.
+- **Multi-user safe** — the `user/` tier is per-contributor and gitignored; `shared/` is committed once and stays in sync via git.
+- **Discoverable** — visible in VS Code's file tree, not buried in an OS-hidden home directory.
+- **Repo-safe** — `<workspace>/.kushi/.gitignore` (auto-written by installer) excludes `config/user/` so personal IDs never leak.

package/plugin/instructions/tracking.instructions.md

@@ -77,7 +77,7 @@ kushi_version: 4.1.0
 - Engagement root: `C:/.../Engagement Assets`
 - Project folder: `HCA Healthcare`
 - Alias: `ushak`
-- Config: `<workspace>/.kushi/config/project-evidence.yml`
+- Config: `<workspace>/.kushi/config/user/project-evidence.yml`
 
 ## Steps taken
 

package/plugin/instructions/workiq-only.instructions.md

@@ -48,7 +48,7 @@ For every M365 source in scope:
 
 ## Canonical WorkIQ commands (CODIFIED — do not re-discover)
 
-The CLI is at `<USER_HOME>\.kushi\bin\workiq.cmd` (resolved from `<workspace>/.kushi/config/project-evidence.yml workiq.cli_path`; fall back to PATH; fall back to `~/.kushi/bin/workiq.cmd`).
+The CLI is at `<USER_HOME>\.kushi\bin\workiq.cmd` (resolved from `<workspace>/.kushi/config/user/project-evidence.yml workiq.cli_path`; fall back to PATH; fall back to `~/.kushi/bin/workiq.cmd`).
 
 Invocation shape:
 
@@ -153,7 +153,7 @@ List my Teams meetings between <YYYY-MM-DD> and <YYYY-MM-DD> where the subject c
 
 Before the first WorkIQ query in a run:
 
-1. Resolve CLI path: `<workspace>/.kushi/config/project-evidence.yml workiq.cli_path` → `Get-Command workiq` → `~/.kushi/bin/workiq.cmd`. If none resolves → log `workiq-not-on-path`, write evidence file pointing at install docs, STOP this source.
+1. Resolve CLI path: `<workspace>/.kushi/config/user/project-evidence.yml workiq.cli_path` → `Get-Command workiq` → `~/.kushi/bin/workiq.cmd`. If none resolves → log `workiq-not-on-path`, write evidence file pointing at install docs, STOP this source.
 2. Probe with `workiq ask -q "ping"`. If EULA prompt → `workiq accept-eula` once, retry.
 3. Capture `--version` once into run-log for audit.
 

package/plugin/lib/Get-KushiConfig.ps1

@@ -0,0 +1,109 @@
+<#
+.SYNOPSIS
+  Resolve and load a Kushi config file from the two-tier .kushi/config/ layout.
+
+.DESCRIPTION
+  Kushi configs live in <workspace>/.kushi/config/ split across two subdirs:
+    - user/    per-contributor identity & local paths (gitignored)
+    - shared/  team-owned, safe to commit (doctrine + team defaults)
+
+  Lookup order (highest-priority first):
+    1. <workspace>/.kushi/config/user/<name>.<ext>
+    2. <workspace>/.kushi/config/shared/<name>.<ext>
+
+  By default the file is parsed (JSON or YAML inferred from extension) and
+  returned as a PowerShell object. Use -Raw for raw text, or -Path to only
+  resolve the path.
+
+  Throws if the file is missing or appears to still hold template
+  placeholder values (sentinel `__FILL_ME_IN__` or `<auto>`). Suppress with
+  -AllowPlaceholders (needed for the identity-resolution flow which fills
+  `<auto>` on first run).
+
+.PARAMETER Name
+  Logical config name, e.g. `project-evidence`, `m365-auth`, `azuredevops`.
+
+.PARAMETER Extension
+  Override extension. Defaults: yml for project-evidence/integrations; json otherwise.
+
+.PARAMETER Workspace
+  Workspace root. Defaults to the current location.
+
+.EXAMPLE
+  $auth = Get-KushiConfig -Name 'm365-auth'
+  $notebookId = $auth.m365Auth.oneNote.defaultNotebookId
+
+.EXAMPLE
+  $cfgPath = Get-KushiConfig -Name 'project-evidence' -Path
+#>
+[CmdletBinding()]
+param(
+  [Parameter(Mandatory = $true, Position = 0)]
+  [string] $Name,
+
+  [ValidateSet('json', 'yml', 'yaml')]
+  [string] $Extension,
+
+  [string] $Workspace = (Get-Location).Path,
+
+  [switch] $Raw,
+  [switch] $Path,
+  [switch] $AllowPlaceholders
+)
+
+$ErrorActionPreference = 'Stop'
+
+function Get-DefaultExtension([string] $name) {
+  if ($name -match '^(project-evidence|integrations)$') { return 'yml' }
+  return 'json'
+}
+
+$ext = if ($PSBoundParameters.ContainsKey('Extension')) { $Extension } else { Get-DefaultExtension $Name }
+$fileName = "$Name.$ext"
+
+$configRoot = Join-Path $Workspace '.kushi/config'
+$userPath   = Join-Path $configRoot (Join-Path 'user'   $fileName)
+$sharedPath = Join-Path $configRoot (Join-Path 'shared' $fileName)
+
+$resolved = $null
+if (Test-Path -LiteralPath $userPath -PathType Leaf)        { $resolved = $userPath }
+elseif (Test-Path -LiteralPath $sharedPath -PathType Leaf)  { $resolved = $sharedPath }
+
+if (-not $resolved) {
+  throw @"
+Kushi config '$Name' not found. Looked in:
+  - $userPath
+  - $sharedPath
+Run `npx kushi-agents@latest` to (re)seed config files, then edit
+$userPath with your values.
+"@
+}
+
+if ($Path) { return $resolved }
+
+$raw = Get-Content -LiteralPath $resolved -Raw
+
+if (-not $AllowPlaceholders) {
+  if ($raw -match '__FILL_ME_IN__' -or $raw -match '<auto>') {
+    throw @"
+Kushi config '$resolved' still has template placeholders (__FILL_ME_IN__ or <auto>).
+Edit the file with your actual values, or pass -AllowPlaceholders to bypass this check.
+"@
+  }
+}
+
+if ($Raw) { return $raw }
+
+switch ($ext) {
+  'json' {
+    return ($raw | ConvertFrom-Json -Depth 100)
+  }
+  { $_ -in 'yml','yaml' } {
+    if (Get-Module -ListAvailable -Name 'powershell-yaml') {
+      Import-Module powershell-yaml -ErrorAction Stop
+      return ConvertFrom-Yaml -Yaml $raw
+    }
+    Write-Warning "powershell-yaml not installed; returning raw YAML text. Install with: Install-Module powershell-yaml -Scope CurrentUser"
+    return $raw
+  }
+}

package/plugin/prompts/aggregate.prompt.md

@@ -1,7 +1,18 @@
----
-description: "Aggregate (pull + consolidate) without building State/."
----
-
+---
+name: aggregate
+description: "Aggregate (pull + consolidate) without building State/."
+argument-hint: "Project name (engagement folder, fuzzy-matched); optional window"
+agent: kushi
+tools: [search, read/readFile, edit, agent, execute/runInTerminal, execute/getTerminalOutput, 'workiq/*']
+---
+
+## User Input
+
+```text
+${input:project:Project name, e.g. HCA}
+${input:window:Optional window — last N days, since YYYY-MM-DD, or YYYY-MM-DD..YYYY-MM-DD (default 7 days)}
+```
+
 # Aggregate
 
 Run `aggregate-project` for the named project.

package/plugin/prompts/apply-ado.prompt.md

@@ -1,8 +1,17 @@
----
-name: apply-ado
-description: Apply approved ADO updates from a proposed.md (gated). Currently a preview-stub — writes a planned.jsonl, no real ADO calls yet.
----
-
+---
+name: apply-ado
+description: "Apply approved ADO updates from a proposed.md (gated). Currently a preview-stub — writes a planned.jsonl, no real ADO calls yet."
+argument-hint: "Project name; runs in dry-mode (writes planned.jsonl, no ADO calls)"
+agent: kushi
+tools: [search, read/readFile, edit, agent, execute/runInTerminal, 'github/*']
+---
+
+## User Input
+
+```text
+${input:project:Project name, e.g. HCA}
+```
+
 # /apply-ado
 
 Route to `@Kushi apply ado <project>`.

package/plugin/prompts/ask.prompt.md

@@ -1,10 +1,20 @@
 ---
 name: ask
-description: Read-only Q&A over a bootstrapped project's State/, Evidence/, and snapshot/ files. Cited; no source pulls; no outbound. Auto-routes when you name a project + ask a question.
+description: "Read-only Q&A over a bootstrapped project's State/, Evidence/, and snapshot/ files. Cited; no source pulls; no outbound. Auto-routes when you name a project + ask a question."
+argument-hint: "Project name + a question about it"
+agent: kushi
+tools: [search, read/readFile, edit, agent]
 ---
 
-# /ask
+## User Input
+
+```text
+${input:project:Project name, e.g. HCA}
+${input:question:Your question, e.g. ''what is the MACC?''}
+```
 
+# /ask
+
 Route to `@Kushi ask <project> <question>`.
 
 Loads the cheapest set of files needed to answer (`State/<topic>.md` first, then latest `Evidence/<alias>/_Consolidated/`, then per-source weekly files, then `external-context/`, then `<project>/SharePoint/snapshot/files/`), emits inline `[source: <alias>/<folder>/<file> · YYYY-MM-DD]` citations, warns if the relevant source is older than `chat.freshness_warn_days` (default 14), and ends with a Confidence line.

package/plugin/prompts/bootstrap.prompt.md

@@ -1,10 +1,20 @@
 ---
 name: bootstrap
-description: First-time setup for a new project — scaffold folders, lay configs side-by-side, do an initial 30-day pull, build State.
+description: "First-time setup for a new project — scaffold folders, lay configs side-by-side, do an initial 30-day pull, build State."
+argument-hint: "Project name (fuzzy-matched under engagement-root); optional initial pull window"
+agent: kushi
+tools: [search, read/readFile, edit, agent, execute/runInTerminal, execute/getTerminalOutput, 'workiq/*']
 ---
 
-# /bootstrap
+## User Input
+
+```text
+${input:project:Project name, e.g. HCA}
+${input:window:Optional initial pull window — last N days, since YYYY-MM-DD, or YYYY-MM-DD..YYYY-MM-DD (default 30 days)}
+```
 
+# /bootstrap
+
 Route to `@Kushi bootstrap <project>`.
 
 Inputs the agent will resolve:
@@ -12,7 +22,21 @@ Inputs the agent will resolve:
 - `<window>` — defaults to 30 days. Override with `last 60 days`, `since 2026-04-01`, or `2026-04-01..2026-05-01`.
 
 Reads:
-- `<workspace>/.kushi/config/project-evidence.yml` for alias + engagement-root.
+- `<workspace>/.kushi/config/user/project-evidence.yml` for alias + engagement-root.
+- `<workspace>/.kushi/config/user/m365-auth.json` for tenant + default notebook + mailbox-folder hints.
+
+**Step 0 — verify per-user config is filled.** Before any pull, call:
+
+```powershell
+& "<install-dest>/lib/Get-KushiConfig.ps1" -Name 'project-evidence' -AllowPlaceholders | Out-Null  # tolerates <auto>; identity-resolution fills it
+& "<install-dest>/lib/Get-KushiConfig.ps1" -Name 'm365-auth'                                       # hard-fails on placeholders
+```
+
+If `Get-KushiConfig -Name 'm365-auth'` throws (file missing or still `__FILL_ME_IN__`), STOP and prompt the user:
+
+> ⚠ `<workspace>/.kushi/config/user/m365-auth.json` still has template placeholders. Open it and fill in your tenant ID, default OneNote notebook ID, mailbox folder names, and SharePoint root before re-running `bootstrap`.
+
+Continue only when both helper calls succeed.
 
 Produces:
 - `<engagement-root>/.project-evidence/m365/{m365-auth,m365-mutable}.json` (per-user filled)

package/plugin/prompts/consolidate.prompt.md

@@ -1,10 +1,20 @@
 ---
 name: consolidate
-description: Merge all contributors' weekly streams into _Consolidated/ for a given window.
+description: "Merge all contributors' weekly streams into _Consolidated/ for a given window."
+argument-hint: "Project name; optional window"
+agent: kushi
+tools: [search, read/readFile, edit, agent, execute/runInTerminal, execute/getTerminalOutput, 'workiq/*']
 ---
 
-# /consolidate
+## User Input
+
+```text
+${input:project:Project name, e.g. HCA}
+${input:window:Optional window — last N days, since YYYY-MM-DD, or YYYY-MM-DD..YYYY-MM-DD (default 7 days)}
+```
 
+# /consolidate
+
 Route to `@Kushi consolidate <project> <window>`.
 
 Default window: `last 7 days`.