docs: describe the layered Insights dashboard and heat by=device

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01P5cxPQdSGJnjXCYY9GeWXt

README.md

@@ -319,11 +319,18 @@ Hubs also track **read heat**: viewer opens and downloads count as human
 reads, share-link hits as share reads, and agent tool reads (reported by
 the sync hooks via `bdrive read-log`) as agent reads — sync replication
 never counts. Folder listings show heat dots and 30-day read counts to
-every member, and admins / org owners get an **Insights** view (⋯ menu)
-plotting each file by reads × days since last change: the hot-but-stale
-quadrant is the knowledge people rely on that nobody maintains. The API
+every member, and admins / org owners get an **Insights** dashboard
+(⋯ menu), four sections with an all/human/agent lens: a **treemap** of
+every file (cell size = reads, color = staleness, ⚠ on hot+stale — click
+through to any file), the **reads × freshness** scatter whose hot-but-stale
+quadrant is the knowledge people rely on that nobody maintains, the
+**hot path** (top files by reads, agent/human split — effectively the
+team's agent context window), and an **agent coverage matrix** (which
+agent devices read which folders). The API
 (`GET /api/p/<id>/heat?prefix=&days=`) exposes only aggregate counts,
-distinct-reader counts, and last-read times — never who read what.
+distinct-reader counts, and last-read times — never who read what;
+`?by=device` adds the agent-only per-device folder breakdown (device
+identity is already public via history; human emails never appear).
 
 ### Authentication
 

plugin/skills/beardrive/SKILL.md

@@ -154,10 +154,14 @@ Hubs aggregate reads per file — viewer opens and downloads count as human
 reads, share-link hits as share reads, and hook-reported agent reads as
 agent reads; `/store` sync replication never counts. The web UI shows heat
 dots and read counts on folder listings (all members), and admins / org
-owners get an **Insights** view (⋯ menu) plotting every file by 30-day
-reads × days since last change — the hot-but-stale quadrant is the list of
-files to fix first. Counts only, never reader identities. API:
-`GET /api/p/<id>/heat?prefix=&days=30`. Server config: `"reads":
+owners get an **Insights** dashboard (⋯ menu, all/human/agent lens): a
+treemap of every file (size = 30-day reads, color = staleness, ⚠ =
+hot+stale, click-through), a reads × freshness scatter (hot-but-stale
+quadrant = fix first), the hot path (top files by reads, agent/human
+split), and an agent coverage matrix (agent devices × folders). Counts
+only, never human reader identities. API:
+`GET /api/p/<id>/heat?prefix=&days=30`, plus `?by=device` for the
+agent-only per-device folder breakdown. Server config: `"reads":
 {"enabled": true, "retention_days": 400}` (on by default in hub mode).
 
 ### Examples to walk a user through