kushi-agents 4.9.0 → 5.0.0

package/plugin/instructions/karpathy-state-layout.instructions.md

@@ -0,0 +1,124 @@
+---
+applyTo: "**"
+description: "v5.0.0 — Karpathy-style State/ layout. The State/ folder adopts the convention (index.md + log.md + CLAUDE.md + AGENTS.md + `[[wikilinks]]`) so external wiki tools (Understand-Anything, Obsidian, Foam, GitHub-pages wiki viewers) render it without custom work. Backward-compatible with v4.x State/ — v5 pages are distinguished by `kushi_state_page: true` front-matter."
+---
+
+# Karpathy State Layout — HARD RULE (kushi v5.0.0+)
+
+## Why
+
+Today `State/` is a kushi-private synthesis layout. Adopting the
+Karpathy-pattern wiki convention (`index.md` + `log.md` + `[[wikilinks]]`)
+makes State/ readable by any wiki tool — most importantly
+Understand-Anything's `/understand-knowledge` skill, which already does
+community clustering, entity extraction, and graph rendering for free
+**if we adopt their conventions**.
+
+## Required files
+
+Every v5.0.0+ project that has been touched by `build-state` has these under
+`<engagement-root>/<project>/State/`:
+
+| File | Purpose |
+|---|---|
+| `index.md` | Catalog of v5 State pages, grouped by category. Each entry is a `[[wikilink]]`. **Always regenerated** by `build-state` from the set of pages with `kushi_state_page: true` front-matter. |
+| `log.md` | Chronological refresh log. **Appended** (never rewritten) — one entry per `refresh-project` or `bootstrap-project` run with: ISO timestamp, alias, mode (`bootstrap` / `refresh`), sources pulled, entities-added count, entities-updated count, link-entities edges-added count. |
+| `CLAUDE.md` | Operating doc for AI agents reading the project — "this is a kushi project, use `[[wikilinks]]`, cite `Evidence/<alias>/<source>/weekly/...` for every claim." Written from `plugin/templates/state/CLAUDE.template.md` on first run; **preserved if user-edited** thereafter (mtime check; if hash diverges from template hash, do not overwrite). |
+| `AGENTS.md` | **Copy** of `CLAUDE.md` for hosts that look for `AGENTS.md` (Codex, OpenAI agents SDK). NOT a symlink — Windows file-system compat. Written from `plugin/templates/state/AGENTS.template.md` (which is byte-identical to `CLAUDE.template.md`); preserved if user-edited. |
+
+## v5 State page convention
+
+A v5 State page is any `State/<category>/<slug>.md` with `kushi_state_page: true`
+in its front-matter.
+
+### Page categories (closed set)
+
+| Category | Folder | Typical content |
+|---|---|---|
+| People | `State/people/` | Per-stakeholder page. Role, org, interactions, decisions touched. |
+| Opportunities | `State/opportunities/` | Per-CRM-opportunity page. Stage, $ size, decisions, asks. |
+| ADOWorkItems | `State/adoworkitems/` | Per-ADO work item that spans multiple weeks. State, owner, related meetings. |
+| Decisions | `State/decisions/` | Per-cross-source decision. Date, decider, what changed, citations. |
+| Risks | `State/risks/` | Per-risk page. Owner, status, mitigation, citations. |
+| CustomerAsks | `State/customerasks/` | Per-ask page. Asker, ask text, status, evidence. |
+| Meetings | `State/meetings/` | Per-recurring-meeting-series page. Attendees, cadence, recent decisions. |
+| Artifacts | `State/artifacts/` | Per-document/deck/file page. Source link, key bullets, related decisions. |
+
+Folder names are lowercase, no spaces. `build-state` creates them on demand.
+
+### Required front-matter
+
+```yaml
+---
+kushi_state_page: true
+category: opportunity              # one of: people | opportunity | ado-work-item | decision | risk | customer-ask | meeting | artifact
+entity_ids: ["crm://entity=opportunity/id=<guid>"]
+related: ["[[alice-smith]]", "[[hca-weekly-sync]]"]
+last_synthesized_iso: "2026-05-26T20:00:00Z"
+synthesized_by_alias: "ushak"
+---
+```
+
+- `entity_ids` MUST list at least one id that matches a node id in
+  `_graph/project-graph.json`. (Self-check D21.state enforces this.)
+- `related` is a list of `[[slug]]` wikilinks to other State pages.
+- `last_synthesized_iso` is the ISO timestamp of the producing `build-state`
+  run.
+
+### Wikilink rules
+
+- `[[slug]]` resolves to `State/<category>/<slug>.md`. The category folder
+  is inferred from the target page's `category` front-matter.
+- Slugs are **lowercase-kebab-case** derived from the page title (e.g.
+  "HCA FY26 Renewal" → `hca-fy26-renewal`). Producers MUST emit slugs
+  deterministically so two runs converge on the same filename.
+- `[[slug|display text]]` is allowed and rendered the way every wiki tool
+  renders it.
+- A wikilink whose target does not exist on disk is a **defect** flagged by
+  self-check D21.state. `build-state` MUST emit pages in dependency order so
+  every emitted wikilink resolves at end-of-run.
+
+## When to emit a v5 State page
+
+`build-state` emits one page per **cross-source entity** in
+`_graph/project-graph.json` — defined as: any node with ≥ 2 incoming/outgoing
+edges OR present in ≥ 2 distinct weeks (per `weekly_refs`).
+
+Nodes that fail both gates are NOT promoted to a State page; they remain
+addressable via the graph and `weekly/` directly.
+
+One file per cross-source entity. If two nodes legitimately share a slug
+(name collision), append a short stable suffix derived from the source +
+last 6 chars of the id (e.g. `alice-smith-ado-9f3c2a`).
+
+## Backward compatibility
+
+- Pages **without** `kushi_state_page: true` in front-matter are LEFT ALONE.
+  v4.x synthesis files (e.g. `State/00_overview.md`, `State/05_action-items.md`)
+  continue to live in `State/` and are produced by the v4.x synthesis path
+  inside `build-state` (which v5.0.0 retains for `full` profile parity).
+- `State/index.md` regeneration only enumerates v5 pages (those with the
+  flag). Legacy synthesis files are not referenced from `State/index.md`;
+  their existing front-matter / cross-links remain valid.
+- No migration. No deletion. Users may continue to use v4.x State files
+  indefinitely; v5 pages live alongside.
+
+## Self-check
+
+`D21.state` enforces this layout:
+
+- Every `State/<category>/*.md` with `kushi_state_page: true` has all required
+  front-matter fields.
+- Every `entity_ids` value matches a node in `_graph/project-graph.json`.
+- Every `[[wikilink]]` in a v5 page resolves to an existing v5 page on disk.
+- `State/index.md` lists every v5 page that exists.
+
+## Cross-references
+
+- `entity-graph.instructions.md` — source of node identity for `entity_ids`.
+- `guided-tour.instructions.md` — `State/tour.md` is a sibling artifact that
+  uses the same wikilinks.
+- `dashboard-artifact.instructions.md` — dashboard consumes `State/index.md`
+  to render the side panel's "State pages" section.
+- `host-portability.instructions.md` — `CLAUDE.md` / `AGENTS.md` mirroring
+  rationale.

