kushi-agents 4.9.0 → 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,6 +1,6 @@
 {
   "name": "kushi-agents",
-  "version": "4.9.0",
+  "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": {

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/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".

package/plugin/instructions/host-portability.instructions.md

@@ -0,0 +1,77 @@
+---
+applyTo: "**"
+description: "v5.0.0 — Host portability contract. `plugin/agents/kushi.agent.md` is the single source of truth for the multi-host top-level agent contract. Per-skill `plugin/skills/<n>/SKILL.md` files are host-portable (Claude Code skills, Clawpilot, Codex AGENTS.md, Copilot custom agents, Cursor, Gemini CLI). The install scripts mirror agent.md → SKILL.md for hosts that discover via SKILL.md (e.g. Clawpilot). No code changes are required by this doctrine — it is a contract write-up."
+---
+
+# Host Portability — HARD RULE (kushi v5.0.0+)
+
+## Why
+
+Kushi is shipped through several distinct host surfaces:
+
+- **GitHub Copilot** (VS Code) — discovers via `.github/copilot-instructions.kushi.md`.
+- **Clawpilot** (a Copilot fork) — discovers via `~/.copilot/m-skills/kushi/SKILL.md`.
+- **Claude Code** — discovers via the Claude Code skills system (per-skill
+  `SKILL.md` in a known location).
+- **Codex / OpenAI Agents SDK** — discovers via `AGENTS.md` at the project root.
+- **Cursor** — discovers via `.cursor/rules/*.md`.
+- **Gemini CLI** — discovers via per-skill markdown.
+
+All of these surfaces consume the **same** prose. v5.0.0 formalizes that one
+file is the source of truth and the install scripts mirror it where required.
+
+## Source of truth
+
+`plugin/agents/kushi.agent.md` is the canonical top-level agent contract. It
+describes the verbs, the routing, the global rules, and the references to
+every skill / instruction / prompt.
+
+Every other host-facing entry point (the live install's `SKILL.md`, the
+`.github/copilot-instructions.kushi.md` shim, the `AGENTS.md` written into a
+project's `State/`) is **derived** from this file via:
+
+1. `src/main.mjs` — mirrors `plugin/agents/kushi.agent.md` →
+   `~/.copilot/m-skills/kushi/SKILL.md` during `npx kushi-agents
+   --clawpilot` install. See the existing top-of-file comment in
+   `src/main.mjs`:
+
+   > `// Mirror agents/kushi.agent.md as top-level SKILL.md for Clawpilot discovery.`
+
+2. `plugin/templates/state/CLAUDE.template.md` / `AGENTS.template.md` —
+   per-project agent doc, written by `build-state` into `<project>/State/`.
+   The two templates are byte-identical (see
+   `karpathy-state-layout.instructions.md`); both reiterate "this is a kushi
+   project, use `[[wikilinks]]`, cite `Evidence/<alias>/<source>/weekly/...`
+   for every claim."
+
+Self-check `D4` already enforces byte-identical parity between
+`plugin/agents/kushi.agent.md` and the live install's `SKILL.md`.
+
+## Per-skill portability
+
+Every per-skill `plugin/skills/<n>/SKILL.md` is host-portable by construction:
+
+- Frontmatter (`name`, `version`, `description`) matches the Claude Code
+  skills system and the Clawpilot skills system.
+- Skill prose uses relative markdown links (`../../instructions/<x>.md`) that
+  resolve regardless of which host root the file is rendered under.
+- No host-specific tool names appear in the SKILL.md body. Tool dispatch
+  happens through neutral verbs (`WorkIQ`, `m365_*`) that each host wires up
+  in its own way.
+
+## No code changes
+
+This doctrine introduces **no** new code or mirror behavior. The install
+scripts already do the right thing; v5.0.0 simply documents the contract so
+future hosts can be added by:
+
+1. Reading `plugin/agents/kushi.agent.md`.
+2. Pointing the new host's discovery at that file (or a mirrored copy).
+3. Re-running self-check to confirm `D4` still passes.
+
+## Cross-references
+
+- `kushi-config-root.instructions.md` — config layout is also host-portable
+  (vscode `<workspace>/.kushi/` vs Clawpilot `~/.copilot/m-skills/kushi/`).
+- `karpathy-state-layout.instructions.md` — per-project `State/CLAUDE.md` +
+  `State/AGENTS.md` are the per-project portability mirror.