kushi-agents 4.9.0 → 5.0.1

package/README.md

@@ -3,6 +3,13 @@
 [![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)
+
+> **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.
 
@@ -30,6 +37,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 +102,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,6 +1,6 @@
 {
   "name": "kushi-agents",
-  "version": "4.9.0",
+  "version": "5.0.1",
   "description": "Install Kushi — multi-source project evidence agent with Comprehensive Structured Capture (CSC) into weekly-only files across Email, Teams, OneNote, Loop, SharePoint, Meetings, CRM, ADO. Meetings retain a sibling verbatim/ audit folder. WorkIQ-only for M365 sources (Graph / m365_* FORBIDDEN as fallbacks; user-paste is first-class). Host-agnostic.",
   "type": "module",
   "bin": {

package/plugin/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/agentskills-compliance.instructions.md

@@ -0,0 +1,144 @@
+---
+name: "agentskills-compliance"
+description: "Spec-compliance doctrine. Aligns every plugin/skills/<name>/SKILL.md with the conventions from https://agentskills.io/skill-creation/best-practices and /optimizing-descriptions. Defines size caps, load-on-trigger layout, gotchas, checklists, validation loops, plan-validate-execute, defaults-not-menus, and description-optimization rules. Enforced by self-check D30."
+applies_to: "every plugin/skills/<name>/SKILL.md"
+since: "kushi v5.0.1"
+---
+
+# agentskills-compliance — doctrine
+
+A SKILL.md is loaded **fully** into the agent's context window the moment it triggers. Every token competes with the conversation, system prompt, and other active skills. Compliance with the agentskills.io best-practices is therefore not stylistic — it is a context-budget contract.
+
+Authoritative external references:
+
+- <https://agentskills.io/skill-creation/best-practices>
+- <https://agentskills.io/skill-creation/optimizing-descriptions>
+
+## Rules (HARD)
+
+### 1. Size cap
+
+Every `plugin/skills/<name>/SKILL.md` MUST be:
+
+- ≤ **500 lines**, AND
+- ≤ **5000 tokens** (approximated by `char_count / 4`).
+
+Oversize SKILLs MUST be split per rule 2 below. Enforced by `self-check D30.skill-size`.
+
+### 2. Load-on-trigger layout
+
+`plugin/skills/<name>/SKILL.md` contains:
+
+- front-matter (`name`, `version`, `description`)
+- one-paragraph purpose
+- `## Gotchas` (top 5) — pull-* skills MUST have this
+- numbered or checklist procedure
+- `## Validation loop` (writer skills)
+- output contract
+
+Bulk content (full canonical WorkIQ prompts, full error-mode taxonomies, deep schema details, worked examples) moves to `plugin/skills/<name>/references/<topic>.md`. Standard reference filenames:
+
+| File | Contents |
+|------|----------|
+| `references/canonical-prompts.md` | Full WorkIQ prompt text (tier A/B/C, CSC, recovery) |
+| `references/error-modes.md` | Error taxonomy with retry semantics |
+| `references/taxonomy.md` | CSC schema deep details (where source-specific) |
+| `references/examples.md` | Full worked examples |
+| `references/playwright-fallback.md` | Opt-in fallback procedures |
+
+Every reference cited from SKILL.md MUST be cited with an **explicit trigger**, not a passive link. Trigger templates:
+
+```
+> Load references/canonical-prompts.md when constructing the WorkIQ query for this source.
+> Load references/error-modes.md if the API returns non-200, or WorkIQ returns "throttled".
+> Load references/playwright-fallback.md only when WorkIQ body-retrieval rate stays poor across ≥2 refreshes.
+```
+
+Enforced by `self-check D30.references-layout`.
+
+### 3. Gotchas (top 5)
+
+Every `pull-*` SKILL.md MUST surface its top 5 gotchas in a `## Gotchas` section near the top (immediately after the H1 / opening paragraph; before `## Steps` or `## Procedure`).
+
+Format: bullet list. Each bullet starts with the **concrete failure mode**, then the correction.
+
+```markdown
+## Gotchas
+
+- **Moved pages keep original wdsectionfileid** → if a section returns `page-body-unavailable` or zero `wdpartid` entries, the pages were authored elsewhere and moved. Open OneNote desktop, drag pages back into target section, retry.
+- **WorkIQ tier C requires ONE page per call** — batching multiple pages into a single ask returns empty results. Loop over pageIds, one call each.
+```
+
+Pull from `plugin/learnings/<source>.md` if present; else extract from the SKILL body itself. Enforced by `self-check D30.gotchas-section`.
+
+### 4. Checklists for orchestrators
+
+Orchestrator SKILLs (`bootstrap-project`, `refresh-project`, `build-state`, `link-entities`, `dashboard`, `tour`) MUST use GitHub checkbox syntax `- [ ]` for their step lists so progress is trackable in tooling and in conversation.
+
+```markdown
+- [ ] Step 1 — Resolve engagement root.
+- [ ] Step 2 — Resolve project alias.
+- [ ] Step 3 — Preflight per source.
+```
+
+Enforced by `self-check D30.checklist-orchestrators`.
+
+### 5. Validation loops (writer skills)
+
+Every skill that writes files to `Evidence/`, `State/`, `_graph/`, `dashboards/`, or `tours/` MUST end with a `## Validation loop` section:
+
+```markdown
+## Validation loop
+
+After writing outputs:
+
+1. Run self-check targeted at this skill: `pwsh plugin/skills/self-check/run.ps1 -Targeted <area>`
+2. If failures: fix and re-run the affected step (not the whole skill).
+3. Repeat until self-check exits 0.
+4. Only then update `run-log.yml` with success status.
+```
+
+Enforced by `self-check D30.validation-loop`.
+
+### 6. Plan-validate-execute (link-entities + build-state)
+
+See `plan-validate-execute.instructions.md`. The skill writes a plan JSON, validates against a source of truth, then executes.
+
+### 7. Defaults not menus
+
+Pick ONE tool for each procedure step. Alternatives are escape hatches and MUST live in `references/` (e.g. `references/playwright-fallback.md`), not in the main SKILL body. The SKILL.md procedure does not enumerate alternatives.
+
+### 8. Procedures over declarations
+
+Write what the agent must DO, not what the skill IS. Imperative voice, concrete steps.
+
+### 9. Description optimization
+
+Per <https://agentskills.io/skill-creation/optimizing-descriptions> the `description:` front-matter is the sole trigger signal. It MUST describe **WHEN to use** the skill (trigger conditions), not just what it does. Convention for kushi skills:
+
+```yaml
+description: "USE WHEN <situational trigger> AND <precondition>. DO NOT USE for <near-miss>. <one-line capability summary>."
+```
+
+- BAD: `"Pulls OneNote pages and saves them as markdown."`
+- GOOD: `"USE WHEN refreshing project evidence for a known kushi project AND the project boundaries.onenote.section_ids list is non-empty. DO NOT USE for global OneNote search or non-kushi note capture."`
+
+Hard limit: 1024 characters. Enforced loosely by `self-check D30.description-optimized` (checks for the literal substring `USE WHEN` or `WHEN ` near the start of `description:`).
+
+## Migration checklist (per oversized SKILL)
+
+- [ ] Move full WorkIQ prompts → `references/canonical-prompts.md`
+- [ ] Move full error taxonomy → `references/error-modes.md`
+- [ ] Move source-specific schema details → `references/taxonomy.md`
+- [ ] Move opt-in fallbacks (Playwright, Edge profile bootstrap) → `references/playwright-fallback.md`
+- [ ] Add `## Gotchas` (top 5)
+- [ ] Add `## Validation loop` (if writer)
+- [ ] Replace inline blocks with "Load references/&lt;file&gt; when …" pointers
+- [ ] Bump skill version (minor) since structure changed
+- [ ] Re-run `self-check D30` and `npm test`
+
+## References
+
+- `instructions/plan-validate-execute.instructions.md`
+- `instructions/capture-learnings.instructions.md`
+- `instructions/issue-recovery.instructions.md`

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).

package/plugin/instructions/guided-tour.instructions.md

@@ -0,0 +1,100 @@
+---
+applyTo: "**"
+description: "v5.0.0 — Guided tour. Auto-generated week-in-review markdown walkthrough at `<project>/State/tour.md`. Score: `recency_weight × cross_ref_count`. recency_weight = exp(-days_since_last_touched / 14). cross_ref_count = degree in the graph. DFS through edges in priority order (decides → action-item-tracks → discusses → references → others). Default top-N = 10 (configurable via `m365Mutable.tour.topN`)."
+---
+
+# Guided Tour — HARD RULE (kushi v5.0.0+)
+
+## Why
+
+After link-entities + build-state, the project has a graph and a wiki, but
+nothing tells a reader **where to start**. The tour is a small ranked
+walkthrough that picks the most-recent, highest-degree entities and DFS-walks
+their connections in order of edge importance.
+
+## Output
+
+- **Path:** `<engagement-root>/<project>/State/tour.md`
+- **Producer:** `tour` skill.
+- **Idempotency:** fully regenerated each run.
+- **Empty case:** if `_graph/project-graph.json` has zero nodes, `tour.md` is
+  written with a single line: `_No graph nodes — run @Kushi refresh first._`
+
+## Scoring
+
+For each node N in the graph:
+
+```
+days_since = max(0, today - last_touched_iso)        # in whole days, UTC
+recency_weight = exp(- days_since / 14)              # 14-day half-life ≈ ln(2)/14 ≈ 0.0495
+cross_ref_count = degree(N)                          # in + out edges, dedupe by edge identity
+score(N) = recency_weight × cross_ref_count
+```
+
+Sort nodes by `score` descending. Take the top-N (default 10; configurable
+via `m365Mutable.tour.topN` in the user's per-project mutable config).
+
+## DFS ordering
+
+Tour stops are emitted in DFS order starting from the highest-scored node:
+
+1. Start with the highest-scored unvisited node → emit it as the next stop.
+2. Pick the next node by walking that node's edges in **edge priority order**:
+   1. `decides`
+   2. `action-item-tracks`
+   3. `discusses`
+   4. `references`
+   5. (any other kind in `entity-graph.instructions.md` taxonomy)
+   Within a priority bucket, prefer the edge whose target has the highest
+   unvisited `score`.
+3. Skip nodes already visited (cycle break).
+4. If the DFS hits a dead end before reaching N stops, restart from the
+   next-highest-scored unvisited node.
+5. Stop after N stops emitted.
+
+## Per-stop markdown shape
+
+```markdown
+## <ordinal>. <Node title>
+
+> _Why this matters:_ <one-line synthesis — recency + degree + dominant edge
+> kind, e.g. "Touched 3 days ago; ties together 5 ADO items and 2 CRM
+> opportunities."_
+
+- **Source:** `<source>` · last touched `YYYY-MM-DD`
+- **Cite:** [`<alias>/<source>/weekly/<file>#<anchor>`](<relative path>)
+- **Related State pages:** [[slug-a]] · [[slug-b]] · …
+```
+
+Citations MUST resolve on disk (D23.tour enforces this).
+
+## Header
+
+The file starts with:
+
+```markdown
+---
+kushi_tour: true
+generated_at: <ISO-8601 UTC>
+generated_by_alias: <alias>
+top_n: <N>
+score_basis: "recency_weight × cross_ref_count (14-day half-life)"
+---
+
+# Guided Tour — <project>
+
+> _Auto-generated week-in-review. <N> top entities by recency × cross-reference count._
+```
+
+## Self-check
+
+`D23.tour` enforces:
+
+- If `_graph/project-graph.json` has ≥ 1 node, `State/tour.md` exists.
+- Every tour stop's citation resolves to an existing weekly file + anchor.
+
+## Cross-references
+
+- `entity-graph.instructions.md` — source of nodes + edge taxonomy.
+- `karpathy-state-layout.instructions.md` — `[[wikilink]]` resolution rules
+  used by per-stop "Related State pages".