package/plugin/plugin.json

@@ -61,18 +61,25 @@
         "refresh-project",
         "fde-intake",
         "fde-report",
-        "fde-triage"
+        "fde-triage",
+        "link-entities",
+        "dashboard",
+        "tour"
       ],
       "prompts": [
         "bootstrap",
         "refresh",
         "fde-intake",
         "fde-report",
-        "fde-triage"
+        "fde-triage",
+        "link-entities",
+        "dashboard",
+        "tour"
       ],
       "templates": [
         "init",
-        "fde"
+        "fde",
+        "dashboard"
       ],
       "reference_packs": [
         "fde"
@@ -82,8 +89,12 @@
         "refresh",
         "fde-intake",
         "fde-report",
-        "fde-triage"
-      ]
+        "fde-triage",
+        "link-entities",
+        "dashboard",
+        "tour"
+      ],
+      "_": null
     },
     "full": {
       "extends": "standard",
@@ -123,4 +134,4 @@
       ]
     }
   }
-}
+}

package/plugin/prompts/dashboard.prompt.md

@@ -0,0 +1,29 @@
+---
+name: dashboard
+description: "v5.0.0 — Render <project>/dashboard.html — single self-contained interactive Cytoscape.js v3 dashboard from the entity graph."
+argument-hint: "Project name; reads project-graph.json + _index/entities.yml + State/index.md and writes dashboard.html"
+agent: kushi
+tools: [search, read/readFile, edit, agent]
+---
+
+## User Input
+
+```text
+${input:project:Project name, e.g. HCA}
+```
+
+# /dashboard
+
+Route to `@Kushi dashboard <project>`.
+
+Pure renderer. Reads:
+- `<engagement-root>/<project>/Evidence/_graph/project-graph.json` (REQUIRED)
+- `<engagement-root>/<project>/Evidence/<alias>/<source>/_index/entities.yml` (optional)
+- `<engagement-root>/<project>/State/index.md` (optional)
+
+Writes:
+- `<engagement-root>/<project>/dashboard.html` — single self-contained file (Cytoscape.js v3 + cose-bilkent + Clawpilot theme variables)
+
+Delegates to `dashboard` skill via `plugin/templates/dashboard/embedder.ps1`. Idempotent — fully regenerated each run. If the graph is missing, this is a no-op (run `@Kushi link-entities <project>` first).
+
+Tracking: see `tracking.instructions.md`. Write `<workspace>/.kushi/tracking/runs/{{YYYY-MM-DD}}-<project>-dashboard.md` as the final step.

