# @PLAN — ControlTower (Go TUI) parallel build plan

This file breaks the project into **independent, parallel tasks** that multiple agents can implement with minimal merge conflicts.

- Source spec: `PLAN.md`
- **Sub-agent models to use:**
  - `anthropic/claude-haiku-4-5-20251001`
  - `github-copilot/claude-haiku-4.5`

## 0) Ground rules (so work composes cleanly)

### 0.1 File ownership
Each task below “owns” a set of files. Agents should **only modify files they own**, except for the explicit shared-contract files listed next.

### 0.2 Shared contracts (edit carefully)
These files are the primary integration points; keep them stable and coordinate changes:

- `internal/model/issue.go` (Issue model + enums)
- `internal/collectors/collector.go` (collector interface + status)
- `cmd/controltower/main.go` (wiring + flags)

### 0.3 Go module + imports
- Use standard package layout from `PLAN.md`.
- No persistence; acknowledgements are in-memory only.
- Prefer small packages with narrow responsibilities.

## 1) Proposed repo layout (target)

- `cmd/controltower/main.go`
- `internal/model/` (Issue + enums)
- `internal/store/` (IssueStore)
- `internal/engine/` (scheduler + concurrency)
- `internal/collectors/collector.go` (shared interface)
- `internal/collectors/host/` (`disk.go`, `mem.go`, `load.go`, `net.go`)
- `internal/collectors/k8s/` (`client.go`, `informers.go`, `issues_*.go`, `rollup.go`, `unreachable.go`)
- `internal/ui/` (`app.go`, `table.go`, `details.go`, `keys.go`, `styles.go`)
- `internal/export/json.go`

## 2) Integration contracts (must align across tasks)

### 2.1 Issue model contract
`internal/model.Issue` must support (per `PLAN.md`):

- Stable `ID` for dedupe
- `Category`, `Priority`, `State` enums
- `Title`, `Details`, `Evidence` (key/value), `SuggestedFix`
- `FirstSeen`, `LastSeen`

Sorting defaults:
- `Priority` desc → `LastSeen` desc (recency)

### 2.2 Collector contract
Create `internal/collectors/collector.go` with:

- `type Collector interface { Name() string; Interval() time.Duration; Collect(ctx context.Context) ([]model.Issue, Status, error) }`
- `type Status` describing health (OK/Degraded/Error + message + last success time)

Collectors should:
- Be fast; respect context cancellation.
- Return issues that are “currently true” for this tick (the store handles resolve-after).

### 2.3 Store contract
`IssueStore.Upsert(now, issues)`:
- Dedupes by `Issue.ID`
- Tracks `FirstSeen`/`LastSeen`
- Maintains `State` (Open/Acknowledged/Resolved)
- Resolves only after `resolveAfter` (default 30s) of absence

Ack/unack should be in-memory and keyed by Issue ID.

### 2.4 Engine contract
Engine runs all collectors concurrently on their intervals with timeouts:

- Host collectors: `collector_timeout_fast` (250ms)
- K8s list/poll: `collector_timeout_k8s_list` (2s)

Engine produces periodic snapshots for UI/export:
- `[]model.Issue` sorted per default
- Collector health summary (Host OK / K8s OK/DEGRADED)

## 3) Task breakdown (parallelizable)

Each task includes: scope, owned files, external dependencies, and acceptance checks.

### Task A — Project scaffold + wiring (1 agent)
**Goal:** create runnable binary, shared contracts, and minimal plumbing.

- Owns:
  - `go.mod`, `go.sum`
  - `cmd/controltower/main.go`
  - `internal/collectors/collector.go`
  - (Optional) `internal/buildinfo/` or version constants
- Provides:
  - CLI flag `--export /path/issues.json` (calls exporter and exits)
  - Default config constants (refresh interval 1s, resolveAfter 30s, timeouts)
  - K8s enabled only if kubeconfig exists (per spec)
- Must not implement heavy logic from other tasks; stub as needed.

**Acceptance:** `go test ./...` passes; `go run ./cmd/controltower` starts.

---

### Task B — Core model package (1 agent)
**Goal:** implement the type system used everywhere.

- Owns:
  - `internal/model/issue.go` (+ small helper files if needed)
- Implements:
  - Enums: `Category`, `Priority`, `State` (stringers / JSON marshal if needed)
  - `Issue` struct + helpers:
    - `func (p Priority) Weight() int` (for sorting)
    - `func (i Issue) Age(now time.Time) time.Duration`
    - `func SortIssuesDefault([]Issue)`
- Evidence representation: `map[string]string` (simple, JSON-friendly).

**Acceptance:** unit tests for sorting + JSON marshalling (if added).

---

### Task C — IssueStore (1 agent)
**Goal:** dedupe, state transitions, resolve-after, flap suppression.

- Owns:
  - `internal/store/store.go`
  - `internal/store/store_test.go`
