feat: dashboard design polish (#185)

* feat: polish dashboard visual design

* feat: enrich dashboard stat card sparklines

* feat: polish dashboard bar fills

* feat: add contextual dashboard next moves

* feat: add dashboard relationship visualizations

* feat: add dashboard readiness queue

* fix: reduce opportunity map mark density

* docs: add dashboard map guide

* docs: add editable dashboard guide

* Polish dashboard storytelling and promotional guide

* chore: publish Reponomics README dashboard [skip ci]

* Revert "chore: publish Reponomics README dashboard [skip ci]"

This reverts commit 7502f6d.

* Add traffic chart code activity overlay

* Fix unlock vault hero overlay

* Add demo preview make target

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: hesreallyhim

.github/workflows/README.md

@@ -22,6 +22,8 @@ This directory contains the repository's CI, release, dependency, and supply-cha
 
 - [`publish-demo.yml`](publish-demo.yml) builds the generated public demo repository and publishes it to `reponomics-dashboard-demo`. It supports manual publication and scheduled daily refresh. Scheduled refresh uses an approved source ref, imports the encrypted synthetic data seed into the demo repository's Actions artifact storage, and deploys the committed Pages dashboard shell without requiring daily human approval.
 
+- [`promotional-dashboard-guide.yml`](promotional-dashboard-guide.yml) is a manual skeleton for refreshing the promotional HTML/PDF dashboard guide. It runs the same `make dashboard-guide-refresh` path used locally, with ephemeral `npx`/`pipx` guide tooling, and intentionally does not publish or commit artifacts by default.
+
 - [`pre-release-validation.yml`](pre-release-validation.yml) is a manual, non-publishing validation pass for candidate refs. It builds the template from the candidate source, runs template smoke checks, runs generated-template consumer e2e against the same candidate action runtime, dry-runs template publication, and uploads the generated template for inspection.
 
 - [`sbom-provenance.yml`](sbom-provenance.yml) generates a repository SPDX SBOM and creates release source/SBOM attestations for release and manual runs. Release asset upload is explicitly disabled because immutable releases cannot be mutated after publication, and dependency snapshot upload is disabled so the third-party SBOM action runs with a read-only job token.

.github/workflows/promotional-dashboard-guide.yml

@@ -0,0 +1,42 @@
+name: Promotional dashboard guide
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build-guide:
+    name: Build promotional guide artifacts
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        # actions/checkout v7.0.0
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0
+
+      - name: Setup Python
+        # actions/setup-python v6.3.0
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1
+        with:
+          python-version: "3.11"
+
+      - name: Setup Node
+        # actions/setup-node v6.4.0
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e
+        with:
+          node-version: "24"
+
+      - name: Prepare ephemeral guide tooling
+        run: |
+          python -m pip install --user pipx
+          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+          npx --yes --package playwright -- playwright install --with-deps chromium
+
+      - name: Build promotional guide
+        run: make dashboard-guide-refresh
+
+      # Skeleton integration point:
+      # Upload docs/promotional/dashboard-guide/ and docs/promotional/pdf/reponomics-dashboard-map.pdf
+      # or commit them from a maintainer-approved workflow if desired.

.gitignore

@@ -16,6 +16,7 @@ docs/index.html
 README.generated.md
 .DS_Store
 .vscode/
+.playwright-mcp/
 
 .tmp/
 

Makefile

@@ -4,15 +4,20 @@
 .PHONY: test js-test js-coverage js-smoke coverage complexity security security-audit audit-runtime-lock lock-runtime validate-runtime-lock update-vendored-assets
 .PHONY: lint type-check markdown-format
 .PHONY: validate validate-action validate-workflows validate-vendored-assets
-.PHONY: build-template verify-template build-and-verify-generated verify-workflow-classification validate-template-action-ref validate-template-accepted-action template-smoke template-consumer-e2e template-action-boundary-e2e template-compat-e2e template-public-action-e2e template-accepted-action-e2e template-release-gates package-template-release publish-template-dry-run publish-template publish-template-staging-dry-run publish-template-staging build-demo verify-demo render-demo-preview preview-demo-site publish-demo-dry-run publish-demo
-.PHONY: fixtures fixture-collect fixture-publish fixture-rotate-key preview-collection-quality-dashboard dashboard-scenario-snapshots update-dashboard-scenario-snapshots clean
+.PHONY: build-template verify-template build-and-verify-generated verify-workflow-classification validate-template-action-ref validate-template-accepted-action template-smoke template-consumer-e2e template-action-boundary-e2e template-compat-e2e template-public-action-e2e template-accepted-action-e2e template-release-gates package-template-release publish-template-dry-run publish-template publish-template-staging-dry-run publish-template-staging build-demo verify-demo render-demo-preview preview-demo preview-demo-site publish-demo-dry-run publish-demo
+.PHONY: fixtures fixture-collect fixture-publish fixture-rotate-key preview-collection-quality-dashboard dashboard-scenario-snapshots update-dashboard-scenario-snapshots dashboard-guide-assets dashboard-guide dashboard-guide-refresh clean
 
 VENV := venv
 PYTHON := $(VENV)/bin/python
 PIP := $(VENV)/bin/pip
 NODE ?= node
+NPX ?= npx
 PIPX ?= pipx
 JS_SMOKE_PYTHON ?= python3
+GUIDE_PYTHON ?= $(PIPX) run --with Pillow --with reportlab python
+GUIDE_NODE ?= $(NPX) --yes --package playwright -- node
+GUIDE_NODE_PATH ?=
+GUIDE_ASSET_CAPTURE_ARGS ?=
 ANTIPASTA := $(VENV)/bin/antipasta
 PIP_AUDIT := $(VENV)/bin/pip-audit
 PIP_COMPILE := $(VENV)/bin/pip-compile
@@ -182,6 +187,17 @@ js-coverage: ## Run JavaScript module tests with Node coverage reporting
 js-smoke: ## Check dashboard JavaScript syntax and flattened secure runtime assembly
 	NODE=$(NODE) $(JS_SMOKE_PYTHON) scripts/check_dashboard_js_smoke.py
 
+dashboard-guide-assets: render-demo-preview ## Capture dashboard guide screenshot assets from the rendered demo preview
+	NODE_PATH="$(GUIDE_NODE_PATH)" $(GUIDE_NODE) scripts/capture_dashboard_guide_assets.mjs \
+		--dashboard-dir $(DEMO_PREVIEW_DIR) \
+		--out-dir docs/promotional/dashboard-guide/assets \
+		$(GUIDE_ASSET_CAPTURE_ARGS)
+
+dashboard-guide: ## Build editable HTML and PDF dashboard guide artifacts
+	$(GUIDE_PYTHON) scripts/build_dashboard_guide.py
+
+dashboard-guide-refresh: dashboard-guide-assets dashboard-guide ## Refresh dashboard guide screenshots, HTML, and PDF
+
 coverage: install ## Run tests with coverage report
 	$(PYTHON) -m pytest tests -v --cov=dashboard_action --cov-report=term-missing --cov-report=xml --cov-fail-under=$(COVERAGE_FAIL_UNDER)
 
@@ -312,6 +328,8 @@ render-demo-preview: build-demo ## Render the demo Pages dashboard locally in di
 	@test -s $(DEMO_PREVIEW_DIR)/assets/demo-unlock.css
 	@echo "Demo Pages preview rendered: $(DEMO_PREVIEW_DIR)/index.html"
 
+preview-demo: preview-demo-site ## Render and serve the local demo dashboard preview
+
 preview-demo-site: render-demo-preview ## Serve the local demo Pages dashboard preview
 	@echo "Serving demo preview at http://$(DEMO_PREVIEW_HOST):$(DEMO_PREVIEW_PORT)/"
 	$(PYTHON) -m http.server $(DEMO_PREVIEW_PORT) --bind $(DEMO_PREVIEW_HOST) --directory $(DEMO_PREVIEW_DIR)

dashboard_action/runtime/scripts/load_data.py

@@ -47,6 +47,9 @@
     actionable_insights,
     actionable_insights_structured,
 )
