diff --git a/.ai-workflows/ops-dashboard.md b/.ai-workflows/ops-dashboard.md
new file mode 100644
index 0000000..8ddffc7
--- /dev/null
+++ b/.ai-workflows/ops-dashboard.md
@@ -0,0 +1,27 @@
+# Supervisor dashboard recovery
+
+The repository's aidevops supervisor dashboard is maintained outside the
+WordPress plugin runtime by the local stats scheduler. If a dashboard freshness
+alert reports that the pinned dashboard issue is stale while `stats.log` still
+shows hourly `Health issues: updated ... repo(s)` messages, verify the local
+health-issue cache before changing plugin code.
+
+## Triage
+
+1. Confirm the launchd job exists and is running.
+2. Inspect `~/.aidevops/logs/stats.log` for the affected repository.
+3. Check the pinned dashboard issue body for the `last_refresh:` marker.
+4. Confirm the cache file naming expected by the current aidevops version.
+
+## Cache migration failure mode
+
+Older aidevops releases wrote role-qualified cache files such as
+`health-issue-<user>-supervisor-<owner>-<repo>`. Current dashboard refresh code
+expects `health-issue-<canonical-user>-<owner>-<repo>`. If only the older cache
+file exists and the repository has no active PRs, assigned issues, or workers,
+the activity guard can skip resolving the already-open dashboard issue, leaving
+the existing dashboard stale.
+
+Restore the expected cache entry to the pinned dashboard issue number, then run
+the dashboard update path again. Verify that the pinned issue's `updated_at` and
+`last_refresh:` marker are current before closing the freshness alert.
diff --git a/.ai-workflows/readme.md b/.ai-workflows/readme.md
index 9119154..daedf15 100644
--- a/.ai-workflows/readme.md
+++ b/.ai-workflows/readme.md
@@ -14,6 +14,7 @@ This directory contains workflow documentation for AI assistants working with th
 - **incremental-development.md**: Time-efficient approach for incremental development and testing
 - **local-env-vars.md**: Local development environment paths and URLs
 - **multi-repo-workspace.md**: Guidelines for working in workspaces with multiple repositories
+- **ops-dashboard.md**: Triage notes for aidevops supervisor dashboard freshness alerts
 - **release-process.md**: Steps for preparing and publishing new releases
 - **wiki-documentation.md**: Guidelines for maintaining wiki documentation