- Needs:
  - `resolveAfter` default 30s
  - Flap suppression: don’t resolve on a single missed tick
  - `Acknowledge(id)`, `Unack(id)` (in-memory only)
  - `Snapshot()` returning issues (optionally copy to avoid races)

**Acceptance:** tests covering:
- Dedup and timestamp updates
- Ack persists while issue present
- Resolve-after triggers only after absence window

---

### Task D — Engine scheduler (1 agent)
**Goal:** concurrency orchestration + snapshot publication.

- Owns:
  - `internal/engine/engine.go`
  - `internal/engine/engine_test.go`
- Integrates:
  - Collectors from Task E (host) and Task F (k8s)
  - Store from Task C
  - Produces:
    - periodic snapshots (channel or callback) for UI
    - immediate refresh on demand (key `r`)
- Concurrency:
  - Run collectors on their own tickers
  - Per-collector context timeouts
  - Track last error/health per collector

**Acceptance:** deterministic tests with fake collectors verifying:
- timeout handling
- interval scheduling
- merge/upsert calls

---

### Task E — Host collectors MVP (1–2 agents)
Split into sub-tasks to avoid conflicts:

#### E1 Disk collector
- Owns: `internal/collectors/host/disk.go` (+ tests)
- Reads `/proc/mounts`, uses `statfs`.
- Filters pseudo filesystems.
- Thresholds:
  - `P1` if usage or inode usage ≥ 92%
  - `P0` if ≥ 98%

#### E2 Memory + swap collector
- Owns: `internal/collectors/host/mem.go` (+ tests)
- Reads `/proc/meminfo`.
- Applies thresholds in `PLAN.md`.

#### E3 Load collector
- Owns: `internal/collectors/host/load.go` (+ tests)
- Reads `/proc/loadavg` + CPU count.
- Sustained windows: track 120s rolling window.

#### E4 Network collector
- Owns: `internal/collectors/host/net.go` (+ tests)
- Reads `/proc/net/route` for default route.
- Reads `/sys/class/net/*/operstate` for “any UP”.
- `P1` if no default route AND any non-loopback UP.

**Acceptance:** each collector has unit tests using fixture files or temp fakes.

---

### Task F — Kubernetes collector MVP (2 agents recommended)
This is the largest area; split by responsibility.

#### F1 K8s client + connectivity + unreachable grace
- Owns:
  - `internal/collectors/k8s/client.go`
  - `internal/collectors/k8s/unreachable.go`
- Responsibilities:
  - Build client-go config from kubeconfig current context.
  - Connectivity tracking: emit `Kubernetes/P0` only after **10s continuous failure**.
  - RBAC errors: emit single `P2` “Insufficient RBAC …” issue per resource.

#### F2 Informers / polling fallback + issue rules + rollups
- Owns:
  - `internal/collectors/k8s/informers.go`
  - `internal/collectors/k8s/issues_pods.go`
  - `internal/collectors/k8s/issues_nodes.go`
  - `internal/collectors/k8s/issues_workloads.go`
  - `internal/collectors/k8s/issues_events.go`
  - `internal/collectors/k8s/rollup.go`
- Responsibilities:
  - Prefer informers (LIST+WATCH caches).
  - If watch fails repeatedly, degrade to periodic LIST and emit a `P1` degraded issue.
  - High-signal rules per `PLAN.md`.
  - Rollups:
    - group by `(namespace, reason, kind)`
    - if group size ≥ 20 emit rollup issue with samples
  - Cap: `k8s.max_issues = 200` after rollups.

**Acceptance:**
- Unit tests for rule functions (pure logic tests with fake objects)
- Manual run against a cluster (optional) verifies unreachable grace.

---

### Task G — Bubble Tea TUI (2 agents recommended)
Split UI work to reduce merge conflicts.

#### G1 App model + layout framing
- Owns:
  - `internal/ui/app.go`
  - `internal/ui/styles.go`
- Responsibilities:
  - Header bar (host/time/age/P0..P3 counts/collector health)
  - Layout: header + table + details pane
  - Wiring to engine snapshot updates (tea.Msg)

#### G2 Table + details + keybindings
- Owns:
  - `internal/ui/table.go`
  - `internal/ui/details.go`
  - `internal/ui/keys.go`
- Responsibilities:
  - Main table columns: `Pri | Cat | Title | Age | State`
  - Search `/`, filter `p`/`c`, sort `s`, focus `tab`
  - Ack/unack `a`
  - Optional: Expand details with `enter`

**Acceptance:**
- UI runs and remains responsive with 1k synthetic issues.

---

### Task H — Exporter (1 agent)
**Goal:** JSON snapshot export, no persistence.

- Owns:
  - `internal/export/json.go`
- Implements:
  - `WriteIssues(path string, issues []model.Issue) error`
  - Used by `--export` and (optional) UI hotkey `E`

**Acceptance:** `--export` writes valid JSON and exits 0.

---

### Task I — End-to-end integration pass (1 agent)
**Goal:** compose all pieces, fix mismatches, and ensure acceptance criteria.

