docs: rewrite Task 8 for the Lua Hyprland config

The live config is hyprland.lua requiring sections/, with rules
declared through an hl helper API, so the planned .conf fragment with
source = could not have worked. Task 8 now writes a Lua section using
hl.window_rule and hl.bind, matching the existing rules.

Three facts checked against the running config:

- keybindings.lua already binds SUPER+D to the unnamed special
  workspace, so the dashboard takes SUPER+S.
- autostart.lua already runs a bare conky. The dashboard replaces it,
  so that line changes rather than a new exec being added, which would
  run two instances.
- The unnamed special workspace hosts the btop scratchpad, so the
  dashboard gets its own special:dash.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

1 files changed, 145 insertions, 61 deletions

diff --git a/docs/superpowers/plans/2026-09-16-conky-lua-dashboard.md b/docs/superpowers/plans/2026-09-16-conky-lua-dashboard.md
index 3445d6a..4289bb1 100644
--- a/docs/superpowers/plans/2026-09-16-conky-lua-dashboard.md
+++ b/docs/superpowers/plans/2026-09-16-conky-lua-dashboard.md
@@ -41,7 +41,8 @@ These were verified experimentally on this machine. Each one invalidates an appr
 | `widgets/clock.lua` | The only v1 widget. `draw(cr, rect, colors)`. |
 | `test/fixtures/` | Committed sample `/proc/stat`, `/proc/meminfo`, `temp1_input`. |
 | `test/test_data.lua` | `assert`-based parser check, run with `lua`. |
-| `hypr/dashboard.conf` | Hyprland windowrules and keybind, sourced by the user's config. |
+| `hypr/dashboard.lua` | Hyprland window rules and the `SUPER+S` bind, as a Lua section for the user's `hyprland.lua`. |
+| `hypr/README.md` | How to wire that section in, and the one-line `autostart.lua` change it needs. |
 | `README.md` | What it is, install, layout editing, the Wayland Cairo gotcha. |
 
 **The UDT repo (`~/Programming/GIT/unified-desktop-theme`), modified in Task 9:**
@@ -1120,44 +1121,135 @@ stubbed via package.preload since they only exist inside Conky."
 
 ### Task 8: Hyprland placement and the toggle
 
+The user's Hyprland config is **Lua**, not `.conf`: `~/.config/hypr/hyprland.lua`
+requires modules from `~/.config/hypr/sections/`, and rules are declared through a
+helper API (`hl.window_rule`, `hl.bind`, `hl.exec_cmd`). A `.conf` fragment with
+`source =` does not fit that design, so this task writes a Lua section instead and
+the user copies it in.
+
+Three facts about the live config, verified before writing this task:
+
+- `sections/keybindings.lua:123` already binds `SUPER+D` to
+  `hl.dsp.workspace.toggle_special("special")`. The dashboard therefore takes
+  **`SUPER+S`**, which is unbound.
+- `sections/autostart.lua:23` already runs `hl.exec_cmd("conky")`. That line
+  starts the OLD desktop-layer conky. Adding another `exec_cmd` for the dashboard
+  would run two instances, so the existing line is what changes, not a new one.
+- The unnamed `special` workspace already hosts `kitty-scratchpad btop`
+  (`autostart.lua`), which is why the dashboard gets its own named
+  `special:dash` rather than sharing it.
+
 **Files:**
-- Create: `hypr/dashboard.conf`
+- Create: `hypr/dashboard.lua`
+- Create: `hypr/README.md`
 
-- [ ] **Step 1: Write the Hyprland config fragment**
+- [ ] **Step 1: Write the Lua section**
 
-Create `hypr/dashboard.conf`:
+Create `hypr/dashboard.lua`. Note `hl.window_rule` takes a `name` and a `match`
+table, following the existing rules in `sections/look_and_feel.lua:112-152`.
 
