kushi-agents 4.8.3 → 5.0.0

package/README.md

@@ -3,6 +3,8 @@
 [![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/)
 
 > A multi-skill GitHub Copilot agent for grounded engagement evidence — across Email, Teams, Meetings, OneNote, SharePoint, Dataverse (CRM), and Azure DevOps.
 
@@ -30,6 +32,18 @@ The split is deliberate: aggregation is **heavy, scheduled, replayable**; answer
 
 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:
@@ -83,7 +97,10 @@ The Evidence/ folder produced by every profile is a **stable public contract**
 | `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. |
+| `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. |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "kushi-agents",
-  "version": "4.8.3",
-  "description": "Install Kushi — multi-source project evidence agent with snapshot+stream capture across Email, Teams, OneNote, Loop, SharePoint, Meetings, CRM, ADO. WorkIQ-only for M365 sources (Graph / m365_* FORBIDDEN as fallbacks; user-paste is first-class). Host-agnostic.",
+  "version": "5.0.0",
+  "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": {
     "kushi-agents": "./bin/cli.mjs"

package/plugin/agents/kushi.agent.md

@@ -35,7 +35,10 @@ The Evidence/ folder produced by `aggregate` is the **public contract** between
 | `@Kushi bootstrap <project>` | standard+ | last 30 days | `bootstrap-project` → `pull-*` → `consolidate-evidence` → (full only) `build-state` |
 | `@Kushi refresh <project>` | standard+ | since last watermark (fallback 7d) | `refresh-project` → `pull-*` → `consolidate-evidence` → (full only) `build-state` |
 | `@Kushi refresh <project> last N days` / `since <date>` / `<from>..<to>` | standard+ | as supplied | same |
-| `@Kushi state <project>` | **full** | n/a (no pull) | `build-state` only — re-render State/ from existing Evidence |
+| `@Kushi state <project>` | **full** | n/a (no pull) | `build-state` only — re-render State/ from existing Evidence (v5.0.0: ALSO emits Karpathy `State/` layout — `index.md` + `log.md` + per-entity pages + `CLAUDE.md`/`AGENTS.md` — gated on `m365Mutable.state.layout`, default `karpathy`). |
+| `@Kushi link-entities <project>` | standard+ | n/a (read-only) | v5.0.0 — `link-entities` writes `<project>/Evidence/_graph/project-graph.json` from per-source `_index/entities.yml` + weekly CSC bodies. Deterministic by default; opt-in LLM augment via `m365Mutable.graph.llm_infer`. |
+| `@Kushi dashboard <project>` | standard+ | n/a (read-only) | v5.0.0 — `dashboard` writes `<project>/dashboard.html` (single self-contained file). Cytoscape.js v3 + Clawpilot theme. |
+| `@Kushi tour <project> [--top N]` | standard+ | n/a (read-only) | v5.0.0 — `tour` writes `<project>/State/tour.md`, an auto-generated week-in-review walkthrough scored by `recency_weight × cross_ref_count` (14-day half-life). Default N=10. |
 | `@Kushi consolidate <project> last N days` | core+ | N days | `consolidate-evidence` only |
 | `@Kushi status <project>` | core+ | n/a | `project-status` — show run-log |
 | `@Kushi ask <project> <question>` | core+ | n/a (read-only) | `ask-project` — cited Q&A over Evidence/ (+ State/ on full) |
@@ -145,7 +148,10 @@ Top-level orchestrator skills (called directly by verbs):
 | `aggregate-project` | core+ | Pull-only orchestrator. Runs every enabled `pull-*` + `consolidate-evidence`. **Does NOT run `build-state`.** |
 | `bootstrap-project` | standard+ | First-time setup; lays configs side-by-side, scaffolds folders, runs initial 30d pull. Profile-aware: calls `build-state` only on `full`. |
 | `refresh-project` | standard+ | Watermark-driven incremental orchestrator. Profile-aware: calls `build-state` only on `full`. |
-| `build-state` | **full** | Renders `State/` from existing `Evidence/` (no source pulls). |
+| `build-state` | **full** | Renders `State/` from existing `Evidence/` (no source pulls). v5.0.0: also emits Karpathy layout (`index.md` + `log.md` + per-entity pages + `CLAUDE.md`/`AGENTS.md`) when `m365Mutable.state.layout: karpathy` (default). |
+| `link-entities` | standard+ | v5.0.0 — cross-source entity graph builder. Walks `Evidence/<alias>/<source>/_index/entities.yml` + weekly CSC bodies and emits `Evidence/_graph/project-graph.json` (nodes per canonical entity id, edges by closed taxonomy). LLM augment is opt-in via `m365Mutable.graph.llm_infer`. |
+| `dashboard` | standard+ | v5.0.0 — renders `<project>/dashboard.html` (single self-contained file) from the entity graph + per-source `_index/entities.yml` + `State/index.md`. Cytoscape.js v3 + Clawpilot theme variables. |
+| `tour` | standard+ | v5.0.0 — emits `<project>/State/tour.md`, an auto-generated week-in-review walkthrough scored by `recency_weight × cross_ref_count` (14-day half-life). |
 | `consolidate-evidence` | core+ | Merges per-user streams into `_Consolidated/`. |
 | `project-status` | core+ | Read-only run-log inspector. |
 | `ask-project` | core+ | Read-only natural-language Q&A over Evidence/ (+ State/ on full). Cited; no source pulls; no outbound. Auto-dispatches when a project name + question are detected. |

package/plugin/instructions/comprehensive-structured-capture.instructions.md

@@ -0,0 +1,250 @@
+---
+applyTo: "**"
+description: "Comprehensive Structured Capture (CSC) — replaces verbatim-by-default (v4.9.0). Every per-entity evidence block is a structured set of bulleted sections capturing every material detail, with no prose paragraphs and no omissions. Readable by humans, parseable by build-state, reliably producible by WorkIQ in one call without payload-too-large failures."
+---
+
+# Comprehensive Structured Capture (CSC) — HARD RULE (kushi v4.9.0+)
+
+## Why CSC replaced verbatim-by-default
+
+The old contract (`verbatim-by-default.instructions.md`) required every pull-* skill to capture
+raw verbatim bodies — full email body, full transcript line-by-line, full OneNote page body —
+plus multi-paragraph AI Narrative Summaries. In practice this failed:
+
+- WorkIQ refuses bulk verbatim with `payload-too-large` for OneNote pages.
+- `m365_get_email` tool-errors ~100% of the time; bodies degrade to 200-char search previews.
+- Teams meeting transcripts are often not generated (transcription not enabled).
+- Multi-paragraph prose summaries are easy to fabricate from adjacent evidence — citation
+  discipline degrades.
+
+CSC trades raw verbatim for **structured completeness**: every material fact captured as a
+bullet, organized into named sections, with citations on every bullet. This is what WorkIQ
+returns reliably on the first try, and it is what downstream readers (build-state,
+ask-project, consolidate-evidence) can parse without natural-language understanding.
+
+## What a CSC block looks like (universal shape)
+
+Every per-entity block — per meeting, per email thread, per Teams thread, per OneNote page,
+per SharePoint file, per CRM record, per ADO work item — uses this section order. Sections
+that don't apply for a source are omitted (see per-source overrides below); sections that
+apply but had nothing surfaced MUST be present with `_None surfaced._`.
+
+```markdown
+## <entity-name> {#<entity-anchor>}
+
+- **Source basis**: <one-liner — what WorkIQ call + request-id, what host probe, fidelity>
+- **Coverage window**: <ISO range covered by this block>
+- **Last touched**: <ISO timestamp>
+
+### Participants / Present
+- <name or address> — <role: organizer / attendee / sender / recipient / author / commenter>
+- ...
+
+### Topics Discussed
+- <topic 1>
+  - <sub-point with detail>
+  - <sub-point with detail>
+- <topic 2>
+  - ...
+- ...
+
+### Q & A
+- **Q** (asked by <name>): <question text> — **A** (answered by <name>): <answer text> [source: ... · ts]
+- **Q** (asked by <name>): <question> — **A**: _Left open._ [source: ... · ts]
+- ...
+
+### Who Said What (material statements)
+- <name>: "<material statement / position / pushback>" [source: ... · ts]
+- ...
+- _(Only material statements — not every utterance. Routine acknowledgements omitted.)_
+
+### Decisions
+- **Decided**: <exact wording> — **by**: <name(s)> — **rationale**: <why> — **rejected alternatives**: <what was considered and dropped> [source: ... · ts]
+- ...
+
+### Dates & Numbers Shared
+- <date / number / dollar amount / percentage / count>: <exact value> — **context**: <what it refers to> — **shared by**: <name> [source: ... · ts]
+- ...
+
+### Action Items
+- [ ] <owner> — <action> — **due**: <date or TBD with reason> [source: ... · ts]
+- ...
+
+### Next Steps
+- <forward-looking commitment without hard owner+due> — **expected by**: <approximate date or "next sync">
+- ...
+- _(Distinct from Action Items. "Team will look into X", "we'll circle back", soft signals.)_
+
+### Open Questions / Unresolved
+- <question or unresolved item> — **raised by**: <name> — **why deferred**: <reason> [source: ... · ts]
+- ...
+
+### Risks / Blockers / Dependencies
+- **Risk**: <description> — **owner**: <name or unassigned> — **mitigation**: <plan or _None._> [source: ... · ts]
+- **Blocker**: <description> — **blocking**: <what's blocked> — **owner**: <name> [source: ... · ts]
+- **Dependency**: <description> — **on**: <what we depend on> — **owner**: <name> [source: ... · ts]
+- ...
+
+### Customer Asks (engagement sources only)
+- <ask> — **asked by**: <customer name> — **of**: <Microsoft role/person> — **status**: <open / committed / declined> [source: ... · ts]
+- ...
+
+### Artifacts / Links
+- <file name or link title>: <url> — <type: shared in meeting / attached to email / linked from page / etc.>
+- ...
+
+### Coverage Notes
+- <what was retrievable vs what wasn't>
+- <any caveats: WorkIQ summary-only, transcript-not-generated, body-not-extractable, etc.>
+```
+
+## Hard rules
+
+### 1. Bullets only — no prose paragraphs
+
+Every section content is a bulleted list. A paragraph of running prose anywhere in a CSC block
+is a **defect**. The AI Narrative Summary that the old verbatim doctrine required is removed —
+its purpose (give a reader the whole picture) is satisfied by the union of `Topics Discussed` +
+`Decisions` + `Who Said What` + `Dates & Numbers Shared`.
+
+Bullets may have nested sub-bullets (2–5 lines of detail per top-level bullet is normal).
+Bullets may span multiple lines using markdown soft-wraps. They must not be paragraphs.
+
+### 2. No omission — "and N more" is a defect
+
+If WorkIQ returns `"and 12 more topics..."`, `"key highlights only"`, `"sample of..."`,
+`"10 of 47 shown"`, or any equivalent truncation marker — that is a **defect**. Re-issue with
+the doubled-strict retry from `workiq-only.instructions.md` asking for the full set with no
+truncation. If the second attempt also truncates, write a deferred-retry marker per
+`deferred-retry-on-workiq-fail.instructions.md` and continue.
+
+### 3. Empty sections are explicit
+
+A section that applies to a source but had nothing surfaced MUST be present with
+`_None surfaced._` (or `_None this entity._`). Omitting the section is a defect — the reader
+cannot tell "checked and empty" from "skipped".
+
+### 4. Citation per material bullet
+
+Every bullet that carries a fact (date, number, decision, statement, action, risk, ask) MUST
+carry an inline citation. Format:
+`[source: <alias>/<source>/weekly/YYYY-MM-DD_<source>-csc.md#<entity-anchor> · <iso-ts>]`
+or
+`[source: WorkIQ request-id <guid> · ts]` when citing the WorkIQ probe directly.
+
+Bullets that are organizational ("Participants", "Artifacts / Links") need not be individually
+cited if the Source basis line covers them.
+
+### 5. No fabrication from adjacent evidence
+
+If WorkIQ returned `body-unavailable` or the cascade returned nothing for an entity, the
+correct CSC block is the entity header + `Source basis: unavailable` + `Coverage Notes`
+explaining the failure mode + `_None surfaced._` for every other section. **Do NOT** infer
+what the entity "likely contained" from other emails, chat traffic, file names, or page titles
+— that's fabrication and pollutes the citation chain. Empty is the correct state until the
+entity is actually retrieved.
+
+### 6. Who Said What is for material attribution only
+
+`Who Said What` is NOT a verbatim transcript reproduction. It is the curated list of
+**material** statements — positions taken, pushbacks raised, key data points stated,
+commitments made — with attribution. Routine acknowledgements (`thanks`, `sounds good`, `+1`)
+are omitted. A 50-message thread typically produces 3–10 entries here, not 50.
+
+For meetings, the raw chronological transcript (when retrievable) lives in
+`Evidence/<alias>/meetings/verbatim/<dir>/transcript.txt` per
+`meetings-verbatim-required.instructions.md`. That is the audit artifact; the CSC block in
+the weekly file is the curated, query-able form.
+
+## Per-source section applicability
+
+| Section | email | teams | meetings | onenote | sharepoint | crm | ado |
+|---|---|---|---|---|---|---|---|
+| Participants / Present | ✅ sender+recipients | ✅ chat members | ✅ attendees | ✅ author + editors | ✅ author + editors | ✅ owner + contacts | ✅ assignee + commenters |
+| Topics Discussed | ✅ | ✅ | ✅ | ✅ page content topics | ✅ file content topics | ✅ record story | ✅ WI story |
+| Q & A | ✅ | ✅ | ✅ | ➖ omit | ➖ omit | ➖ omit | ✅ from comments |
+| Who Said What | ✅ | ✅ | ✅ | ➖ omit | ➖ omit | ➖ omit | ✅ from comments |
+| Decisions | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Dates & Numbers Shared | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Action Items | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Next Steps | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Open Questions | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Risks / Blockers / Dependencies | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Customer Asks | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Artifacts / Links | ✅ attachments | ✅ shared files | ✅ recording+files | ✅ embedded links | ✅ this file | ✅ related records | ✅ related WIs |
+| Coverage Notes | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+
+Sections marked ➖ MUST be omitted for that source (don't write `_None surfaced._` — omit
+entirely).
+
+## Volume guidance
+
+CSC blocks are typically **denser per byte** than the old verbatim shape (no prose padding) but
+LONGER overall (more sections, every fact bulleted). Expect:
+
+- 80–200 lines per substantive meeting
+- 40–120 lines per substantive email thread
+- 30–80 lines per Teams chat thread with activity
+- 50–150 lines per OneNote page with substantive edits
+- 30–100 lines per SharePoint file body
+- 50–200 lines per CRM/ADO record update
+
+A 10-line CSC block for a 90-minute meeting is a defect. So is a 500-line block for a
+3-message email thread — the latter signals padding / fabrication.
+
+## Anti-patterns (defects)
+
+1. **Prose paragraph anywhere in a CSC block.** Re-extract as bullets.
+2. **AI Narrative Summary section.** Removed in v4.9.0 — Topics Discussed + Who Said What
+   carry the load. Re-extract.
+3. **"and N more" / truncation markers.** Doubled-strict retry, then defer.
+4. **Omitted sections that should be `_None surfaced._`.** Add them back.
+5. **Section misorder.** Use the canonical order above (Participants → Topics → Q&A →
+   Who Said What → Decisions → Dates & Numbers → Action Items → Next Steps → Open Questions →
+   Risks → Customer Asks → Artifacts → Coverage Notes).
+6. **Inferred narrative for missing bodies.** When body is unavailable, write
+   `Source basis: unavailable` + `_None surfaced._` for content sections. Don't make it up.
+7. **Verbatim quote reproduction outside meetings/verbatim/.** Quote in `Who Said What`
+   sparingly for material statements only; never copy the full transcript into the weekly
+   file — that lives in `meetings/verbatim/<dir>/transcript.txt`.
+8. **Bullets without citations** on fact-bearing sections.
+9. **`Who Said What` as 50-row utterance log.** Curate to material only.
+
+## Pre-write checklist (every pull-* skill)
+
+Before writing a CSC block, confirm:
+
+- [ ] Section order matches the canonical order
+- [ ] Every applicable section is present (empty → `_None surfaced._`)
+- [ ] Inapplicable sections are omitted entirely (not stubbed)
+- [ ] Every fact-bearing bullet has a citation
+- [ ] No prose paragraphs anywhere
+- [ ] No `and N more` / truncation markers
+- [ ] If body was unavailable, `Source basis: unavailable` + content sections are `_None surfaced._`, not inferred
+- [ ] `Who Said What` curated to material statements only
+- [ ] Entity anchor `{#slug}` is set on the heading for citation targeting
+
+## Self-check enforcement
+
+`plugin/skills/self-check/run.ps1` deep checks D11–D16 (rewritten in v4.9.0):
+- **D11**: every weekly CSC file has at least one entity block.
+- **D12**: every entity block has the canonical section order.
+- **D13**: meetings stream block has a sibling `verbatim/<dir>/` folder (kept from v3.10.0).
+- **D14**: no prose paragraphs in weekly CSC files (heuristic: lines without leading `-`, `*`,
+  `#`, `>`, or empty, longer than 200 chars).
+- **D15**: no `and N more`, `key highlights only`, `sample of`, `N of M shown` markers
+  outside coverage notes.
+- **D16**: `_index/entities.yml` exists for every populated weekly/ folder.
+
+## Apply
+
+Every `pull-<source>` SKILL.md MUST reference this instruction in its front contracts
+blockquote alongside `weekly-csc.instructions.md`. The two are co-equal.
+
+Cross-references:
+- `weekly-csc.instructions.md` — defines the file layout CSC blocks live in.
+- `meetings-verbatim-required.instructions.md` — raw transcript audit folder (meetings-only).
+- `citation-ledger.instructions.md` — citation format.
+- `deferred-retry-on-workiq-fail.instructions.md` — what to do when WorkIQ truncates.
+- `evidence-thoroughness.instructions.md` — rewritten in v4.9.0 to point at this file.
+- `verbatim-by-default.instructions.md` — DEPRECATED in v4.9.0; redirects here.

package/plugin/instructions/dashboard-artifact.instructions.md

@@ -0,0 +1,132 @@
+---
+applyTo: "**"
+description: "v5.0.0 — Interactive HTML dashboard. Single self-contained `<project>/dashboard.html` rendered from `_graph/project-graph.json` + `_index/entities.yml` (per source) + `State/index.md`. Uses Cytoscape.js v3 + cose-bilkent layout, two-view tabs (Graph + Timeline), source/alias/date filters, fuzzy search, and a side panel that surfaces weekly CSC blocks on node click. Theming follows the Clawpilot `web-artifacts-builder` skill (CSS variables). Idempotent — regenerated every run."
+---
+
+# Dashboard Artifact — HARD RULE (kushi v5.0.0+)
+
+## Why
+
+Stakeholders ask "what happened on this engagement?" and we hand them
+markdown nobody reads. v5.0.0 ships a single HTML file that visualizes the
+project graph and lets the reader click any node to surface the cited CSC
+block. No server, no build, no install — just open the file.
+
+## Output
+
+- **Path:** `<engagement-root>/<project>/dashboard.html`
+- **Producer:** `dashboard` skill.
+- **Idempotency:** the file is **fully regenerated** every run. The producer
+  embeds the latest graph + indices + state catalog inline. There is no
+  external fetch at view time; the file opens from any path on any browser.
+
+## Input contract
+
+The dashboard reads three things (all OPTIONAL; missing inputs gracefully
+degrade the view):
+
+1. `<project>/Evidence/_graph/project-graph.json` — nodes + edges.
+2. `<project>/Evidence/<alias>/<source>/_index/entities.yml` for every
+   contributor / source — surfaces `latest_csc_file` + per-entity weekly
+   pointers used by the side panel.
+3. `<project>/State/index.md` — list of v5 State pages, used to populate the
+   side panel's "State pages" section.
+
+If `_graph/project-graph.json` is missing, the dashboard is not produced.
+(Self-check D22.dashboard enforces this.)
+
+## Output contract
+
+A **single self-contained HTML file** with:
+
+- All JS libraries inlined (no CDN at view time).
+- All graph + index + state data inlined via
+  `<script id="graph-data" type="application/json">...</script>`
+  (and sibling `index-data` / `state-data` scripts).
+- All CSS inlined using Clawpilot theme variables (per the
+  `web-artifacts-builder` skill).
+
+## Rendering stack
+
+- **Cytoscape.js v3.x** for graph rendering (Q2 = B locked in the v5 plan).
+  v3.x because it is the current major; v3 ships an ES5-friendly minified
+  build that inlines cleanly into a single HTML file.
+- **cytoscape-cose-bilkent** layout for force-directed node placement.
+- **Optional fuzzy search:** inline `fuse.js` (≈ 9 KB minified) OR a 30-line
+  bespoke fuzzy matcher in the template — producer's choice based on the
+  final inline size budget.
+
+CDN URLs are referenced at template **author time** for traceability, but
+the bytes themselves are **embedded inline** in
+`plugin/templates/dashboard/dashboard.template.html`. The shipped file does
+NOT fetch from any CDN at view time.
+
+## Theming
+
+Follows the Clawpilot `web-artifacts-builder` skill. The template MUST use
+CSS variables (`--bg`, `--fg`, `--accent`, `--surface`, `--border`, etc.)
+defined by that skill so the dashboard adopts the user's Clawpilot theme when
+opened inside Clawpilot, and falls back to a Clawpilot-default light/dark
+scheme when opened in a vanilla browser.
+
+## Views
+
+The dashboard exposes two views via top-level tabs:
+
+1. **Graph view** — Cytoscape canvas. Nodes colored by `source`. Edge style
+   varies by `kind`. Default layout: `cose-bilkent`. Pan + zoom +
+   click-to-select.
+2. **Timeline view** — CSS-grid layout with one column per ISO week (computed
+   from `last_touched_iso` across all nodes). Within each column, nodes are
+   stacked + grouped by source. Click selects same as Graph view.
+
+## Side panel
+
+Clicking a node opens a side panel showing:
+
+- Title + source pill + last_touched date.
+- `weekly_refs` — each rendered as a collapsible block. When expanded, the
+  block loads the cited CSC anchor inline (HTML-rendered markdown extracted
+  client-side from the embedded weekly file text, or — if the file body is
+  too large to inline — a click-through link to the file path).
+- Incoming + outgoing edges with their evidence snippets + kind pill.
+- Related State pages (resolved via `State/index.md`) as `[[wikilink]]`
+  click-throughs that open `State/<category>/<slug>.md`.
+
+## Filters
+
+A header strip exposes:
+
+- **Source** — multi-select pill list of the seven source families.
+- **Alias** — multi-select of contributors who touched the project.
+- **Date range** — slider over ISO-week buckets between
+  `min(first_seen_iso)` and `max(last_touched_iso)` across all nodes.
+
+Filter application is client-side; no re-fetch.
+
+## Search
+
+A search box (top-right of header) does fuzzy match on node `title`.
+Selecting a hit pans the Graph view to the node and opens the side panel.
+
+## Configuration
+
+Producer reads from the user's `m365-mutable.json` /
+`integrations.yml#dashboard.*` (no required keys today; reserved for future
+options like `dashboard.layout` override or `dashboard.maxNodes`).
+
+## Self-check
+
+`D22.dashboard` enforces:
+
+- If `_graph/project-graph.json` exists, `<project>/dashboard.html` exists.
+- WARN (not fail) if `dashboard.html` is older than the graph file (suggests
+  the user ran `link-entities` standalone without `dashboard`).
+
+## Cross-references
+
+- `entity-graph.instructions.md` — input schema (source of truth).
+- `karpathy-state-layout.instructions.md` — `State/index.md` is one of the
+  inputs.
+- `web-artifacts-builder` (Clawpilot user skill) — theming + single-HTML
+  packaging contract.

package/plugin/instructions/entity-graph.instructions.md

@@ -0,0 +1,160 @@
+---
+applyTo: "**"
+description: "v5.0.0 — Cross-source entity graph. One JSON artifact per project: `Evidence/_graph/project-graph.json`. Nodes are source entities (email threads, teams chats, meetings, OneNote pages, SharePoint sites, CRM records, ADO work items) keyed by canonical entity-id URIs from weekly-csc.instructions.md. Edges are typed (closed taxonomy) and carry weekly/+anchor evidence. Deterministic-first; LLM-inferred edges are opt-in. Multi-user safe: merge by node-id + (from,to,kind)."
+---
+
+# Entity Graph — HARD RULE (kushi v5.0.0+)
+
+## Why
+
+After v4.9.0 every entity across every source is captured as a structured CSC
+block with a canonical entity-id. That makes one new artifact possible:
+a project-scoped, cross-source graph that says **which entities relate to
+which** — meeting decisions to ADO work items, customer asks to CRM
+opportunities, email threads to meetings.
+
+This doctrine defines the graph schema, the closed edge taxonomy, the
+producer/reader contract, and the multi-user merge rules. The graph is
+consumed by `dashboard`, `tour`, `build-state`, and `ask-project`.
+
+## Output
+
+- **Path:** `<engagement-root>/<project>/Evidence/_graph/project-graph.json`
+- **Producer:** `link-entities` skill (see `plugin/skills/link-entities/`).
+- **Idempotency:** the file is **fully regenerated** on every `link-entities`
+  run. There is no append/merge across runs — the producer always rewalks
+  `_index/` + `weekly/` and rebuilds from scratch.
+
+## Schema
+
+```jsonc
+{
+  "kushi_version": "5.0.0",
+  "project": "<project-name>",
+  "generated_at": "<ISO-8601 UTC>",
+  "generated_by_alias": "<alias>",
+  "nodes": [
+    {
+      "id": "<canonical-entity-id>",          // see weekly-csc.instructions.md
+      "source": "email|teams|meetings|onenote|sharepoint|crm|ado",
+      "title": "<display title>",
+      "first_seen_iso": "YYYY-MM-DD",
+      "last_touched_iso": "YYYY-MM-DD",
+      "weekly_refs": [
+        "<alias>/<source>/weekly/YYYY-MM-DD_<source>-csc.md#<entity-anchor>"
+      ]
+    }
+  ],
+  "edges": [
+    {
+      "from": "<node-id>",
+      "to":   "<node-id>",
+      "kind": "<one of the closed edge taxonomy values>",
+      "owner": "<optional — action-item-tracks only>",
+      "due":   "<optional ISO date or 'unspecified' — action-item-tracks only>",
+      "evidence": {
+        "weekly_file": "<alias>/<source>/weekly/YYYY-MM-DD_<source>-csc.md",
+        "anchor": "<entity-anchor>",
+        "bullet_snippet": "<≥20 chars verbatim from the source bullet>"
+      },
+      "confidence": "explicit | inferred-llm"
+    }
+  ]
+}
+```
+
+## Canonical entity-id formats
+
+Identical to `weekly-csc.instructions.md` — the graph never invents IDs.
+
+| Source     | Canonical id |
+|------------|--------------|
+| email      | `email://conversation_id=<id>` |
+| teams      | `teams://chat_id=<id>` OR `teams://channel=<teamId>/<channelId>/<rootMessageId>` |
+| meetings   | `meetings://joinurl=<urlencoded>&start=<iso>` |
+| onenote    | `onenote://page/wdpartid=<id>` |
+| sharepoint | `sharepoint://siteurl=<url>` |
+| crm        | `crm://entity=<logicalName>/id=<guid>` |
+| ado        | `ado://org=<org>/project=<project>/workitemid=<int>` |
+
+## Closed edge taxonomy
+
+Edges MUST use one of these `kind` values. Producers that need a new kind
+update this doctrine first.
+
+| `kind` | Meaning |
+|---|---|
+| `references` | X cites/links Y (URL reference in a bullet). |
+| `decides` | X makes a decision that affects Y (bullet appears under Decisions). |
+| `action-item-tracks` | An action item in X is tracked in Y (typically ADO/CRM). Bullet appears under Action Items. `owner` + `due` MAY be populated. |
+| `discusses` | X (meeting/chat/email) discusses Y (CRM/ADO/OneNote/SharePoint). Bullet appears under Topics Discussed or Q & A. |
+| `produced-by` | Artifact Y was produced from discussion X. |
+| `follow-up-of` | Y is chronologically a follow-up to X. |
+| `same-thread` | X and Y are part of the same conversation thread. |
+| `participant-of` | Person Y is a participant in X. (Reserved — person nodes ship in a later release.) |
+
+## Evidence + citation requirements
+
+- Every node has ≥ 1 `weekly_refs` entry that resolves to an existing
+  `<alias>/<source>/weekly/<file>` + `#<anchor>` on disk.
+- Every edge carries `evidence.weekly_file` + `evidence.anchor` that resolve
+  on disk. `evidence.bullet_snippet` is the verbatim bullet text (or a leading
+  prefix ≥ 20 chars) that justified the edge.
+- Edges with `confidence: inferred-llm` MUST include `bullet_snippet` ≥ 20
+  chars — empty inferences are forbidden.
+
+## Confidence
+
+| Value | Meaning |
+|---|---|
+| `explicit` | Produced by the deterministic extractor (URL match, ID token match, conversation-id correlation). The default and the only confidence written when `m365Auth.linkEntities.llmInfer` is false (default). |
+| `inferred-llm` | Produced by an LLM augment pass (WorkIQ call given the project entity inventory). Only emitted when `m365Auth.linkEntities.llmInfer: true` is set in the user's `m365-auth.yml`. |
+
+When the flag is false, the graph contains **only** explicit edges. Toggling
+the flag does not invalidate existing graphs — it just changes what the next
+`link-entities` run will emit.
+
+## Multi-user merge rules
+
+`link-entities` walks **all** contributors under `Evidence/<alias>/<source>/`
+and produces a single project-scoped graph:
+
+1. **Nodes:** dedupe by `id`. If two contributors saw the same entity,
+   merge: `first_seen_iso = min`, `last_touched_iso = max`, `title` from the
+   most-recent contributor, `weekly_refs` is the **union** across contributors
+   (preserves per-contributor citations).
+2. **Edges:** dedupe by `(from, to, kind)`. When duplicates exist, keep the
+   one with the strongest confidence (`explicit > inferred-llm`); ties keep
+   the most-recent weekly_file. `weekly_refs` are not stored on edges —
+   evidence is the single bullet that justified the edge.
+3. **No contributor isolation.** The graph is a project artifact. Contributors
+   never own slices of it; `_graph/` lives outside any `<alias>/` folder.
+
+## Reader contract
+
+Readers (dashboard, tour, build-state, ask-project) MUST treat the graph as
+authoritative for "what relates to what" within a project, and MUST follow
+edges back to `evidence.weekly_file#anchor` to cite their answers.
+
+If `_graph/project-graph.json` is missing, readers fall back to the v4.9.0
+behavior (walk `weekly/` + `_index/` per source).
+
+## Self-check
+
+`D20.graph` enforces the schema:
+
+- Every node has ≥ 1 `weekly_refs` entry that resolves on disk.
+- Every edge has `evidence.weekly_file` + `anchor` that resolve on disk.
+- Every edge `kind` is in the closed taxonomy above.
+- Inferred-llm edges have `bullet_snippet` ≥ 20 chars.
+
+## Cross-references
+
+- `weekly-csc.instructions.md` — canonical entity-id formats (source of truth).
+- `comprehensive-structured-capture.instructions.md` — section taxonomy that
+  drives edge-kind inference (Decisions → `decides`, Action Items →
+  `action-item-tracks`, Topics/Q&A → `discusses`, else → `references`).
+- `karpathy-state-layout.instructions.md` — consumer (writes one State page
+  per cross-source entity in the graph).
+- `dashboard-artifact.instructions.md` — consumer (visualizes the graph).
+- `guided-tour.instructions.md` — consumer (scores + walks the graph).