- Owns (only light edits across packages):
  - small wiring fixes in `cmd/controltower/main.go`
  - integration tweaks in engine/UI
- Validates:
  - Without kubeconfig: app runs, host collectors work
  - With kubeconfig but unreachable cluster: `P0` appears only after 10s
  - With reachable cluster: issues populate; rollups protect UI

## 4) 8-agent assignment (recommended)

This assignment uses exactly **8 agents** and keeps overlaps minimal. For each agent, you can use either model:
- `anthropic/claude-haiku-4-5-20251001`
- `github-copilot/claude-haiku-4.5`

**Phase 1 (parallel, no blocking):** Agents 1–6
- **Agent 1 (Scaffold/contracts):** Task A
- **Agent 2 (Model):** Task B
- **Agent 3 (Store):** Task C
- **Agent 4 (Engine):** Task D
- **Agent 5 (Host collectors):** Task E1–E4 (own all `internal/collectors/host/*`)
- **Agent 6 (Exporter):** Task H

**Phase 2 (parallel, after A+B exist):** Agents 7–8
- **Agent 7 (Kubernetes collector):** Task F1 + F2 (own all `internal/collectors/k8s/*`)
- **Agent 8 (TUI + integration):** Task G1 + G2 + Task I (UI owns `internal/ui/*`; integration touches wiring only)

Notes:
- Agent 5 is bundled intentionally to avoid conflicts in `internal/collectors/host/`.
- K8s (Agent 7) is bundled intentionally to avoid informer/client contract churn.
- UI + integration (Agent 8) is bundled so UI/engine message types stay aligned.

**Start order (min waiting):**
- Start Agents **1–6** immediately.
- Start Agents **7–8** once Agent 1 has created `go.mod` + `internal/collectors/collector.go` and Agent 2 has created `internal/model/issue.go` (so imports compile).

**Merge order (min conflicts / keep build green):**
1) Agent 1 (scaffold/contracts) — establishes module + shared interfaces
2) Agent 2 (model) — unblocks compilation for most packages
3) Agent 3 (store) + Agent 6 (export) — mostly isolated, compile-time checks
4) Agent 4 (engine) — depends on store/model/contracts
5) Agent 5 (host collectors) — depends on model/contracts; can land anytime after (1,2)
6) Agent 7 (k8s) — depends on model/contracts; may need go.sum updates
7) Agent 8 (UI + integration) — land last; touches wiring and stabilizes API edges

**If you use a single shared branch:**
- Prefer merging frequently in the above order and rebasing lagging work onto the latest `main`.
- If a shared contract must change, have Agent 1 do the change and notify all other agents.

## 5) Suggested agent prompts (copy/paste)

Use each prompt with model `anthropic/claude-haiku-4-5-20251001` or `github-copilot/claude-haiku-4.5`.

### Prompt template
- Implement only the task scope.
- Touch only owned files.
- Add small unit tests where indicated.
- Keep APIs aligned with the shared contracts.

#### Agent prompt: Task B (model)
"Implement `internal/model/issue.go` per @PLAN.md §2.1. Add sorting helpers and minimal tests. Do not modify other packages."

#### Agent prompt: Task C (store)
"Implement `internal/store` IssueStore with dedupe, ack/unack, resolve-after (30s), flap suppression, and tests. Import and use `internal/model`."

#### Agent prompt: Task D (engine)
"Implement `internal/engine` scheduler running collectors concurrently with per-collector timeouts and health tracking. Provide snapshot publication for UI; add tests with fake collectors."

#### Agent prompt: Task E1–E4 (host collectors)
"Implement the specified host collector in `internal/collectors/host/*.go` reading Linux proc/sys files as described. Emit Issues with correct IDs/evidence/priority and add small tests using fixtures/mocks."

#### Agent prompt: Task F1 (k8s base)
"Implement kubeconfig client creation and unreachable grace logic. Emit a single P0 issue only after 10s continuous failure; emit P2 on RBAC denial. Keep rule logic separate."

#### Agent prompt: Task F2 (k8s rules + rollups)
"Implement informer/polling collector and rule + rollup logic with caps. Keep rule functions testable. Coordinate only via shared contracts."

#### Agent prompt: Task G1/G2 (UI)
"Implement Bubble Tea UI pieces per @PLAN.md: header/table/details/keybindings. Subscribe to engine snapshots and keep rendering cheap."

#### Agent prompt: Task H (export)
"Implement JSON exporter used by `--export` and optional UI hotkey. Ensure output includes all Issue fields."

#### Agent prompt: Task I (integration)
"Integrate all packages, resolve API mismatches, and verify acceptance scenarios. Keep changes minimal and avoid refactors."

#### Agent prompt: Task J (Help overlay)
"Implement in-app help overlay showing all keybindings. Add `?` key binding in keys.go and create help.go with overlay model and render logic."

#### Agent prompt: Task K (Direct priority jump)
"Add numeric bindings `0`/`1`/`2`/`3` to jump directly to P0/P1/P2/P3 filter. Keep `p` cycle for `all`."