-```bash
-# Conky Lua dashboard: window placement and toggle.
-#
-# Source this from hyprland.conf:
-#     source = ~/Programming/GIT/conky-theme-udt/hypr/dashboard.conf
-#
-# The dashboard is a normal toplevel, not a desktop-layer surface, which is what
-# lets these rules put it on a workspace at all.
-
-# Pin it to its own special workspace. `silent` keeps launching it from stealing
-# focus, since it starts with the session rather than on request.
-windowrulev2 = workspace special:dash silent, class:^(conky-dash)$
-windowrulev2 = float, class:^(conky-dash)$
-windowrulev2 = fullscreen, class:^(conky-dash)$
-windowrulev2 = noborder, class:^(conky-dash)$
-windowrulev2 = noshadow, class:^(conky-dash)$
-# It is a dashboard, not a window: never let it take focus or be tabbed to.
-windowrulev2 = nofocus, class:^(conky-dash)$
-
-# Toggle. Super+D shows and hides the special workspace.
-bind = SUPER, D, togglespecialworkspace, dash
-
-# Always running, started with the session: hiding is a workspace switch, so
-# showing is instant and any graph history survives. Draws are not skipped while
-# hidden; that optimisation was rejected as unmeasured.
-exec-once = conky -c ~/.config/conky/conky.conf
+```lua
+-- Conky Lua dashboard: window placement and toggle.
+--
+-- Copy or symlink into ~/.config/hypr/sections/ and add to hyprland.lua:
+--     require("sections.dashboard")
+--
+-- The dashboard is a normal toplevel, not a desktop-layer surface, which is
+-- what lets a window rule put it on a workspace at all.
+
+-- Its own named special workspace: the unnamed `special` already hosts the
+-- btop scratchpad.
+local WS = "special:dash"
+
+hl.window_rule({
+    name      = "dash-workspace",
+    match     = { class = "conky-dash" },
+    workspace = WS,
+})
+hl.window_rule({
+    name  = "dash-float",
+    match = { class = "conky-dash" },
+    float = true,
+})
+hl.window_rule({
+    name       = "dash-fullscreen",
+    match      = { class = "conky-dash" },
+    fullscreen = true,
+})
+hl.window_rule({
+    name        = "dash-no-border",
+    match       = { class = "conky-dash" },
+    border_size = 0,
+})
+hl.window_rule({
+    name     = "dash-no-rounding",
+    match    = { class = "conky-dash" },
+    rounding = 0,
+})
+-- It is a dashboard, not a window: never let it take focus or be tabbed to.
+-- This matters because it starts with the session, so without it the dashboard
+-- would steal focus at login.
+hl.window_rule({
+    name     = "dash-no-focus",
+    match    = { class = "conky-dash" },
+    no_focus = true,
+})
+
+-- SUPER+S, not SUPER+D: keybindings.lua already binds D to the unnamed special
+-- workspace.
+hl.bind(hl.mainMod .. " + s", hl.dsp.workspace.toggle_special("dash"))
+```
+
+Note: `hl.mainMod` may not be exported; `keybindings.lua` uses a local
+`mainMod`. If `hl.mainMod` is nil at load, replace that last line with the
+literal modifier used in `keybindings.lua` (read its `mainMod` assignment with
+`grep -n 'mainMod' ~/.config/hypr/sections/keybindings.lua | head -3`).
+
+- [ ] **Step 2: Verify it parses as Lua**
+
+The `hl` API only exists inside Hyprland, so this checks syntax, not semantics.
+
+Run: `cd ~/Programming/GIT/conky-theme-udt && lua -e "assert(loadfile('hypr/dashboard.lua')); print('SYNTAX OK')"`
+
+Expected: `SYNTAX OK`
+
+- [ ] **Step 3: Write the install note**
+
+Create `hypr/README.md`:
+
+```markdown
+# Hyprland integration
+
+`dashboard.lua` is a section for the Lua-based Hyprland config in
+`~/.config/hypr/`. It is not sourced automatically; wire it in once:
+
+    ln -s ~/Programming/GIT/conky-theme-udt/hypr/dashboard.lua \
+          ~/.config/hypr/sections/dashboard.lua
+
+and add to `~/.config/hypr/hyprland.lua`:
+
+    require("sections.dashboard")
+
+## One change to make by hand
+
+`sections/autostart.lua` runs `hl.exec_cmd("conky")`, which starts the old
+desktop-layer conky. The dashboard replaces it, so change that line to:
+
+    hl.exec_cmd("conky -c ~/.config/conky/conky.conf")
+
+Leaving both would run two conky instances.
+
+## Bindings
+
+`SUPER+S` toggles the dashboard. `SUPER+D` is already taken by the unnamed
+special workspace, and that workspace also hosts the btop scratchpad, which is
+why the dashboard uses its own `special:dash`.
 ```
 
-- [ ] **Step 2: Verify the rules match the real window**
+- [ ] **Step 4: Verify the window class matches the rules**
 
-Do not assume the class matches; check it against a running instance.
+Do not assume the class matches; check it against a running instance. The rules
+are inert if the class in the config and the rules disagree.
 
 ```bash
 cd ~/Programming/GIT/conky-theme-udt