+from load_data_modules.narratives import (
+    narrative_insights_structured,
+)
 from load_data_modules.quality import (
     collection_quality,
 )
@@ -91,11 +94,21 @@
     "latest_repo_metrics_per_day",
     "load_collection_status",
     "load_collection_days",
+    "load_collection_endpoints",
+    "load_code_frequency_weekly",
+    "load_contributor_activity_weekly",
     "load_daily",
+    "load_event_index",
+    "load_issue_label_snapshots",
+    "load_issue_pr_snapshots",
+    "load_languages",
     "load_paths",
     "load_referrers",
+    "load_release_assets",
     "load_repo_metrics",
+    "load_topics",
     "load_traffic_coverage",
+    "narrative_insights_structured",
     "repo_growth_series",
     "repo_metric_deltas",
     "storage",
@@ -144,6 +157,51 @@ def load_traffic_coverage(data_dir=None):
     return _load_csv("traffic-coverage.csv", data_dir)
 
 
+def load_event_index(data_dir=None):
+    """Load repo-event-index.csv and return the raw row list."""
+    return _load_csv("repo-event-index.csv", data_dir)
+
+
+def load_release_assets(data_dir=None):
+    """Load repo-release-assets.csv and return the raw row list."""
+    return _load_csv("repo-release-assets.csv", data_dir)
+
+
+def load_languages(data_dir=None):
+    """Load repo-languages.csv and return the raw row list."""
+    return _load_csv("repo-languages.csv", data_dir)
+
+
+def load_topics(data_dir=None):
+    """Load repo-topics.csv and return the raw row list."""
+    return _load_csv("repo-topics.csv", data_dir)
+
+
+def load_issue_pr_snapshots(data_dir=None):
+    """Load repo-issue-pr-snapshots.csv and return the raw row list."""
+    return _load_csv("repo-issue-pr-snapshots.csv", data_dir)
+
+
+def load_issue_label_snapshots(data_dir=None):
+    """Load repo-issue-label-snapshots.csv and return the raw row list."""
+    return _load_csv("repo-issue-label-snapshots.csv", data_dir)
+
+
+def load_collection_endpoints(data_dir=None):
+    """Load collection-endpoints.csv and return the raw row list."""
+    return _load_csv("collection-endpoints.csv", data_dir)
+
+
+def load_code_frequency_weekly(data_dir=None):
+    """Load repo-code-frequency-weekly.csv and return the raw row list."""
+    return _load_csv("repo-code-frequency-weekly.csv", data_dir)
+
+
+def load_contributor_activity_weekly(data_dir=None):
+    """Load repo-contributor-activity-weekly.csv and return the raw row list."""
+    return _load_csv("repo-contributor-activity-weekly.csv", data_dir)
+
+
 def _load_csv(filename, data_dir=None):
     data_path = data_dir or storage.DATA_DIR
     return _filter_published_rows(storage.read_csv(os.path.join(data_path, filename)))