#### Agent prompt: Task L (Visual filter indicators)
"Add highlighted style for active filters in header. Apply FilterActive style when pri= or cat= are set."

#### Agent prompt: Task M (Better empty state)
"Show friendly message 'All systems healthy' when no issues instead of just 'No issues'."

#### Agent prompt: Task N (Bulk ack all visible)
"Add `A` key to acknowledge all currently visible issues at once. Optimize updates and refresh counts."

#### Agent prompt: Task O (Page navigation)
"Document page up/down keys already supported by bubbles/table. Ensure they work correctly in Update handler."

#### Agent prompt: Task P (Home/End jump)
"Add `g`/`G` bindings to jump to first/last row quickly like vim/less."

#### Agent prompt: Task Q (Vi-style nav)
"Add `j`/`k` bindings as alternatives to arrow keys for down/up navigation."

#### Agent prompt: Task R (Collector health icons)
"Replace text 'ok=1 deg=0 err=Z' with visual icons (✓ ⚠ ✗). Use lipgloss styles."

#### Agent prompt: Task S (Issue count warning near cap)
"Add warning indicator in header when approaching 200-issue cap (show at >= 180)."

#### Agent prompt: Task T (Copy to clipboard)
"Add `y` key to copy SuggestedFix (or Title) to system clipboard. Add atotto/clipboard dependency."

#### Agent prompt: Task U (Dynamic column width)
"Add `t` key to toggle between compact and wide Title column widths for long issue titles."

#### Agent prompt: Task V (Age format toggle)
"Add `d` key to toggle between compact (2dm) and relative (2m ago) age formats."

#### Agent prompt: Task W (Rollup drill-down)
"When rollup issue selected, show 'Affected Issues' list with sample IDs in details pane."

#### Agent prompt: Task X (Light/dark theme toggle)
"Add `T` key to toggle between light and dark themes. Define two theme sets in styles.go."

#### Agent prompt: Task Y (Sound/flash on new P0)
"Add terminal bell/flash when P0 count increases (new critical issue detected). Respect NO_BELL env var."

#### Agent prompt: Task Z (Theme, sound, flash)
"Add theme toggle (`T`) and P0 alert (bell/flash) with env var support. Test with `NO_BELL=1`."

## 6) Definition of done

- Meets `PLAN.md` Acceptance Criteria.
- `go test ./...` passes.
- `go run ./cmd/controltower` works without kubeconfig.
- With kubeconfig and unreachable cluster: `P0` only after 10s.
- UI remains responsive under high issue counts (rollups + caps).

## 7) TUI UX Improvements

This section defines UX enhancements that improve discoverability, navigation efficiency, and visual clarity. Tasks are designed for **parallel agent execution** (independent file ownership).

### 7.1 Quick wins (high-impact, low-effort)

#### Task J — Help overlay
**Goal:** Users can discover all keybindings in-app without external docs.

**Agent:** 1 (can be same agent that implements Task J in Phase 2)

**Owned files:**
- `internal/ui/help.go` (new)
- `internal/ui/keys.go` (add `Help` binding, update prompts)
- `internal/ui/app.go` (add help model + view routing)

**Implementation:**
- Add `Help` key binding (`?`) to `KeyMap`
- Create `help.go` with a `Model` struct:
  - List of keybindings by group (Global, Filters, Navigation, Actions)
  - `render()` function to display as overlay
- Add `helpRequestedMsg` type in `app.go` to trigger help overlay
- Update `keys.go`: add `Help` binding with help text
- Update `app.go`:
  - Add `showHelp bool` field to Model
  - Handle `?` key: toggle help overlay (hide table/details)
  - Update `View()` to conditionally show help instead of main layout

**Acceptance:**
- Press `?` shows keybinding list overlay covering main layout
- Press `?` again or `esc` dismisses help
- `go test ./...` passes

---

#### Task K — Direct priority jump (`0`/`1`/`2`/`3`)
**Goal:** Jump directly to P0/P1/P2/P3 filter instead of cycling through all 5 options.

**Agent:** 1

**Owned files:**
- `internal/ui/keys.go` (add numeric bindings)
- `internal/ui/app.go` (update Update handler)

**Implementation:**
- Add bindings in `keys.go`:
  - `PriorityP0: key.NewBinding(key.WithKeys("0"), key.WithHelp("0", "P0 only"))`
  - `PriorityP1: key.NewBinding(key.WithKeys("1"), key.WithHelp("1", "P1 only"))`
  - `PriorityP2: key.NewBinding(key.WithKeys("2"), key.WithHelp("2", "P2 only"))`
  - `PriorityP3: key.NewBinding(key.WithKeys("3"), key.WithHelp("3", "P3 only"))`