@@ -1167,40 +1259,33 @@ hyprctl clients -j | jq -r '.[]|select(.class=="conky-dash")|"class=\(.class) ws
 pkill -f 'conky -c ./conky.conf'
 ```
 
-Expected: one line with `class=conky-dash`. If it prints nothing, the class in
-the config and the rules disagree and the rules will never fire.
-
-- [ ] **Step 3: Verify the waybar launcher command**
-
-The waybar module lives in the UDT repo, so this task only confirms the command
-the user will bind. Run it and check the workspace toggles:
-
-```bash
-hyprctl dispatch togglespecialworkspace dash
-sleep 1
-hyprctl activeworkspace -j | jq -r .name
-hyprctl dispatch togglespecialworkspace dash
-```
-
-Expected: the middle command prints `special:dash`, then the state returns.
+Expected: one line with `class=conky-dash`. Nothing printed means the class is
+wrong and no rule will ever fire.
 
-- [ ] **Step 4: Commit**
+- [ ] **Step 5: Commit**
 
 ```bash
 cd ~/Programming/GIT/conky-theme-udt
-git add hypr/dashboard.conf
+git add hypr/
 git commit -m "feat: add Hyprland placement rules and toggle
 
-Pins conky-dash to a special workspace, fullscreen, no border, no
-focus, and binds Super+D to toggle it. Sourced from hyprland.conf
-rather than edited into it.
+A Lua section, not a .conf fragment: the live Hyprland config is
+hyprland.lua requiring sections/, with rules declared through the hl
+helper API.
+
+Pins conky-dash to its own special:dash workspace, fullscreen, no
+border, no focus, and binds SUPER+S. Not SUPER+D, which keybindings.lua
+already binds to the unnamed special workspace, and that workspace
+already hosts the btop scratchpad.
+
+no_focus matters because the dashboard starts with the session:
+without it, it steals focus at login and can be tabbed to like an app.
 
-nofocus and silent matter because the dashboard starts with the session:
-without them it steals focus at login and can be tabbed to like an app."
+autostart.lua already launches a bare conky, so the README says to
+change that line rather than add one, which would run two instances."
 ```
 
 ---
-
 ### Task 9: Switch UDT over
 
 Last, so no intermediate state touches the working desktop. This modifies the other repo.
@@ -1389,7 +1474,7 @@ Create `README.md`:
 # conky-theme-udt
 
 A fullscreen Conky dashboard for Hyprland, drawn with Cairo from Lua, living on
-a special workspace that `SUPER+D` toggles.
+a special workspace that `SUPER+S` toggles.
 
 Colours come from [unified-desktop-theme](../unified-desktop-theme): this repo
 holds `conky.conf.in`, and UDT's `bin/udt-palette` renders it into `conky.conf`
@@ -1401,10 +1486,9 @@ dashboard.
     cd ../unified-desktop-theme && ./install.sh
 
 That renders `conky.conf` and links it, `dashboard.lua`, `lib/` and `widgets/`
-into `~/.config/conky/`. Then source the Hyprland rules once, from
-`hyprland.conf`:
-
-    source = ~/Programming/GIT/conky-theme-udt/hypr/dashboard.conf
+into `~/.config/conky/`. Then wire the Hyprland section in once, and change the
+bare `conky` in `sections/autostart.lua` to load this config. See
+[`hypr/README.md`](hypr/README.md) for both steps.
 
 ## Changing the layout