package/plugin/prompts/link-entities.prompt.md

@@ -0,0 +1,30 @@
+---
+name: link-entities
+description: "v5.0.0 — Build the cross-source entity graph (Evidence/_graph/project-graph.json) for a project. Deterministic; opt-in LLM augment."
+argument-hint: "Project name; walks per-source _index/entities.yml + weekly CSC bodies and writes project-graph.json"
+agent: kushi
+tools: [search, read/readFile, edit, agent]
+---
+
+## User Input
+
+```text
+${input:project:Project name, e.g. HCA}
+```
+
+# /link-entities
+
+Route to `@Kushi link-entities <project>`.
+
+Pure builder. Reads:
+- `<engagement-root>/<project>/Evidence/<alias>/<source>/_index/entities.yml` (every contributor, every source)
+- `<engagement-root>/<project>/Evidence/<alias>/<source>/weekly/*-csc.md` (resolves citation bodies)
+
+Writes:
+- `<engagement-root>/<project>/Evidence/_graph/project-graph.json`
+
+Delegates to `link-entities` skill. Use this when you want the graph refreshed without triggering source pulls. `refresh` and `bootstrap` call this automatically at the end of every run.
+
+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`.
+
+Tracking: see `tracking.instructions.md`. Write `<workspace>/.kushi/tracking/runs/{{YYYY-MM-DD}}-<project>-link-entities.md` as the final step.

package/plugin/prompts/tour.prompt.md

@@ -0,0 +1,30 @@
+---
+name: tour
+description: "v5.0.0 — Render <project>/State/tour.md — auto-generated week-in-review walkthrough scored by recency_weight × cross_ref_count."
+argument-hint: "Project name (optionally --top N); reads project-graph.json and writes State/tour.md"
+agent: kushi
+tools: [search, read/readFile, edit, agent]
+---
+
+## User Input
+
+```text
+${input:project:Project name, e.g. HCA}
+```
+
+# /tour
+
+Route to `@Kushi tour <project> [--top N]`.
+
+Pure renderer. Reads:
+- `<engagement-root>/<project>/Evidence/_graph/project-graph.json` (REQUIRED)
+- `<engagement-root>/<project>/State/index.md` (optional — for `[[wikilink]]` resolution)
+
+Writes:
+- `<engagement-root>/<project>/State/tour.md`
+
+Delegates to `tour` skill via `plugin/skills/tour/build-tour.ps1`. Scoring: `recency_weight × cross_ref_count` (14-day half-life × graph degree). DFS-walks edges in priority order (`decides` → `action-item-tracks` → `discusses` → `references` → others). Default top-N = 10 (override with `--top N` or `m365Mutable.tour.topN`).
+
+If the graph is missing, this is a no-op (run `@Kushi link-entities <project>` first).
+
+Tracking: see `tracking.instructions.md`. Write `<workspace>/.kushi/tracking/runs/{{YYYY-MM-DD}}-<project>-tour.md` as the final step.

package/plugin/skills/ask-project/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: "ask-project"
-version: "3.0.0"
-description: "Read-only Q&A over an already-bootstrapped project (v4.9.0+). Answers natural-language questions using State/, Evidence/, and weekly CSC files via 3-step reader fallback (_index/entities.yml → weekly/*.md → legacy snapshot/ + stream/). Cited; no source pulls; no outbound."
+version: "4.0.0"
+description: "Read-only Q&A over an already-bootstrapped project (v5.0.0). Answers natural-language questions using State/, Evidence/, and weekly CSC files. v5 cross-source questions go GRAPH-FIRST: consult Evidence/_graph/project-graph.json before walking weekly files. 3-step reader fallback (_index/entities.yml → weekly/*.md → legacy snapshot/ + stream/). Cited; no source pulls; no outbound."
 ---
 
 # Skill: ask-project
@@ -84,6 +84,16 @@ If the question doesn't fit, default to: `State/00_overview.md` + greppable scan
 
 ### Step 3 — Load files (cheapest → richest, stop when sufficient)
 
+**Graph-first for cross-source questions (v5.0.0).** If the question
+touches more than one source (e.g. "what did the team commit to in Teams
+that we then tracked in ADO?", "which decisions reference the OneNote
+architecture page?"), FIRST consult
+`<project>/Evidence/_graph/project-graph.json` to identify the relevant
+node ids + edges, then jump directly to the cited weekly files via each
+node's `weekly_refs`. This avoids whole-folder scans. If the graph is
+absent or stale → fall back to the legacy walking strategy below and
+suggest `@Kushi refresh <project>` in the answer footer.
+
 1. Load the **primary files** identified in Step 2.
 2. If primary files don't have the answer, expand to: latest week's `Evidence/<alias>/_Consolidated/` file.
 3. If still insufficient, expand to per-source latest week files for the relevant source.
@@ -185,4 +195,5 @@ Explicit triggers also accepted:
 
 ## Changelog
 
+- **v4.0.0 (kushi v5.0.0, 2026-05-26)**: graph-first cross-source resolution — consult `Evidence/_graph/project-graph.json` before walking weekly files when a question spans sources. Falls back to v4.9.0 walking strategy if graph absent/stale.
 - **v3.0.0 (kushi v4.9.0, 2026-05-26)**: 3-step reader fallback chain (`_index/entities.yml` → `weekly/*.md` → legacy `snapshot/` + `stream/`). New citation form `weekly/<YYYY-MM-DD>_<source>-csc.md#<anchor>`. Legacy citations suffixed `(legacy pre-v4.9.0 layout)`. Output marked with `Source-layout:` footer.

package/plugin/skills/bootstrap-project/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: "bootstrap-project"
-version: "3.0.0"
+version: "4.0.0"
 description: "First-time setup for a project (kushi v4.9.0+): machine preflight, side-by-side config, engagement-root + project resolution, customer-hint discovery sweep across all WorkIQ-driven sources, initial full-window CSC pull across all enabled sources writing weekly/ + _index/ per source. All pull-* skills write CSC blocks per comprehensive-structured-capture.instructions.md. Verbatim-by-default — every enabled source dispatched, no silent skips. Discovery sweep MANDATORY before declaring blocked-config. CRM bootstrap discovery REQUIRED per `crm-bootstrap-discovery.instructions.md`. Writes per-user refresh report per `run-reports.instructions.md`. Cleans stale no-match notes on resolution per `cleanup-on-resolution.instructions.md`. Builds State/ only on `full` profile. Idempotent."
 ---
 
@@ -264,6 +264,20 @@ If `kushi-install.json#profile` is `full` → dispatch `build-state` to render `
 
 If `standard` (or `core`) → **skip this step**. Note in the run summary: *"State/ rollup skipped (profile = `standard`). To enable, re-install with `npx kushi-agents --clawpilot --profile full --force`."*
 
+### Step 6b — Cross-source graph + dashboard + tour (kushi v5.0.0)
+
+After `build-state` (or in its place on `standard` profile, since graph/
+dashboard/tour read from Evidence + v5 State pages when present),
+dispatch the v5 enrichment chain in order:
+
+1. `link-entities` → `<project>/Evidence/_graph/project-graph.json`
+2. `dashboard`     → `<project>/dashboard.html`
+3. `tour`          → `<project>/State/tour.md`
+
+Each step records its outcome in the run summary; a failure does NOT
+block the next step. If `link-entities` produced no graph, skip 2 and 3
+cleanly and surface a run-summary line.
+
 ### Step 7 — Verify + summary
 
 Per `side-by-side-config.instructions.md` "Verification" rule, list all live config files (path + size + last-write time). Show:
@@ -297,4 +311,6 @@ When this skill exposes a reusable defect (auth pattern, doctrine gap, layout mi
 
 ## Changelog
 
+
+- **v4.0.0 (kushi v5.0.0, 2026-05-26)**: After build-state, dispatch the v5 enrichment chain — `link-entities` → `dashboard` → `tour`. Each step's success/failure is recorded in the run summary; a failure of one step does not block the next.
 - **v3.0.0 (kushi v4.9.0, 2026-05-26)**: Drops "1 verbatim per source per bootstrap" carve-out. Walks the full boundary window per source. Preflight ensures `weekly/` + `_index/` exist per source. All pull-* invoked write CSC blocks per comprehensive-structured-capture.instructions.md.

package/plugin/skills/build-state/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: "build-state"
-version: "3.0.0"
-description: "Render <project>/State/*.md from existing Evidence (v4.9.0+). 3-step reader fallback: _index/entities.yml → weekly/*.md → legacy snapshot/ + stream/. No source pulls — pure re-render. Latest fact wins on conflicts. Every assertion cited. Always updates Open Questions."
+version: "4.0.0"
+description: "Render <project>/State/ from existing Evidence. v5.0.0: emits BOTH the legacy 00–09 synthesis (retained for `full` profile parity) AND the new Karpathy-style layout (index.md + log.md + per-entity pages under people/ opportunities/ adoworkitems/ decisions/ risks/ customerasks/ meetings/ artifacts/, plus CLAUDE.md + AGENTS.md). 3-step reader fallback: _index/entities.yml → weekly/*.md → legacy snapshot/ + stream/. No source pulls — pure re-render. Latest fact wins on conflicts. Every assertion cited. Always updates Open Questions. v5 pages are ADDITIVE and distinguished by `kushi_state_page: true` front-matter."
 ---
 
 # Skill: build-state
@@ -70,7 +70,45 @@ Update `<project>/State/09_open-questions.md`:
 - If a question is no longer relevant (scope cut, decision overtaken), flip to ⚫ Stale with reason.
 - Bump the file's `As of:` line. Briefly mention in run-log how many opened / partial / resolved / staled.
 
-### Step 6 — Banner
+### Step 6 — v5 Karpathy emission (ADDITIVE; per `karpathy-state-layout.instructions.md`)
+
+After Steps 1–5 produce the legacy 00–09 files, ALSO emit the v5 layout:
+
+1. Ensure category folders exist under `<project>/State/`:
+   `people/`, `opportunities/`, `adoworkitems/`, `decisions/`, `risks/`,
+   `customerasks/`, `meetings/`, `artifacts/`.
+2. For each entity surfaced via the reader-fallback chain, write one
+   markdown file using `..\..\templates\state\page.template.md`. Filename
+   slug = lowercase ascii of the entity title (alphanumeric + hyphen, ≤80
+   chars), with `.md` suffix. Place it in the matching category folder.
+   The front-matter MUST include `kushi_state_page: true`, the canonical
+   `entity_ids: [...]` (graph node ids), and a `related: [...]` array of
+   other state-page paths (relative, slash-separated) discovered via graph
+   edges (`decides`, `discusses`, `action-item-tracks`, `references`,
+   `produced-by`, `follow-up-of`, `same-thread`, `participant-of`).
+3. Regenerate `<project>/State/index.md` from
+   `..\..\templates\state\index.template.md` by enumerating every file
+   under `State/**/*.md` whose front-matter has `kushi_state_page: true`,
+   grouped by category, sorted by filename. The index MUST be fully
+   overwritten each run.
+4. Append a new dated entry to `<project>/State/log.md`
+   (from `..\..\templates\state\log.template.md`):
+   `## YYYY-MM-DD HH:mm UTC — build-state run by <alias>` plus a short
+   summary (`pages_written: N`, `categories_touched: …`,
+   `legacy_files_rewritten: 00..09`).
+5. Ensure `<project>/State/CLAUDE.md` and `<project>/State/AGENTS.md` exist
+   and are byte-identical copies of
+   `..\..\templates\state\CLAUDE.template.md` (per the doctrine — Windows
+   does not honor symlinks reliably, so we copy).
+6. `[[wikilink]]` rendering: page bodies SHOULD use the
+   `[[category/slug]]` form for cross-references; the build does not need
+   to resolve these — they are render-time hints for human + agent
+   readers.
+
+v5 emission is gated on `m365Mutable.state.layout: "karpathy"` (default
+true). If set to `"legacy"`, skip Step 6.
+
+### Step 7 — Banner
 
 Top of every State file:
 