- Update `app.go` Update handler:
  - Match `keyMatch(msg, m.keys.PriorityP0)` → set `m.filterPri = model.PriorityP0`
  - Match `keyMatch(msg, m.keys.PriorityP1)` → set `m.filterPri = model.PriorityP1`
  - Match `keyMatch(msg, m.keys.PriorityP2)` → set `m.filterPri = model.PriorityP2`
  - Match `keyMatch(msg, m.keys.PriorityP3)` → set `m.filterPri = model.PriorityP3`
  - Keep existing `p` cycle behavior for `all` option

**Acceptance:**
- Pressing `0` shows only P0 issues; `1` shows only P1, etc.
- Pressing `p` cycles through: all → P0 → P1 → P2 → P3 → all → …

---

#### Task L — Visual filter indicators
**Goal:** Make active filters visually obvious in header (highlight vs. plain text).

**Agent:** 1

**Owned files:**
- `internal/ui/styles.go` (add filter highlight style)
- `internal/ui/app.go` (update `renderHeader()`)

**Implementation:**
- Add style in `styles.go`:
  - `FilterActive lipgloss.Style` (e.g., bold + distinct foreground)
- Update `renderHeader()` in `app.go`:
  - Apply `FilterActive` style to `pri=` or `cat=` portions when filter is active
  - Keep `all` in plain `HeaderVal` style

**Acceptance:**
- `pri=P1` or `cat=Kubernetes` appears highlighted/colored in header
- `pri=all` or `cat=all` appears in plain text

---

#### Task M — Better empty state
**Goal:** When no issues, show helpful message instead of just “No issues”.

**Agent:** 1

**Owned files:**
- `internal/ui/app.go` (update `applyViewFromSnapshot()`)

**Implementation:**
- In `applyViewFromSnapshot()` (around row building), when `len(filtered) == 0`:
  - Set details content to friendly message: “All systems healthy. No issues detected.”
  - Optionally: add hint like “Press `r` to refresh, `/` to search past logs”

**Acceptance:**
- When snapshot has 0 issues, details pane shows friendly message
- Header still displays correct P0/P1/P2/P3 counts (all 0)

---

#### Task N — Bulk ack all visible
**Goal:** Allow user to acknowledge all currently visible issues at once.

**Agent:** 1

**Owned files:**
- `internal/ui/keys.go` (add bulk ack binding)
- `internal/ui/app.go` (add `AckAllVisible()` method + handler)

**Implementation:**
- Add binding in `keys.go`:
  - `AckAll: key.NewBinding(key.WithKeys("A"), key.WithHelp("A", "ack all visible"))` (shift+a)
- Add method in `app.go`:
  - `func (m *Model) AckAllVisible()`
  - Iterate over `m.rowsIDs`, call `m.ack(id)` for each
  - Optimistically update `issueByID` and table rows
- Update `Update()` handler:
  - Match `keyMatch(msg, m.keys.AckAll)` → call `m.AckAllVisible()`

**Acceptance:**
- Pressing `A` acknowledges all issues currently visible in table
- Header P0/P1/P2/P3 counts remain correct
- `a` still toggles ack/unack for single selected issue

---

### 7.2 Navigation efficiency improvements

#### Task O — Page navigation (`PgUp`/`PgDn` or `Ctrl+u`/`Ctrl+d`)
**Goal:** Faster scrolling through long issue lists (200+ issues with rollups).

**Agent:** 1

**Owned files:**
- `internal/ui/table.go` (no changes needed; bubbles/table supports page keys by default)

**Implementation:**
- Bubbles/table already supports standard page keys:
  - `pgup`/`pgdn`
  - `ctrl+u`/`ctrl+d`
  - `home`/`end`
- Ensure these are not overridden in `app.go` Update handler
- Optionally: update help overlay to document these keys

**Acceptance:**
- PageUp/PageDown jumps 10 rows in table
- Ctrl+u/Ctrl+d jumps half a screen
- Home/End jump to top/bottom

---

#### Task P — Home/End jump (`g`/`G` like vim/less)
**Goal:** Jump to first or last row quickly.

**Agent:** 1

**Owned files:**
- `internal/ui/keys.go` (add bindings)
- `internal/ui/app.go` (add handlers)

**Implementation:**
- Add bindings in `keys.go`:
  - `JumpToTop: key.NewBinding(key.WithKeys("g"), key.WithHelp("g", "jump to first"))`
  - `JumpToBottom: key.NewBinding(key.WithKeys("G"), key.WithHelp("G", "jump to last"))`
- Update `app.go`:
  - Handle `JumpToTop` → set cursor to 0
  - Handle `JumpToBottom` → set cursor to last row

**Acceptance:**
- Pressing `g` moves selection to first visible row
- Pressing `G` moves selection to last visible row

---

#### Task Q — Vi-style nav (`j`/`k` in addition to arrows)
**Goal:** Support vim-style navigation for users who prefer hjkl.

**Agent:** 1

**Owned files:**
- `internal/ui/keys.go` (add bindings)
- `internal/ui/app.go` (add handlers)

**Implementation:**
- Add bindings in `keys.go`:
  - `Down: key.NewBinding(key.WithKeys("j"), key.WithHelp("j", "down"))`
  - `Up: key.NewBinding(key.WithKeys("k"), key.WithHelp("k", "up"))`
