From dbb29d449a4e3867c951dcd54e033459c072bada Mon Sep 17 00:00:00 2001
From: Phil Larson <hello@phillarson.xyz>
Date: Fri, 10 Jul 2026 23:18:39 -0700
Subject: [PATCH] docs: explain planner overseer eye badge

---
 .changeset/planner-overseer-eye-badge-docs.md | 7 +++++++
 docs/dashboard-guide.md                       | 2 ++
 packages/cli/skill/fusion/SKILL.md            | 3 +++
 3 files changed, 12 insertions(+)
 create mode 100644 .changeset/planner-overseer-eye-badge-docs.md

diff --git a/.changeset/planner-overseer-eye-badge-docs.md b/.changeset/planner-overseer-eye-badge-docs.md
new file mode 100644
index 0000000000..d0cfc89cb6
--- /dev/null
+++ b/.changeset/planner-overseer-eye-badge-docs.md
@@ -0,0 +1,7 @@
+---
+"@runfusion/fusion": patch
+---
+
+summary: Document the planner-overseer eye badge on task cards.
+category: internal
+dev: Clarifies that the eye icon reflects non-idle plannerOverseerState, not a human view marker.
\ No newline at end of file
diff --git a/docs/dashboard-guide.md b/docs/dashboard-guide.md
index 5a40d07634..766dbf61cd 100644
--- a/docs/dashboard-guide.md
+++ b/docs/dashboard-guide.md
@@ -200,6 +200,8 @@ Features:
 <!-- FNXC:PlannerOversight 2026-07-04-19:10: FN-7539 fix — the badge was rendering on virtually every card because the schema default `autonomous` tier was treated as "meaningfully configured". Narrowed the gate so an inherited (no per-task-override, no non-default workflow tier) `autonomous` level renders no badge; only an explicit per-task override or a resolved workflow/effective tier that is not the plain inherited default surfaces the badge. -->
 - Task cards show a read-only **oversight-level badge** (`Observe`, `Steer`, or `Auto-recovery`) in the meta-badges cluster reflecting the effective planner-oversight level, but only when oversight is *meaningfully configured* — an explicit per-task override (including an explicit `autonomous` override), or a resolved workflow/effective tier of `observe`/`steer` (`data-testid="card-oversight-badge"`). A card that merely **inherits** the schema default `autonomous` tier (no per-task override, no non-default workflow tier) renders no badge and no empty `.card-meta-badges` shell. The badge is also absent when the effective level is explicitly "off", **and** while an inherited (no per-task-override) workflow tier is still being resolved (in flight or not yet fetched) — it never shows a guessed default during that window.
 <!-- FNXC:PlannerOversight 2026-07-04-HH:MM: FN-7542 removed the FN-7516 active-overseer-state ("Executor") indicator described above as unwanted per-card noise — it fired on nearly every in-progress card. The oversight-level badge documented above is unaffected. -->
+<!-- FNXC:PlannerOversight 2026-07-11-00:00: FN-7592 reintroduced a compact active-overseer state indicator as an Eye glyph instead of a wide text badge, using the engine-provided transient plannerOverseerState rather than locally guessing from task fields. -->
+- Task cards show a compact **planner-overseer eye badge** (`data-testid="planner-overseer-state-badge"`) when the engine reports a non-idle transient `plannerOverseerState`. The eye badge is an active-overseer state marker, not a human-read/view indicator: `watching` means passive monitoring, `steering`/`recovering` mean active guidance or recovery is underway, and `awaiting-confirmation` means a human decision is required before the overseer can continue. Hover/tap exposes the composed tooltip with the overseer's reason, watched stage/signal, and pending-confirmation note when present.
 <!-- FNXC:PlannerOversight 2026-07-04-17:00: FN-7517 adds interactive task-detail planner-overseer controls (quick level change, manual nudge, stop oversight, explain current action) alongside the FN-7516 read-only card badges above. These controls live ONLY in TaskDetailModal, not TaskCard.
 
 FNXC:PlannerOversight 2026-07-05-00:00: FN-7604 collapses the desktop inline cluster (documented below through FN-7545/FN-7546) into the single universal overflow-menu dropdown that FN-7545 originally built for mobile only — the dropdown is now the ONE canonical surface on every viewport, desktop included. -->
diff --git a/packages/cli/skill/fusion/SKILL.md b/packages/cli/skill/fusion/SKILL.md
index 874a636e1e..e4a5c0eadd 100644
--- a/packages/cli/skill/fusion/SKILL.md
+++ b/packages/cli/skill/fusion/SKILL.md
@@ -71,6 +71,9 @@ Use `fn_task_list` to see all tasks grouped by column. Use `column` param to fil
 **Show task details:**
 Use `fn_task_show` with the task ID (e.g., FN-001) to see steps, progress, and log.
 
+**Planner oversight eye badge:**
+On dashboard task cards, an eye icon means `plannerOverseerState` is non-idle — not that a human viewed the task. States: `watching` = passive monitoring; `steering`/`recovering` = active overseer guidance or repair; `awaiting-confirmation` = human decision required. Before manually taking over stuck in-review/merging tasks, inspect the overseer state and intervention timeline so you do not race Fusion's own recovery loop.
+
 **Plan complex work:**
 Use `fn_task_plan` for AI-guided planning that interviews you before creating the task.