kushi-agents 5.9.5 → 6.0.0

package/README.md

@@ -1,400 +1,134 @@
-# Kushi
+# kushi
 
-[![npm version](https://img.shields.io/npm/v/kushi-agents.svg)](https://www.npmjs.com/package/kushi-agents)
-[![npm downloads](https://img.shields.io/npm/dw/kushi-agents.svg)](https://www.npmjs.com/package/kushi-agents)
-[![license](https://img.shields.io/npm/l/kushi-agents.svg)](LICENSE)
-[![host: Clawpilot](https://img.shields.io/badge/host-Clawpilot-7c9cff)](https://gim-home.github.io/kushi/)
-[![host: VS Code](https://img.shields.io/badge/host-VS%20Code-007acc)](https://gim-home.github.io/kushi/)
-[![spec: agentskills.io](https://img.shields.io/badge/spec-agentskills.io-22c55e)](https://agentskills.io/skill-creation/best-practices)
+> Multi-source project evidence + cited Q&A for consulting / engineering engagements.
 
-> **v5.6.0 — Learning candidates.** Runners now auto-capture novel field errors into `<project>/Evidence/_learnings-candidates/` for human review and upstream promotion. Local-only (no telemetry, no auto-PR), 7-day dedup, classifier filters out user-side and transient errors. Closes the field-bug loop — published kushi installs can now contribute doctrine back. New probe `D48`, new concept doc [Learning candidates](https://gim-home.github.io/kushi/concepts/learning-candidates/), new how-to [Promote a learning candidate](https://gim-home.github.io/kushi/how-to/promote-learning-candidate/). `kushi share-learnings` (opt-in redacted upstream submission) lands in v5.7.0.
-
-> **v5.5.0 — Deterministic runners.** Nine pull/orchestrator skills are now thin pointers to Node runners under `plugin/runners/`. The LLM picks scope; the runner does HTTP, file IO, week math, and writes evidence. New probes D44–D47 enforce the contract.
-
-> **v5.2.0 — Hooks + parallel pulls + OTel + teach + schema-evolve.** Pipeline events trigger configurable hooks (`.kushi/hooks/`); pull dispatch is parallel by default (4 workers); OpenTelemetry export is opt-in via `KUSHI_OTEL_ENDPOINT`; `kushi explain <topic>` teaches concepts; `kushi remember <rule>` persists conventions.
-
-> **v5.1.0 — Living wiki.** Build-state is now incremental: human edits outside `<!-- kushi:auto -->` fences are preserved, contradictions are flagged with Obsidian-compatible callouts (`> [!warning]`), and a new `lint-state` skill monitors wiki health. State/ is a valid [Obsidian](https://obsidian.md) vault — callout syntax, Dataview-compatible frontmatter, and `[[wikilinks]]` all work natively.
-
-> **v5.0.1 spec-compliance pass.** Every `plugin/skills/<name>/SKILL.md` follows the [agentskills.io best practices](https://agentskills.io/skill-creation/best-practices) and [optimizing-descriptions](https://agentskills.io/skill-creation/optimizing-descriptions) guides: ≤ 500 lines & ≤ 5000 tokens, load-on-trigger references, top-5 gotchas, checklist orchestrators, validation loops, plan-validate-execute for graph + State writers, and "USE WHEN …" descriptions. Enforced by `self-check -Deep` D30.*.
-
-> **Project lineage:** for the *why* behind each release — what built on what, what trade-offs were accepted, what external work inspired which design — see [`docs/genealogy.md`](docs/genealogy.md). Every release MUST add an entry there before tagging (enforced by `self-check` D31.genealogy).
-
-> A multi-skill GitHub Copilot agent for grounded engagement evidence — across Email, Teams, Meetings, OneNote, SharePoint, Dataverse (CRM), and Azure DevOps.
-
-> **KUSHI** — **K**nowledge **U**nification for **S**takeholder **H**andoff & **I**nsight.
->
-> *Also: Kushi (குஷி) is Tamil for "happiness" — the kind you feel when every "what was decided?" question has a cited answer in seconds.*
-
-📖 **Full docs: https://gim-home.github.io/kushi/**
-
-## The essence: aggregate, then answer
-
-Kushi has two halves that work as one loop:
-
-1. **Aggregate** — pull evidence from every M365 + CRM + ADO surface (email, Teams, meetings, OneNote, SharePoint, Dataverse, Azure DevOps) into a structured per-engagement folder on disk. Captured as **snapshot** (current truth) + **stream** (timestamped events), with provenance.
-2. **Answer** — a read-only **ask-me-anything** agent over that evidence. Every assertion cites the source file + date. No new pulls at answer time. No hallucination. Freshness-gated. Auto-routes when a message names a known project and asks a question — no special prefix needed.
-
-```
-> @Kushi bootstrap Acme           # aggregate: pull 30d baseline + build State
-> what's the MACC for Acme?       # answer: cited, grounded, instant
-> who is the EM on Acme?          # answer: auto-routes, no prefix
-> @Kushi refresh Acme             # aggregate: incremental from last watermark
-```
-
-The split is deliberate: aggregation is **heavy, scheduled, replayable**; answering is **cheap, instant, citable**. A weekly refresh keeps the corpus fresh so every question is already grounded.
-
-See [Concepts → Aggregate, then Answer](https://gim-home.github.io/kushi/concepts/aggregate-and-answer/) for the full pattern.
-
-## v5.0.0 — Cross-source graph + Karpathy State + interactive dashboard + auto-tour
-
-v5.0.0 builds on the v4.9.0 Comprehensive Structured Capture (CSC) + weekly-only layout to surface cross-source structure:
-
-- **Cross-source entity graph** — `link-entities` walks every per-source `_index/entities.yml` + weekly CSC body and emits `<project>/Evidence/_graph/project-graph.json`. Closed edge taxonomy (`references`, `decides`, `action-item-tracks`, `discusses`, `produced-by`, `follow-up-of`, `same-thread`, `participant-of`); deterministic by default; LLM augment is opt-in via `m365Mutable.graph.llm_infer`.
-- **Karpathy-style State layout** — `build-state` now also emits `State/index.md` + `State/log.md` + per-entity pages under closed-set categories (`people/`, `opportunities/`, `adoworkitems/`, `decisions/`, `risks/`, `customerasks/`, `meetings/`, `artifacts/`), plus `State/CLAUDE.md` and `State/AGENTS.md`. Legacy `State/00_…–09_…` files coexist for `full` profile parity.
-- **Interactive HTML dashboard** — `dashboard` writes a single self-contained `<project>/dashboard.html` (Cytoscape.js v3 + cose-bilkent, Clawpilot theme variables, Graph + Timeline tabs, source/alias/date filters, fuzzy search, side panel with cited CSC blocks).
-- **Auto-generated guided tour** — `tour` writes `<project>/State/tour.md`, a top-N walkthrough scored by `recency_weight × cross_ref_count` (14-day half-life × graph degree). Default N=10, configurable via `m365Mutable.tour.topN`.
-- **`refresh` and `bootstrap` chain it all** — at the end of each run, both orchestrators dispatch `link-entities → dashboard → tour`; failures are recorded but never block the next step.
-
-No migration required. Run `@Kushi refresh <project>` to produce the graph, regenerate State/, write the dashboard, and write the tour.
-
-## Two-way sync to ADO — preview shipped
-
-Kushi can now **propose updates back to ADO** from the cited evidence it already has. Two skills under the opt-in `preview` profile:
-
-- ✅ **`propose-ado-update`** — fully working, read-only. Reads the latest `_Consolidated/` evidence and writes `<project>/ado-updates/<date>/proposed.md` with a field-update preview + Discussion comment + per-bullet citations + per-item confidence scores. Safe to run on the same Monday-9am schedule as `refresh`.
-- ✅ **`apply-ado-update`** — preview-stub. Re-fetches live ADO state, runs the approval gate, writes a `planned.jsonl` of what *would* be PATCH/POST'd. Real ADO calls land in v0.1.x once the proposal format is validated against multiple projects.
+`kushi` captures **snapshots** and **streams** from Email, Teams, OneNote, Loop,
+SharePoint, Meetings, CRM, and Azure DevOps into a deterministic on-disk
+**Evidence/** tree, then answers questions strictly from that evidence
+with citations.
 
 ```text
-> @Kushi propose ado Acme
-
-  #4821  Status: Active → Resolved
-         Evidence: Email 2026-05-12 from Priya — "shipped to prod Monday"
-         Confidence: high
-
-  #4837  AssignedTo: Sam → Priya
-         Evidence: Teams 2026-05-11 — "I'll take this one over from Sam"
-         Confidence: medium
-
-Apply [a]ll · [s]elect · [n]one?
+WorkIQ ──▶ runners ──▶ Evidence/<alias>/<source>/<week>/*.csc.md
+                                                   │
+                                                   └──▶ ask  (cited Q&A)
+                                                   └──▶ fde  (FDE authoring)
+                                                   └──▶ ado  (update reports)
 ```
 
-**Safety guarantees** — preview-first diffs, approval gate or per-project allowlist, ledger with reverse op for every applied write, hard tenant-allowlist guard, no bulk migrations, no CRM writes (ADO first).
-
-Try it: `npx kushi-agents --clawpilot --profile preview` · How-to: [Two-way ADO update](https://gim-home.github.io/kushi/how-to/two-way-ado-update/) · Roadmap: [`docs/concepts/roadmap.md`](docs/concepts/roadmap.md).
-
-## Obsidian compatible
-
-`State/` is a valid [Obsidian](https://obsidian.md) vault out of the box:
-
-- **Callout syntax** — contradictions use `> [!warning]` / `> [!info]` callouts (native Obsidian rendering).
-- **Dataview compatible** — every State page has YAML frontmatter (`kushi_state_page: true`, `entity_ids`, `related`, timestamps) queryable by [Dataview](https://blacksmithgu.github.io/obsidian-dataview/).
-- **Wikilinks** — cross-references use `[[category/slug]]` form, resolvable by Obsidian's link resolver.
-- **No binary assets required** — all content is plain Markdown. No images, no custom plugins needed.
-
-To use: point Obsidian at `<project>/State/` as a vault. The `index.md` serves as the home page, `log.md` is the activity feed, and category folders (`people/`, `decisions/`, etc.) are navigable in the sidebar.
-
-> **Note:** Obsidian is optional. State/ works identically without it — the conventions are designed to be tool-agnostic while being Obsidian-first for teams that use it.
-
-<!-- Screenshot placeholder: Obsidian rendering of State/ with contradiction callouts visible. No binary screenshots committed — use text descriptions or link to docs site. -->
-
 ---
 
-## Hooks (v5.2.0+)
-
-Pipeline events (`post-pull`, `post-state`, `post-contradiction`, `post-lint`) trigger configurable hooks — PowerShell scripts or webhooks. Failures are logged but never block the pipeline.
-
-```bash
-# List configured hooks
-kushi hooks list MyProject
-
-# Test-fire a synthetic event
-kushi hooks test MyProject post-pull
-```
-
-Configure in `.kushi/hooks.yml` or drop scripts into `.kushi/hooks/<event>.ps1`. Templates at `plugin/skills/_shared/hook-templates/`.
-
-## Parallel refresh (v5.2.0+)
-
-Pull dispatch is parallel by default (4 workers). Each source writes to its own isolated subtree. Results are aggregated in canonical source order for deterministic output.
-
-```bash
-# Default: parallel (up to 4 workers)
-kushi refresh MyProject
-
-# Force sequential (old behavior)
-kushi refresh MyProject --sequential
-```
-
-Configure `parallel.max_workers` in `.kushi/config.yml`. See `parallel-execution.instructions.md`.
-
-## Telemetry (opt-in, v5.2.0+)
-
-Set `KUSHI_OTEL_ENDPOINT` to export spans to any OTLP-compatible backend (Jaeger, Grafana Tempo, Azure Monitor). Zero overhead when unset. No evidence content or PII — metadata only.
-
-```bash
-export KUSHI_OTEL_ENDPOINT=http://localhost:4318/v1/traces
-kushi refresh MyProject  # spans emitted for each pull + build-state + lint
-```
-
-## Teach mode (v5.2.0+)
-
-Pedagogical, read-only. Explains kushi concepts by loading relevant doctrine + genealogy.
-
-```bash
-kushi explain contradictions
-kushi explain parallel
-kushi explain hooks
-```
-
-## Schema evolve (v5.2.0+)
-
-Teach kushi project-specific conventions that persist across runs.
+## Install
 
-```bash
-kushi remember "always use 'Northwind' not 'Healthcare Accelerator' in summaries"
+```powershell
+npm install -g kushi-agents
+kushi setup                       # one-time: pick engagement root + hosts
+kushi bootstrap <project>         # scaffold a project's Evidence/ tree
+kushi discover <project>          # ask WorkIQ to fill boundaries.yml
+kushi refresh <project>           # pull this week's evidence
+kushi ask <project> "question?"   # cited Q&A in chat
 ```
 
-Rules stored in `Evidence/<alias>/State/CLAUDE.md`. Read by `build-state`, `ask-project`, `refresh-project` at run start.
+Workspace install (per-project, no global): from your engagement root,
+run `npx kushi-agents --target vscode --yes` (or `--target clawpilot`).
 
 ---
 
-## Global wiki (v5.3.0+)
-
-A per-user **global wiki** at `~/.kushi-global/State/` for cross-engagement knowledge — same Karpathy shape as a project `State/`, marked `scope: global`.
-
-```bash
-kushi global init                     # scaffold ~/.kushi-global/State/
-kushi global status                   # counts + last-modified summary
-kushi global ask "what's our confidence ladder pattern?"
-kushi global lint                     # privacy + structure pass
+## What's in v6
 
-# Project → global is explicit-only:
-kushi promote <project> <answer-page>          # refuses if identifiers detected
-kushi promote <project> <answer-page> --force  # redacts + writes target + back-link
+v6 is the **frill amputation** release — one profile, one job:
 
-# Routing under ask-project:
-kushi ask <project> "..."                     # project-first (default)
-kushi ask <project> "..." --global            # global-first
-kushi ask <project> "..." --project-only      # suppress global
-```
+- **Capture**: Evidence pulls from 7 sources (email, teams, meetings, onenote, sharepoint, crm, ado).
+- **Answer**: cited Q&A over Evidence/ only (no hallucination, no web).
+- **FDE**: intake / triage / report authoring prompts.
+- **ADO**: propose + apply update reports.
 
-The global root honors `$KUSHI_GLOBAL_ROOT` (used by tests). There is no auto-promotion path — privacy is always your call. See `plugin/instructions/global-wiki.instructions.md` + `plugin/instructions/multi-wiki-routing.instructions.md`.
+Removed in v6: State/, global wiki, dashboards, tours, learning candidates,
+schema-evolve, teach, lint-state, build-state. See `CHANGELOG.md` for the
+full list.
 
 ---
 
-## Three install profiles
-
-Kushi ships in three tiers. Pick how much you take — the default (`standard`) matches v2.x behavior end-to-end.
-
-| Profile | What's installed | Pick this if… |
-|---|---|---|
-| **`core`** | Aggregator only: `aggregate`, `consolidate`, `status`, `pull`, `ask` | You want raw Evidence/ + cited Q&A — typically to feed an external rollup repo or BI system. |
-| **`standard`** *(default)* | core + `bootstrap`, `refresh`, FDE authoring trio (`fde-intake`, `fde-report`, `fde-triage`) + FDE reference pack | Kushi's default opinion. No State/ rollup. |
-| **`full`** | standard + `state` (renders the opinionated `State/` rollup) | You want everything, including the outcome-based State/ files. |
-
-```bash
-npx kushi-agents --clawpilot                       # default = standard
-npx kushi-agents --clawpilot --profile core        # aggregator only
-npx kushi-agents --clawpilot --profile full        # everything
-```
-
-The Evidence/ folder produced by every profile is a **stable public contract** — external systems can read from it without depending on Kushi internals. See [Concepts → Profiles and report packs](https://gim-home.github.io/kushi/concepts/profiles-and-packs/) and the [Evidence contract](https://gim-home.github.io/kushi/reference/evidence-contract/).
-
 ## Verbs
 
-| Verb | Profile | Window | What it does |
-|------|---------|--------|--------------|
-| `setup` | core+ | n/a | Functionally verify WorkIQ is reachable + auto-fill contributor identity. Idempotent. Run once per machine before first `bootstrap`/`refresh`. |
-| `aggregate` | core+ | last watermark → now | Pull every enabled source + consolidate. **No State/ rebuild.** |
-| `bootstrap` | standard+ | 30 days (default) | First-time setup — scaffold folders, lay configs side-by-side, initial pull. Profile-aware (builds State only on `full`). |
-| `refresh` | standard+ | last watermark → now | Pull only what changed. Profile-aware (rebuilds State only on `full`). |
-| `state` | full | n/a | Render the outcome-based `State/` files from existing evidence. No new pulls. v5.0.0 also emits Karpathy-style layout (`index.md` + `log.md` + per-entity pages under closed-set categories + `CLAUDE.md`/`AGENTS.md`). |
-| `link-entities` | standard+ | n/a | v5.0.0 — Build the cross-source entity graph (`Evidence/_graph/project-graph.json`). Deterministic; opt-in LLM augment. |
-| `dashboard` | standard+ | n/a | v5.0.0 — Render `<project>/dashboard.html` — single self-contained Cytoscape.js v3 dashboard with Graph + Timeline views, filters, fuzzy search, side panel. |
-| `tour` | standard+ | n/a | v5.0.0 — Render `<project>/State/tour.md`, an auto-generated week-in-review walkthrough scored by `recency_weight × cross_ref_count`. |
-| `consolidate` | core+ | per week | Merge per-user streams into `_Consolidated/<YYYY-MM-DD>_consolidated.md`. |
-| `status` | core+ | n/a | Show the run-log for a project. |
-| `ask` | core+ | n/a | Read-only natural-language Q&A. Always cites. Auto-routes. |
-| `fde-intake` | standard+ | n/a | Capture the 6 FDE intake questions → `Reports/00-FDE-Intake-<project>.md` (updated in place). |
-| `fde-report` | standard+ | n/a | FDE report generator. 5 shapes: `weekly` (default), `short`, `long`, `fitness`, `stage-readiness`. |
-| `fde-triage` | standard+ | n/a | 7-file FDE triage bundle at `Reports/triage/<YYYY-MM-DD>/`. File 07 merges across re-runs. |
-| `propose-ado` | **preview** | n/a | Read-only ADO update proposal from latest `_Consolidated/` → `ado-updates/<date>/proposed.md`. Safe to schedule. No ADO writes. |
-| `apply-ado` | **preview** | n/a | Gated apply skill. v0.1.0-preview is dry-mode only (writes `planned.jsonl`); real ADO PATCH/POST lands in v0.1.x. |
-| `vertex-link` | **preview** | n/a | One-time link of a kushi project to a vertex repo `<customer>/<initiative>` (multi-binding supported). Populates `kushi.yaml#vertex`. Re-run with `--reconfigure` to change. |
-| `emit-vertex` | **preview** | n/a | Render vertex-shaped artifacts from kushi Evidence/+State/ — weekly status, decisions, workshops, comms, living-doc diff proposals. Stages first, validates against vertex's own schemas, applies on demand. |
-| `doctor` | core+ | n/a | v5.4.0 — Aggregated health check (env, self-check, evals, skill-checker, live-install drift, global wiki). `--json` for CI; `--strict` to fail on yellow. |
-| `lint` | standard+ | n/a | v5.1.0 — Run wiki-lint checks against `State/` (contradictions, stale claims, orphans, missing cross-refs, data gaps). Writes `State/reports/lint-YYYY-MM-DD.md`. |
-| `teach` | standard+ | n/a | v5.2.0 — Persist a reusable fact/preference/pattern under `.kushi/learnings/`. |
-| `explain` | standard+ | n/a | v5.2.0 — Retrieve a previously taught fact/preference/pattern from `.kushi/learnings/`. |
-| `promote` | standard+ | n/a | v5.3.0 — Copy a project State page into the global wiki at `~/.kushi-global/` with identifier redaction + back-link + dual log. Refuses without `--force` when identifiers detected. |
-| `migrate-files` | standard+ | n/a | v5.4.4 — One-time migration of root-level `bootstrap-status.md` / `FOLLOW-UPS.md` / `OPEN-QUESTIONS-DRAFT.md` to per-user `Evidence/<alias>/`. Dry-run by default; `--apply` to commit. Refuses to overwrite on content conflict. |
-| `global` (init/status/ask/lint) | standard+ | n/a | v5.3.0 — Manage the per-user cross-engagement wiki at `~/.kushi-global/State/`. |
-| `schema-evolve` | standard+ | n/a | v5.2.0 — Migrate `kushi.yaml` and Evidence/ layouts across schema versions; idempotent + dry-run by default. |
-| `create-skill` / `check-skill` | full | n/a | v5.0.4 — Skill-authoring harness (scaffold a new skill; lint/retrofit every SKILL.md against `skill-authoring.instructions.md`). |
-
-See [Quickstart](https://gim-home.github.io/kushi/getting-started/quickstart/) for the full workflow.
-
-### Doctor works from both layouts (v5.4.5+)
-
-`doctor` and `self-check` are **layout-portable**: they run cleanly from either the **source tree** (this repo: `plugin/skills/...`) or an **installed host directory** (e.g. `~/.vscode/chat/skills/kushi/skills/...` — FLAT, no `plugin/` prefix). A banner like `[layout=source]` or `[layout=install (host=clawpilot)]` prints at the top of every run so you know which personality is active.
-
-- **Source mode** (default in this repo): runs the full source-author surface (C1..C12, D1..D43).
-- **Install mode**: runs a focused install-integrity probe set (manifest validity, every enumerated skill present, agent file, skills-metadata sibling, npm-latest drift if `npm` is on PATH, optional global wiki shape). Fix hints become `Re-install: npx kushi-agents@latest --<host> --force` instead of "restore from git".
-
-Force a mode with `-LayoutMode source|install` on either script; default is `auto`.
-
-## Install
-
-Kushi supports **two host surfaces** as first-class peers (v5.0.2+):
-
-| Host                                  | Install path                       | Best for                                |
-|---------------------------------------|------------------------------------|-----------------------------------------|
-| **Clawpilot CLI**                     | `~/.copilot/m-skills/kushi/`       | Scheduled / overnight runs (e.g. `kushi refresh <project>` at 6 AM via automation) |
-| **VS Code Chat** ("GitHub Copilot Chat") | `~/.vscode/chat/skills/kushi/`     | Interactive use (`@kushi what's the MACC for X?`) |
-
-Both hosts read the **same** Evidence/ tree on disk, so a refresh from one is immediately visible from the other — the same user routinely lives in both. SKILL content is host-agnostic (no per-host branching, enforced by self-check `D32.multi-host`).
-
-```bash
-# Install to a single host
-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
-npx kushi-agents --uninstall                       # all detected hosts
-npx kushi-agents --uninstall --clawpilot           # Clawpilot only
-npx kushi-agents --uninstall --vscode              # VS Code Chat only
-npx kushi-agents --uninstall --all                 # both
-
-# Legacy workspace install (per-project .kushi/ in cwd)
-npx kushi-agents                                   # default = standard profile
-npx kushi-agents --profile core                    # aggregator only
-```
-
-The 2-host matrix is a deliberate cap — see [`plugin/instructions/multi-host-install.instructions.md`](plugin/instructions/multi-host-install.instructions.md) for the rationale + per-host layout details.
-
-```bash
-npx kushi-agents --clawpilot --profile full        # everything
-```
-
-To switch profiles later, re-run with `--force` (cleanly handles downgrades):
-
-```bash
-npx kushi-agents --clawpilot --profile core --force
-```
-
-> **Bleeding-edge from GitHub (Microsoft org members only)**: `npx github:gim-home/kushi …` works identically and pulls straight from the source repo — useful for testing pre-release commits. Stick to `npx kushi-agents` for everything else.
-
-See [Install](https://gim-home.github.io/kushi/getting-started/install/) for flags, prerequisites, and per-user config.
+| Verb | What it does | Where it runs |
+|------|--------------|---------------|
+| `setup` | One-time identity + host config | terminal |
+| `bootstrap` | Scaffold `<root>/<P>/Evidence/<alias>/` tree | terminal |
+| `discover` | Ask WorkIQ to fill `boundaries.yml` + `integrations.yml` | terminal |
+| `refresh` | Pull this week's evidence (alias: `update`, `pull`, `sync`) | terminal |
+| `references` | Resolve external URLs into `Evidence/_shared/references/` | terminal |
+| `lint` | Validate Evidence/ against the CSC schema | terminal |
+| `migrate-files` | One-time helper to move legacy files into the v6 layout | terminal |
+| `doctor` | Self-check: hashes, canary, install drift | terminal |
+| `ask` | Cited Q&A in chat (read-only) | chat |
+| `status` | Latest evidence summary | chat |
+| `aggregate` | Roll a contributor's per-week files into `_aggregated/` | chat |
+| `consolidate` | Merge multiple contributors' aggregations | chat |
+| `fde-intake` | Author an FDE intake brief | chat |
+| `fde-triage` | Author an FDE triage decision matrix | chat |
+| `fde-report` | Author an FDE outcome report | chat |
+| `propose-ado` | Draft an ADO update report | chat |
+| `apply-ado` | Apply an approved ADO update report | chat |
+| `link-entities` | Cross-source entity link cache for `ask` | chat |
+| `vertex-link` | Link a Vertex node into an external rollup | chat |
+| `emit-vertex` | Emit a Vertex bridge artifact | chat |
 
-## What it does
-
-Engagement context lives in too many places. By the time someone asks "what was decided about the architecture?" or "who is the EM on project X?" the answer is buried across emails, Teams threads, OneNote pages, SharePoint files, meeting transcripts, CRM records, and ADO work items.
-
-Kushi pulls all of those into a structured, citable, per-engagement folder — and lets you ask grounded questions that always cite the source.
-
-- **WorkIQ-only**: every source pull uses WorkIQ. We walk you through [installing it](docs/getting-started/install-workiq.md) — Microsoft Graph isn't a viable fallback here. When WorkIQ can't answer, Kushi asks you to paste rather than producing thin metadata.
-- **Snapshot + stream**: current truth and the trail of how we got there.
-- **Citation per assertion**: every claim in State files and answers points back to a real source file with a date.
-- **Host-agnostic**: works in VS Code Chat or Clawpilot CLI.
-
-## Output shapes (what aggregation writes to disk)
-
-For each source, Kushi produces two output shapes:
-
-| Shape | What | Filename | Refresh behavior |
-|-------|------|----------|------------------|
-| **Snapshot** | Current state of an entity (page body, work item, CRM record, file content) | `snapshot/<entity>.md` (NO date in filename) | **Replace** on every refresh |
-| **Stream** | Timestamped events (emails, messages, edits, comments, state changes) | `stream/<YYYY-MM-DD>_<source>-stream.md` (Monday of ISO week) | **Append**, dedupe by event ID |
-
-Email is stream-only (emails ARE events). Every other source has both. `ask-project` reads both shapes when answering.
-
-## Documentation
-
-| | |
-|---|---|
-| 🚀 [Getting started](https://gim-home.github.io/kushi/getting-started/) | Install + quickstart — pick a target, run one `npx` command |
-| 💡 [Concepts](https://gim-home.github.io/kushi/concepts/) | Hosts, storage backends, snapshot vs stream, multi-user model |
-| 🤝 [Kushi with Vertex](docs/concepts/kushi-with-vertex.md) | Using kushi alongside the [vertex](https://github.com/commercial-software-engineering/vertex) shared note-taking platform — better weekly status, decisions, workshops, and comms |
-| 🛠️ [How-to guides](https://gim-home.github.io/kushi/how-to/) | Schedule refreshes, add contributors, switch backends, upgrade, uninstall |
-| 📖 [Reference](https://gim-home.github.io/kushi/reference/) | Verbs, CLI options, config files, path map, self-check |
-| 📋 [Changelog](CHANGELOG.md) | Release history |
+---
 
-## Repository layout (high level)
+## Layout
 
 ```text
-kushi/
-├── bin/cli.mjs              Installer entry point
-├── src/                     Installer source
-├── plugin/                  ← THE PAYLOAD that ships into .kushi/ (or ~/.copilot/m-skills/kushi/)
-│   ├── plugin.json
-│   ├── agents/
-│   ├── instructions/
-│   ├── prompts/
-│   ├── skills/
-│   └── templates/
-├── docs/                    MkDocs Material site (deployed to GitHub Pages)
-├── mkdocs.yml
-├── requirements-docs.txt
-├── README.md
-├── CHANGELOG.md
-└── LICENSE
-```
-
-See [docs/reference/where-things-live.md](docs/reference/where-things-live.md) for the complete layout.
-
-## Contributing
-
-See [CONTRIBUTING.md](CONTRIBUTING.md) for the full contributor guide — repo layout, dev environment setup, the pre-commit checklist (self-check + mkdocs + npm pack), commit conventions, and how to add new skills/instructions/templates.
-
-Quick pre-commit check:
+<engagement-root>/
+└── <ProjectName>/
+    ├── boundaries.yml             ← per-source query scope (auto-filled by `discover`)
+    ├── integrations.yml           ← CRM/ADO/SharePoint pointers
+    └── Evidence/
+        ├── _shared/
+        │   ├── references/        ← URLs from project docs, fetched + cited
+        │   └── _aggregated/       ← `consolidate` output
+        └── <your-alias>/
+            ├── _ledger.yml        ← per-week pull receipts
+            ├── email/<week>/
+            ├── teams/<week>/
+            ├── meetings/<week>/
+            ├── onenote/<week>/
+            ├── sharepoint/<week>/
+            ├── crm/<week>/
+            └── ado/<week>/
+```
+
+Each evidence file is a **CSC** (Cite-Source-Capture) markdown block —
+deterministic, hand-readable, grep-friendly.
 
-```powershell
-pwsh plugin/skills/self-check/run.ps1 -Deep
-mkdocs build --strict
-npm pack --dry-run
-```
-
-The self-check validates frontmatter, agent inventory, prompt → skill routing, profile manifest, reference packs, cross-links, the verbs table in this README, and the layout diagram in `docs/reference/where-things-live.md`. Full reference: [docs/reference/self-check.md](docs/reference/self-check.md).
-
-## Authoring a new skill (v5.0.4+)
-
-Adding a new skill takes one command + a per-skill lint loop:
-
-```powershell
-node bin/cli.mjs create-skill --name my-thing --type writer --description "Generates the foo report from State/"
-node bin/cli.mjs check-skill --name my-thing
-node bin/cli.mjs check-skill --name my-thing --retrofit --apply   # auto-fix additive findings
-npm run eval -- my-thing
-```
+---
 
-Full walkthrough: [`docs/contributing/skill-authoring.md`](docs/contributing/skill-authoring.md). Doctrine: [`plugin/instructions/skill-authoring.instructions.md`](plugin/instructions/skill-authoring.instructions.md). Repo-wide dogfood baseline: [`docs/audits/v5.0.4-skill-creator-dogfood.md`](docs/audits/v5.0.4-skill-creator-dogfood.md).
+## Env vars
 
-## Evaluating skills (v5.0.3+)
+| Var | Effect |
+|-----|--------|
+| `KUSHI_ALIAS` | Your alias (overrides `.kushi/config/user/project-evidence.yml`). |
+| `KUSHI_WIZARD_ROOT` | Engagement root for `kushi setup` (non-interactive). |
+| `KUSHI_WIZARD_HOSTS` | `clawpilot` / `vscode` / `both`. |
+| `KUSHI_WIZARD_GLOBAL` | `y` / `n`. |
+| `KUSHI_WIZARD_WORKSPACE` | `y` / `n` — scaffold cwd as a kushi workspace. |
+| `KUSHI_WORKIQ_BIN` | Path to the WorkIQ binary (auto-detected by default). |
+| `KUSHI_DISCOVER_HEARTBEAT_MS` | Heartbeat cadence for `discover` progress logs. |
 
-Every skill ships per-case evals at `plugin/skills/<name>/evals/evals.json`, aligned with the [agentskills.io evaluating-skills spec](https://agentskills.io/skill-creation/evaluating-skills). Doctrine: [`plugin/instructions/skill-evals.instructions.md`](plugin/instructions/skill-evals.instructions.md).
+---
 
-Quickstart:
+## Develop
 
 ```powershell
-npm run eval:canary        # ~6 skills, runs in seconds — what PRs run
-npm run eval:all           # full suite (every plugin/skills/<name>/)
-npm run eval -- ask-project   # one skill
-npm run eval:baseline      # maintainer-only: refresh evals/baseline.json
+git clone <repo> kushi
+cd kushi
+npm install
+npm test                  # 279 tests
+npm run eval:canary       # 8/8 fixture-based grader cases
+node bin/cli.mjs doctor   # green when canary + hashes line up
 ```
 
-Outputs:
-
-- `Evidence/_evals/<utc-ts>.json` — per-run JSON (pass/fail + duration + tokens per case).
-- `Evidence/_evals/benchmark.json` — per-skill mean/stddev for `pass_rate`, `duration_ms`, `tokens_total` + regression flags vs `evals/baseline.json`.
-
-Regressions flagged at ≥10pp pass-rate drop OR ≥50% latency/token increase. The canary subset is `ask-project`, `bootstrap-project`, `refresh-project`, `link-entities`, `build-state`, `self-check`.
-
-**Privacy:** fixtures under `evals/fixtures/` are synthetic. NEVER copy real customer data into the evals tree.
+---
 
 ## License
 
-See [LICENSE](LICENSE).
+MIT.