- Update `app.go`:
  - Match `Down` and pass to `m.table.Update(msg)` (bubbles/table handles both arrows and j/k)
- Update help overlay to document `j`/`k` as alternatives to arrows

**Acceptance:**
- `j` moves selection down, `k` moves up
- Arrows continue to work (both styles supported)

---

### 7.3 Visual polish & feedback

#### Task R — Collector health icons
**Goal:** Replace text “ok=1 deg=0 err=Z” with visual status icons.

**Agent:** 1

**Owned files:**
- `internal/ui/app.go` (update `renderHeader()`)
- `internal/ui/styles.go` (add icon styles if desired)

**Implementation:**
- Update `renderHeader()` health display:
  - Use icon instead of text:
    - `✓` for OK
    - `⚠` for DEGRADED
    - `✗` for ERROR
  - Format: `collectors: ✓1 ⚠0 ✗0`
- Optional: use `lipgloss.SetGlyphWidth()` if icons appear misaligned

**Acceptance:**
- Header shows icon-based collector health (e.g., `collectors: ✓4`)
- Status still readable for screen readers (icons are supplementary)

---

#### Task S — Issue count warning near cap
**Goal:** Warn users when approaching the 200-issue cap (after rollups).

**Agent:** 1

**Owned files:**
- `internal/ui/app.go` (update `renderHeader()`)

**Implementation:**
- In `renderHeader()`, calculate total issues: `total := p0 + p1 + p2 + p3`
- If `total >= 180` (90% of cap):
  - Append warning text to collector health line: ` [~180/200]`
  - Use warning color from `styles.Error`
- Only show when near cap; don’t clutter at low counts

**Acceptance:**
- When near 200 issues, header shows warning indicator
- Below 180 issues, no warning appears

---

#### Task T — Copy to clipboard (`y` on selected issue)
**Goal:** Quick copy of issue ID, Title, or SuggestedFix.

**Agent:** 1

**Owned files:**
- `internal/ui/keys.go` (add binding)
- `internal/ui/app.go` (add handler + clipboard dep if needed)
- `go.mod` (add clipboard dependency)

**Implementation:**
- Add binding in `keys.go`:
  - `Copy: key.NewBinding(key.WithKeys("y"), key.WithHelp("y", "copy to clipboard"))`
- Add dependency in `go.mod` (pick one):
  - `github.com/atotto/clipboard` (cross-platform, widely used)
  - or use xclip/xsel via `exec.Command` for linux-only (no new dep)
- Update `app.go`:
  - On `y` key, copy selected issue’s `SuggestedFix` to clipboard (most useful field)
  - Show brief confirmation in details pane: “Copied to clipboard”

**Acceptance:**
- Pressing `y` copies SuggestedFix (or Title) to system clipboard
- Brief confirmation shown in details pane

---

### 7.4 Nice-to-have (higher effort)

#### Task U — Dynamic column width
**Goal:** Allow widening Title column on demand for long issue titles.

**Agent:** 1

**Owned files:**
- `internal/ui/keys.go` (add toggle binding)
- `internal/ui/app.go` (add `wideTitle` state + update layout())

**Implementation:**
- Add binding in `keys.go`:
  - `ToggleWideTitle: key.NewBinding(key.WithKeys("t"), key.WithHelp("t", "toggle wide title"))`
- Add `wideTitle bool` field to Model
- Update `layout()` to compute two widths:
  - Normal mode: compact Title width (current behavior)
  - Wide mode: allocate more space to Title column
- On `t` toggle, recompute layout and rebuild rows

**Acceptance:**
- Pressing `t` expands Title column
- Pressing `t` again returns to compact width
- Header shows current state (e.g., `wide=on` or icon)

---

#### Task V — Age format toggle (compact vs. “X ago”)
**Goal:** Switch between “2dm” (compact) and “2m ago” (relative) formats.

**Agent:** 1

**Owned files:**
- `internal/ui/keys.go` (add toggle binding)
- `internal/ui/app.go` (add `ageMode` field + update rendering)

**Implementation:**
- Add binding in `keys.go`:
  - `ToggleAgeFormat: key.NewBinding(key.WithKeys("d"), key.WithHelp("d", "toggle age format"))`
- Add `ageMode AgeMode` field to Model with values: `AgeCompact` (default), `AgeRelative`
- Update `table.go` `formatAge()` or `app.go` wrapper to support both modes
- In `renderHeader()`, keep compact age (0s, Xds, Xdm, Xdh, Xdd)
- In details pane, show full time with relative suffix

**Acceptance:**
- Default: table shows `2dm`, details shows “2m ago”
- Press `d`: table shows `2m ago`, details show same
- Press `d` again: revert to compact

---

#### Task W — Rollup drill-down in details
**Goal:** When a rollup issue is selected, show the individual issues it aggregates.

**Agent:** 1