@@ -89,4 +127,5 @@ Top of every State file:
 
 ## Changelog
 
+- **v4.0.0 (kushi v5.0.0, 2026-05-26)**: ADDITIVE Karpathy-style emission — per-entity pages under `State/<category>/`, `State/index.md`, `State/log.md`, `State/CLAUDE.md`, `State/AGENTS.md`. Distinguished by `kushi_state_page: true`. Legacy 00–09 synthesis is retained for `full` profile parity. Gated on `m365Mutable.state.layout` (default `karpathy`). See `..\..\instructions\karpathy-state-layout.instructions.md`.
 - **v3.0.0 (kushi v4.9.0, 2026-05-26)**: 3-step reader fallback chain (`_index/entities.yml` → `weekly/*.md` → legacy `snapshot/` + `stream/`). New citation form `weekly/<YYYY-MM-DD>_<source>-csc.md#<anchor>`. Legacy citations suffixed `(legacy pre-v4.9.0 layout)`. Output marked with `Source-layout:` footer.

package/plugin/skills/dashboard/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: "dashboard"
+version: "1.0.0"
+description: "v5.0.0 — Render an interactive HTML dashboard for a project. Reads Evidence/_graph/project-graph.json + per-source _index/entities.yml + State/index.md and emits a single self-contained <project>/dashboard.html via plugin/templates/dashboard/dashboard.template.html. Uses Cytoscape.js v3 + cose-bilkent layout (inlined), Clawpilot theme variables (per the web-artifacts-builder skill), two-view tabs (Graph + Timeline), source/alias/date filters, fuzzy search, side panel with cited CSC blocks. Idempotent — fully regenerated each run."
+---
+
+# Skill: dashboard
+
+> **v5.0.0 — Single-file HTML dashboard producer.** See
+> `..\..\instructions\dashboard-artifact.instructions.md` for the full
+> contract: inputs, outputs, theming, views, filters, search, side panel.
+>
+> **Theming uses the Clawpilot `web-artifacts-builder` skill.** All CSS
+> variables (`--bg`, `--fg`, `--accent`, `--surface`, `--border`, …) come from
+> that skill's theme contract so the dashboard adopts the user's Clawpilot
+> palette when opened inside Clawpilot, and falls back to a default
+> light/dark scheme in a vanilla browser.
+
+## When to run
+
+- Automatically as part of `refresh-project` (after `link-entities` +
+  `build-state`) and `bootstrap-project` (same chain).
+- Manually: `@Kushi dashboard <project>`.
+
+## Inputs
+
+- `<project>` — already-bootstrapped project root.
+- `<project>/Evidence/_graph/project-graph.json` — REQUIRED. Missing graph →
+  skill is a no-op (dashboard is not produced).
+- `<project>/Evidence/<alias>/<source>/_index/entities.yml` — OPTIONAL per
+  contributor / source.
+- `<project>/State/index.md` — OPTIONAL. Used to populate the side panel's
+  "State pages" list.
+
+## Output
+
+- `<project>/dashboard.html` — single self-contained HTML file.
+
+## Steps
+
+### Step 1 — Verify inputs
+
+If `<project>/Evidence/_graph/project-graph.json` does not exist, exit
+cleanly with a one-line message ("no graph — run `link-entities` first").
+Do NOT produce a dashboard.
+
+### Step 2 — Collect data
+
+1. Read the graph JSON.
+2. Walk all `Evidence/<alias>/<source>/_index/entities.yml` files and merge
+   their entries into a single index map keyed by entity id (used by the
+   side panel to surface `latest_csc_file` quickly).
+3. Read `State/index.md` if present; parse the v5 state pages it lists.
+
+### Step 3 — Render
+
+Invoke the embedder:
+
+```pwsh
+pwsh plugin/templates/dashboard/embedder.ps1 `
+    -TemplatePath plugin/templates/dashboard/dashboard.template.html `
+    -OutPath <project>/dashboard.html `
+    -GraphJsonPath <project>/Evidence/_graph/project-graph.json `
+    -IndexJsonPath <intermediate> `
+    -StateJsonPath <intermediate>
+```
+
+The embedder substitutes the `__GRAPH_JSON__`, `__INDEX_JSON__`, and
+`__STATE_JSON__` placeholders in the template with the stringified JSON of
+the collected data, and writes the result to `<project>/dashboard.html`.
+
+### Step 4 — Verify
+
+Confirm `<project>/dashboard.html` exists and is non-empty. Open the file
+in a browser (manual verification step — not automated here) to confirm:
+the graph view renders, the side panel opens on node click, filters work.
+
+## Hard rules
+
+- The output is a **single self-contained HTML file**. No external CDN
+  fetches at view time.
+- Theming uses the Clawpilot `web-artifacts-builder` skill's CSS variables.
+- Idempotent — the file is fully regenerated on every run.
+- NEVER write outside `<project>/dashboard.html`.
+
+## Triggers
+
+- "dashboard `<X>`"
+- "build dashboard for `<X>`"
+- "@Kushi dashboard `<X>`"
+- (auto) end of `refresh-project` / `bootstrap-project`
+
+## References
+
+- `..\..\instructions\dashboard-artifact.instructions.md`
+- `..\..\instructions\entity-graph.instructions.md`
+- `..\..\instructions\karpathy-state-layout.instructions.md`
+- `..\..\instructions\issue-recovery.instructions.md`
+- Clawpilot user skill: `web-artifacts-builder` (theme variables, single-HTML
+  packaging contract).
+
+## Issue Recovery
+
+When this skill exposes a reusable defect (template placeholder mismatch,
+data shape drift, theming regression), apply the [Issue Recovery Rule](../../instructions/issue-recovery.instructions.md):
+fix the template or embedder first, re-render, verify in browser, then
+re-run self-check D22.dashboard.
+
+## Changelog
+
+- **v1.0.0 (kushi v5.0.0, 2026-05-26)**: initial release. Cytoscape.js v3 +
+  cose-bilkent + Clawpilot theme variables; two-view tabs; side panel;
+  filters; fuzzy search.