diff --git a/WAYBAR.md b/WAYBAR.md
new file mode 100644
index 0000000..df945ac
--- /dev/null
+++ b/WAYBAR.md
@@ -0,0 +1,58 @@
+# Waybar — Troubleshooting & Fix Log
+
+## Final Working State
+
+- Layer: top (level 2, above windows)
+- Position: top, margin-top: 10px
+- Width: fits exactly 1280px (screen logical width at 1.5x scale)
+- Config: `~/.config/waybar/config.jsonc`
+- CSS: `~/.config/waybar/style.css`
+
+## Issues Found and Fixed (2026-06-08)
+
+### 1. Bar invisible — wrong layer (bottom instead of top)
+
+**Root cause:** Two problems stacked:
+- `"format": {}` (JSON object instead of string) in `custom/cava` module caused config parse to silently fall back to defaults, placing bar at layer 1 (bottom).
+- `"mode": "dock"` overrides the `"layer"` setting in Waybar 0.15.0 + Hyprland 0.55.2, keeping the bar at the bottom layer regardless.
+
+**Fix:**
+```jsonc
+// Wrong:
+"format": {},
+"mode": "dock",
+
+// Fixed:
+"format": "{}",
+// mode: "dock" removed entirely
+```
+
+### 2. Bar overflowing screen width (1460px on a 1280px logical screen)
+
+**Root cause:** Variable-length module content (network bandwidth string changes length) caused the GTK layout to expand the bar beyond the 1280px logical screen width. Setting `"width": 1280` in Waybar config does NOT cap the width — it only sets a minimum.
+
+**Fix:** Reduced CSS padding on all modules and workspace buttons to make total content fit:
+
+| Selector | Old padding | New padding |
+|----------|-------------|-------------|
+| modules (network, memory, etc.) | `0px 10px` | `0px 7px` |
+| workspace buttons | `2px 8px` | `2px 5px` |
+| media group modules | `0px 10px` | `0px 7px` |
+
+Also:
+- `#workspaces` margin: `10px 10px` → `10px 5px`
+- `#media` margin: `10px 10px` → `10px 5px`
+- mpris `max-length`: 20 → 14
+- network `min-length`/`max-length`: 22 (to prevent bandwidth string from varying bar width)
+- cava `max-length`: 12
+
+## Layout
+
+```
+[hardware group]              [workspaces] [⏻] [workspaces]          [media group] [clock]
+ ↑ up/down bw, mem, bat, cpu, temp         ↑ left workspaces (1,3,5,7)  ↑ spotify, cava, mpris, vol
+```
+
+## Waybar Version Compatibility Note
+
+Waybar 0.15.0 + Hyprland 0.55.2: `"mode": "dock"` prevents `"layer": "top"` from working. Do not use `"mode": "dock"` if you need the bar above windows.