**Owned files:**
- `internal/ui/model` (add rollup-specific types) — or keep minimal
- `internal/ui/app.go` (update `renderIssueDetails()` / `setDetailsToSelected()`)

**Implementation:**
- Add helper `getRollupSamples(iss model.Issue) []string`:
  - Parse `iss.Evidence["samples"]` if it exists
  - Return list of affected IDs/pod names
- Update `renderIssueDetails()` in `details.go`:
  - Detect rollup (e.g., ID starts with `k8s:rollup:` or category=Kubernetes + “rollup” in title)
  - Append section: `Affected Issues` with list of sample IDs (up to 10)
- Keep full rollup summary (count, namespace, reason)

**Acceptance:**
- Selecting a rollup issue shows “Affected Issues: [k8s:pod:default/x, k8s:pod:default/y, …]” in details
- Non-rollup issues show normal details without this section

---

#### Task X — Light/dark theme toggle
**Goal:** Respect user’s theme preference or allow toggling.

**Agent:** 1

**Owned files:**
- `internal/ui/styles.go` (add theme variants)
- `internal/ui/keys.go` (add toggle binding)
- `internal/ui/app.go` (add theme state)
- `cmd/controltower/main.go` (optional env var support)

**Implementation:**
- Define two theme sets in `styles.go`:
  - `LightTheme` (current hardcoded colors)
  - `DarkTheme` (inverted/better contrast)
- Add `themeMode ThemeMode` field to Model (`ThemeAuto`, `ThemeLight`, `ThemeDark`)
- Add binding in `keys.go`:
  - `ToggleTheme: key.NewBinding(key.WithKeys("T"), key.WithHelp("T", "toggle theme"))`
- Optional: respect `NO_COLOR=1` env var (disable all colors)
- On theme toggle, update `styles := defaultStyles()` to apply selected theme

**Acceptance:**
- Default theme is current (light-like)
- Pressing `T` toggles light/dark
- `NO_COLOR=1` disables colors entirely

---

#### Task Y — Sound/flash on new P0
**Goal:** Alert user when critical issues appear.

**Agent:** 1

**Owned files:**
- `internal/ui/app.go` (track P0 count changes + trigger alert)

**Implementation:**
- Add `lastP0Count int` field to Model
- In `applyViewFromSnapshot()`:
  - Compare `p0` with `m.lastP0Count`
  - If `p0 > m.lastP0Count`: new critical issues appeared
  - Update `m.lastP0Count = p0`
- Add alert function:
  - Use bubbletea’s `bell` (terminal bell) or flash:
    - Send `tea.BellMsg` on P0 increase
  - Optional: check for `NO_BELL=1` env var to disable

**Acceptance:**
- When P0 count increases, terminal bell/flash occurs (if not disabled)
- P0 decrease or no change does not trigger alert
- `NO_BELL=1` env var suppresses all alerts

---

### 8-agent assignment for UX tasks

To keep parallelism and avoid conflicts, assign as follows (can be done in Phase 3):

| Agent | Tasks | Owned Files | Notes |
|-------|-------|--------------|-------|
| **Agent 9** | Task J (Help overlay) | `internal/ui/help.go`, `keys.go`, `app.go` | High discoverability impact |
| **Agent 10** | Tasks K, L, M (Priority jump, visual filters, empty state) | `keys.go`, `styles.go`, `app.go` | Quick navigation wins |
| **Agent 11** | Tasks N, O, P (Bulk ack, page nav, home/end) | `keys.go`, `app.go` | Nav efficiency |
| **Agent 12** | Tasks Q, R (Vi nav, collector health icons) | `keys.go`, `app.go`, `styles.go` | Nav + visual polish |
| **Agent 13** | Tasks S, T, V (Count warning, copy clipboard, dynamic width) | `keys.go`, `app.go`, `go.mod`, `table.go` | Polish + utility |
| **Agent 14** | Tasks W, X (Rollup drill-down, age toggle) | `app.go`, `details.go`, `keys.go` | Details enhancements |
| **Agent 15** | Tasks Y, Z (Theme, sound/flash) | `styles.go`, `app.go`, `keys.go` | Theme + alerts |

**Execution order (minimal dependencies):**
1. Agents 9–12 run in parallel (all are independent file changes)
2. Agents 13–14 run after 9–12 (may reference new keys/styles)
3. Agent 15 runs after 13–14 (may reference theme from styles)


---

### 8-agent assignment (UX improvements, parallel)

