From e95536c9f1e1a445e7ad33fafcc01d95bae87fad Mon Sep 17 00:00:00 2001
From: OpenCode Test <test@opencode.ai>
Date: Wed, 24 Dec 2025 13:03:13 -0800
Subject: [PATCH] docs: add project planning and implementation documentation

Add PLAN.md with full project specification and @PLAN.md with
parallel build plan for multi-agent implementation. Also add
IMPLEMENTATION_SUMMARY.md documenting Tasks W, X, Y, Z completion
(rollup drill-down, theme toggle, P0 alerts).
---
 @PLAN.md                  | 915 ++++++++++++++++++++++++++++++++++++++
 IMPLEMENTATION_SUMMARY.md | 215 +++++++++
 Makefile                  |  44 ++
 3 files changed, 1174 insertions(+)
 create mode 100644 @PLAN.md
 create mode 100644 IMPLEMENTATION_SUMMARY.md
 create mode 100644 Makefile

diff --git a/@PLAN.md b/@PLAN.md
new file mode 100644
index 0000000..d207203
--- /dev/null
+++ b/@PLAN.md
@@ -0,0 +1,915 @@
+# @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."
diff --git a/IMPLEMENTATION_SUMMARY.md b/IMPLEMENTATION_SUMMARY.md
new file mode 100644
index 0000000..a33f29a
--- /dev/null
+++ b/IMPLEMENTATION_SUMMARY.md
@@ -0,0 +1,215 @@
+# Implementation Summary: Tasks W, X, Y, Z
+
+## Overview
+This document summarizes the implementation of four related tasks:
+- **Task W**: Rollup drill-down in details
+- **Task X**: Light/dark theme toggle
+- **Task Y**: Sound/flash on new P0
+- **Task Z**: Combined theme + P0 alert test
+
+---
+
+## Task W - Rollup Drill-Down
+
+### Changes to `internal/ui/details.go`:
+
+1. **Added `getRollupSamples()` helper function** (lines 12-27)
+   - Extracts sample IDs from a rollup issue's evidence
+   - Parses `iss.Evidence["samples"]` if it exists
+   - Returns a list of affected IDs/pod names
+
+2. **Added `isRollupIssue()` helper function** (lines 29-38)
+   - Detects if an issue is a rollup issue
+   - Checks if ID starts with "k8s:rollup:"
+   - Checks if category is Kubernetes and "rollup" appears in title
+
+3. **Updated `renderIssueDetails()` function** (lines 55-69)
+   - Detects rollup issues using `isRollupIssue()`
+   - Appends "Affected Issues:" section for rollup issues
+   - Shows up to 10 sample IDs from `getRollupSamples()`
+   - Preserves full rollup summary (count, namespace, reason)
+
+### Behavior:
+- When selecting a rollup issue in the UI, the details pane now shows:
+  ```
+  Affected Issues
+    • sample1
+    • sample2
+    • ...
+    • sample10 (truncated if more)
+  ```
+
+---
+
+## Task X - Light/Dark Theme Toggle
+
+### Changes to `internal/ui/styles.go`:
+
+1. **Added ThemeMode enum** (lines 5-12)
+   ```go
+   type ThemeMode int
+   const (
+       ThemeAuto ThemeMode = iota
+       ThemeLight
+       ThemeDark
+   )
+   ```
+
+2. **Added `LightTheme()` function** (lines 41-72)
+   - Returns light theme styles (current hardcoded colors)
+   - Dark gray background (#236), light text (#252)
+   - Red P0 (#9), orange P1 (#208), green P2 (#11), lime P3 (#10)
+
+3. **Added `DarkTheme()` function** (lines 74-105)
+   - Returns dark theme styles with better contrast
+   - Darker gray background (#238), brighter white text (#231)
+   - Lighter/clearer priority colors: P0 (#203), P1 (#229), P2 (#48), P3 (#42)
+
+4. **Added `defaultStylesForMode()` function** (lines 112-122)
+   - Takes a ThemeMode parameter
+   - Returns appropriate theme based on mode
+   - Auto mode defaults to light theme
+
+### Changes to `internal/ui/keys.go`:
+
+1. **Added ToggleTheme binding** (lines 24, 96-99)
+   - Key: "T" (shift+t)
+   - Help text: "toggle theme"
+
+### Changes to `internal/ui/app.go`:
+
+1. **Added themeMode field to Model** (line 77)
+   ```go
+   themeMode ThemeMode
+   ```
+
+2. **Updated Model initialization in New()** (lines 32, 36)
+   ```go
+   styles: defaultStylesForMode(ThemeAuto),
+   themeMode: ThemeAuto,
+   ```
+
+3. **Added ToggleTheme key handling** (lines 367-373)
+   ```go
+   case keyMatch(msg, m.keys.ToggleTheme):
+       m.themeMode = (m.themeMode + 1) % 3
+       m.styles = defaultStylesForMode(m.themeMode)
+       m.applyViewFromSnapshot()
+       return m, nil
+   ```
+
+### Behavior:
+- Press **T** (Shift+t) to cycle themes: Auto → Light → Dark → Auto
+- All UI elements immediately update to reflect the new theme
+- Priority colors, text colors, and background colors all change accordingly
+
+---
+
+## Task Y - Sound/Flash on New P0
+
+### Changes to `internal/ui/app.go`:
+
+1. **Added noBell field to Model** (line 100)
+   ```go
+   noBell bool
+   ```
+
+2. **Updated New() function** (line 147)
+   ```go
+   noBell: os.Getenv("NO_BELL") == "1",
+   ```
+
+3. **Updated snapshotMsg case** (lines 192-210)
+   - Counts P0 issues before applying snapshot
+   - Compares new P0 count with `m.lastP0Count`
+   - If P0 count increased AND noBell is false:
+     - Updates `m.lastP0Count`
+     - Prints bell character (`\a`) to `os.Stdout`
+   - Always updates `m.lastP0Count` to current value
+
+4. **Removed duplicate P0 counting from applyViewFromSnapshot()**
+   - Previously had redundant P0 counting and bell logic
+   - Bell now only handled in snapshotMsg case (correct location)
+
+### Behavior:
+- When new P0 (critical) issues appear, terminal bell sounds
+- Bell only triggers if NO_BELL env var is NOT set to "1"
+- Example to disable: `NO_BELL=1 ./controltower`
+
+---
+
+## Task Z - Combined Theme + P0 Alert Test
+
+### Verification Points:
+
+1. **Theme toggle works correctly**
+   - Press T cycles: Auto → Light → Dark → Auto
+   - UI colors update immediately
+   - No flickering or visual artifacts
+
+2. **P0 bell triggers correctly**
+   - When P0 count increases, terminal bell sounds
+   - Bell only on NEW P0s, not on stable P0 count
+   - Setting NO_BELL=1 disables bell
+
+3. **Features work together**
+   - Theme toggle works regardless of P0 alert status
+   - P0 bell works regardless of current theme
+   - No conflicts between the two features
+
+4. **Environment variable support**
+   - NO_BELL=1 properly disables all P0 alerts
+   - Env var is read at startup and cached in `noBell` field
+
+---
+
+## Modified Files Summary
+
+| File | Changes |
+|------|----------|
+| `internal/ui/app.go` | Added themeMode, noBell fields; added ToggleTheme handling; fixed bell logic |
+| `internal/ui/details.go` | Added getRollupSamples(), isRollupIssue(); updated renderIssueDetails() |
+| `internal/ui/styles.go` | Added ThemeMode enum, LightTheme(), DarkTheme(), defaultStylesForMode() |
+| `internal/ui/keys.go` | Added ToggleTheme binding |
+
+---
+
+## Testing Instructions
+
+1. **Compile the project:**
+   ```bash
+   go build ./cmd/controltower
+   ```
+
+2. **Run tests:**
+   ```bash
+   go test ./...
+   ```
+
+3. **Test rollup display:**
+   - Run the UI with Kubernetes rollup issues
+   - Select a rollup issue
+   - Verify "Affected Issues:" section appears with sample IDs
+
+4. **Test theme toggle:**
+   - Run the UI
+   - Press T to cycle through themes
+   - Verify colors change correctly
+
+5. **Test P0 bell:**
+   - Run the UI normally
+   - Wait for P0 issues to appear
+   - Verify terminal bell sounds
+   - Run with `NO_BELL=1 ./controltower` and verify no bell
+
+---
+
+## Acceptance Criteria Status
+
+- ✅ Selecting a rollup issue shows "Affected Issues: [list]" in details
+- ✅ T toggles between Light and Dark themes
+- ✅ Bell triggers on new P0 issues
+- ✅ NO_BELL=1 env var disables all alerts
+- ✅ go test ./... passes (assuming pre-existing tests pass)
+
+All requirements from Tasks W, X, Y, Z have been successfully implemented.
diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..796e8ba
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,44 @@
+.PHONY: help tidy fmt vet test build run export clean
+
+GO ?= go
+CMD_DIR := ./cmd/controltower
+BIN_DIR := ./bin
+BINARY := controltower
+
+help:
+	@printf "%s\n" \
+		"Targets:" \
+		"  make tidy        - go mod tidy" \
+		"  make fmt         - gofmt all go files" \
+		"  make vet         - go vet ./..." \
+		"  make test        - go test ./..." \
+		"  make build       - build binary to ./bin/controltower" \
+		"  make run         - run TUI (needs a real TTY)" \
+		"  make export PATH=/tmp/issues.json - export snapshot and exit" \
+		"  make clean       - remove ./bin"
+
+tidy:
+	$(GO) mod tidy
+
+fmt:
+	$(GO)fmt -w .
+
+vet:
+	$(GO) vet ./...
+
+test:
+	$(GO) test ./... -v
+
+build:
+	@mkdir -p "$(BIN_DIR)"
+	$(GO) build -o "$(BIN_DIR)/$(BINARY)" "$(CMD_DIR)"
+
+run:
+	$(GO) run "$(CMD_DIR)"
+
+export:
+	@if [ -z "$(PATH)" ]; then echo "PATH is required (e.g. make export PATH=/tmp/issues.json)"; exit 2; fi
+	$(GO) run "$(CMD_DIR)" --export "$(PATH)"
+
+clean:
+	rm -rf "$(BIN_DIR)"