| Agent | Tasks | Owned Files | Notes |
|-------|-------|--------------|-------|
| **Agent 9** | Task J (Help overlay) | `internal/ui/help.go`, `keys.go`, `app.go` | High discoverability impact |
| **Agent 10** | Tasks K, L, M (Priority jump, visual filters, empty state) | `keys.go`, `styles.go`, `app.go` | Quick navigation wins |
| **Agent 11** | Tasks N, O, P (Bulk ack, page nav, home/end) | `keys.go`, `app.go` | Nav efficiency |
| **Agent 12** | Tasks Q, R (Vi nav, collector health icons) | `keys.go`, `app.go`, `styles.go` | Nav + visual polish |
| **Agent 13** | Tasks S, T, V (Count warning, copy clipboard, dynamic width) | `keys.go`, `app.go`, `go.mod`, `table.go` | Polish + utility |
| **Agent 14** | Tasks W, X (Rollup drill-down, age toggle) | `app.go`, `details.go`, `keys.go` | Details enhancements |
| **Agent 15** | Tasks Y, Z (Theme, sound/flash) | `styles.go`, `app.go`, `keys.go` | Theme + alerts |

**Execution order (minimal dependencies):**
1. Agents 9–12 run in parallel (all are independent file changes)
2. Agents 13–14 run after 9–12 (may reference new keys/styles)
3. Agent 15 runs after 13–14 (may reference theme from styles)

**Coordinated changes:**
- `keys.go` is shared across Agents 9–15; each agent appends new bindings without removing others.
- `app.go` is shared; each agent adds new handlers in disjoint methods to avoid merge conflicts.
- `styles.go` is shared; agents add new styles without modifying existing.
- `details.go` is shared; Agents 13–14 add optional sections.
- `help.go` is new (Task J) and owned entirely by Agent 9.

#### Agent prompt: Task J (Help overlay)
"Implement in-app help overlay showing all keybindings. Add `?` key in keys.go, create help.go with Model + render() function. Toggle overlay with `?` key and dismiss with `?` or `esc`."

#### Agent prompt: Task K (Direct priority jump)
"Add numeric bindings `0`/`1`/`2`/`3` in keys.go to jump directly to P0/P1/P2/P3. Keep `p` cycle for `all` option. Update app.go Update handler."

#### Agent prompt: Task L (Visual filter indicators)
"Add FilterActive style in styles.go (highlight color). Update renderHeader() to apply when pri= or cat= filters are active."

#### Agent prompt: Task M (Better empty state)
"Show friendly message 'All systems healthy' in applyViewFromSnapshot() when len(filtered) == 0."

#### Agent prompt: Task N (Bulk ack all visible)
"Add AckAll binding (shift+a) in keys.go. Implement AckAllVisible() method in app.go that iterates rowsIDs and calls ack(). Update handler."

#### Agent prompt: Task O (Page navigation)
"Document that bubbles/table supports page keys (pgup/pgdn, ctrl+u/ctrl+d). Ensure they are not overridden in app.go Update handler. Add to help overlay."

#### Agent prompt: Task P (Home/End jump)
"Add `g`/`G` bindings in keys.go. Add handlers in app.go: `g` sets cursor to 0, `G` sets cursor to last row. Add to help overlay."

#### Agent prompt: Task Q (Vi-style nav)
"Add `j`/`k` bindings in keys.go. Update app.go to pass to table.Update(); bubbles/table handles both arrows and j/k. Update help overlay."

#### Agent prompt: Task R (Collector health icons)
"Update renderHeader() to use icons (✓ for OK, ⚠ for DEGRADED, ✗ for ERROR) instead of text. Format: 'collectors: ✓1 ⚠0 ✗0'."

#### Agent prompt: Task S (Issue count warning near cap)
"In renderHeader(), calculate total issues. If total >= 180, append warning '[~180/200]' with error color. Show only when near cap."

#### Agent prompt: Task T (Copy to clipboard)
"Add `y` binding in keys.go. Add atotto/clipboard to go.mod. On `y` key, copy selected issue's SuggestedFix to clipboard. Show brief confirmation in details."

#### Agent prompt: Task U (Dynamic column width)
"Add ToggleWideTitle binding (`t`) in keys.go. Add wideTitle bool to Model. Update layout() to compute wide vs compact widths. Toggle with `t` key. Update help overlay."

#### Agent prompt: Task V (Age format toggle)
"Add ToggleAgeFormat binding (`d`) in keys.go. Add AgeMode field (Compact/Relative) to Model. Update formatAge() or wrapper in app.go to support both modes. Toggle with `d` key."

#### Agent prompt: Task W (Rollup drill-down)
"Add getRollupSamples() helper to parse Evidence['samples']. Update renderIssueDetails() in details.go to detect rollup and append 'Affected Issues' section with sample IDs."

#### Agent prompt: Task X (Light/dark theme toggle)
"Define LightTheme and DarkTheme in styles.go. Add themeMode field to Model with Auto/Light/Dark. Add ToggleTheme binding (`T`) in keys.go. Respect NO_COLOR env var."

#### Agent prompt: Task Y (Sound/flash on new P0)
"Add lastP0Count to Model. In applyViewFromSnapshot(), compare p0 with lastP0Count. If p0 increases, send bubbletea.BellMsg. Check NO_BELL env var."

#### Agent prompt: Task Z (Theme, sound, flash)
"Combine Task X (theme toggle) and Task Y (P0 alert). Test theme toggle works and P0 bell/flash. Add env var checks for NO_BELL."