changes

.memory/gates/doc-coverage-waybar-pomodoro-fix.md

@@ -0,0 +1,36 @@
+---
+title: doc-coverage-waybar-pomodoro-fix
+type: note
+permalink: dotfiles/gates/doc-coverage-waybar-pomodoro-fix
+tags:
+- waybar
+- pomodoro
+- documentation
+- doc-coverage
+---
+
+# Documentation Coverage: Waybar Pomodoro Visibility Fix
+
+## Summary
+
+Documentation coverage reviewed for the waybar pomodoro visibility fix (explicit binary path instead of PATH reliance).
+
+## Observations
+
+- [decision] No repo documentation changes needed for the pomodoro visibility fix — this is a personal dotfiles repo with no README, no docs/ directory, and AGENTS.md contains only agent workflow config, not dotfiles-specific documentation
+- [decision] Changed files (`.config/waybar/config`, `.config/waybar/scripts/pomodoro-preset.sh`) are self-documenting through clear variable naming (`POMODORO_BIN`) and standard Waybar config format
+- [decision] The plan note `plans/waybar-pomodoro-not-showing` already records full execution context, outcomes, and verification results — no additional knowledge capture needed
+
+## Surfaces Checked
+
+| Surface | Exists | Update Needed | Reason |
+|---|---|---|---|
+| README | No | N/A | Personal dotfiles repo, no README |
+| docs/ | No | N/A | No docs directory exists |
+| AGENTS.md | Yes | No | Contains only agent workflow config, not dotfiles project docs |
+| Inline docs | Yes (self-documenting) | No | Variable naming and script structure are clear |
+| Plan note | Yes | No | Already has execution notes and outcomes |
+
+## Relations
+
+- documents [[waybar-pomodoro-not-showing]]

.memory/gates/gate-waybar-pomodoro-not-showing-review.md

@@ -0,0 +1,44 @@
+---
+title: gate-waybar-pomodoro-not-showing-review
+type: note
+permalink: dotfiles/gates/gate-waybar-pomodoro-not-showing-review
+tags:
+- gate
+- review
+- waybar
+- pomodoro
+- approved
+---
+
+# Gate: Waybar Pomodoro Not Showing — Correctness Review
+
+## Verdict
+- [decision] APPROVED — REVIEW_SCORE: 0 #gate #approved
+
+## Scope
+- Reviewed `.config/waybar/config`
+- Reviewed `.config/waybar/scripts/pomodoro-preset.sh`
+- Cross-referenced plan `[[waybar-pomodoro-not-showing]]` (`memory://plans/waybar-pomodoro-not-showing`)
+- Confirmed prior critic guidance is reflected in current code
+
+## Evidence checked
+- [evidence] `.config/waybar/config:136-139` now uses `$HOME/.local/bin/waybar-module-pomodoro` for `exec`, `on-click`, and `on-click-middle`, while preserving the existing preset script hook for right-click
+- [evidence] `.config/waybar/scripts/pomodoro-preset.sh:6-10` introduces `POMODORO_BIN="$HOME/.local/bin/waybar-module-pomodoro"` and replaces PATH-dependent lookup with an executable-file guard
+- [evidence] `.config/waybar/scripts/pomodoro-preset.sh:30-32` routes `set-work`, `set-short`, and `set-long` through the same explicit binary path
+- [evidence] Repository search found pomodoro binary references only in the expected changed lines, with no stale bare `waybar-module-pomodoro` invocations remaining in `.config/waybar/config` or `.config/waybar/scripts/pomodoro-preset.sh`
+- [evidence] Fresh verification supplied by lead/coder: `bash -n` on the script passed; `/home/alex/.local/bin/waybar-module-pomodoro --help` succeeded and confirmed required subcommands/options exist
+
+## Findings
+- [observation] No correctness defects found in the reviewed change set
+- [observation] The implementation matches the approved minimal fix for launch-time PATH mismatch and updates all user-triggered pomodoro entry points called out in the plan pre-mortem
+
+## Related regression checks
+- [check] `.config/waybar/config:136-139` — no stale bare binary references remain in `exec`, left-click toggle, right-click preset hook, or middle-click reset
+- [check] `.config/waybar/scripts/pomodoro-preset.sh:6-10,30-32` — helper now uses one consistent binary path for validation and all preset subcommands; no path drift found in changed lines
+
+## Freshness notes
+- [finding] Prior critic guidance was confirmed, not contradicted: the old PATH-based guard was removed and replaced with an explicit executable-path check, matching the approved fix direction
+
+## Relations
+- gates [[waybar-pomodoro-not-showing]]
+- related_to [[waybar-pomodoro-not-showing]]

.memory/gates/gate-waybar-pomodoro-not-showing.md

@@ -0,0 +1,39 @@
+---
+title: gate-waybar-pomodoro-not-showing
+type: note
+permalink: dotfiles/gates/gate-waybar-pomodoro-not-showing
+tags:
+- gate
+- critic
+- waybar
+- pomodoro
+- approved
+---
+
+# Critic Gate: Waybar Pomodoro Not Showing
+
+## Verdict
+- [decision] APPROVED — plan is clear, correctly scoped, and adequately de-risked #gate #approved
+
+## Rationale
+- [finding] Root cause (bare binary name in PATH-less Waybar launch environment) is the most likely explanation and is well-supported by explorer research
+- [finding] All 8 bare `waybar-module-pomodoro` references are confined to the two target files: `.config/waybar/config` (3 refs) and `.config/waybar/scripts/pomodoro-preset.sh` (5 refs) — no other source files reference this binary
+- [finding] Verification steps (bash -n, --help check) adequately gate against the alternative failure mode of a missing binary
+- [finding] Plan scope is correctly limited to pomodoro-only; no decomposition needed
+
+## Assumption Challenges
+- [challenge] Binary path validity → mitigated by plan's --help verification step
+- [challenge] Completeness of reference coverage → confirmed all 8 references across both files; no others in repo
+- [challenge] JSONC $HOME expansion → confirmed Waybar does shell-expand $HOME in exec/on-click fields (existing config uses it on lines 94, 138)
+
+## Coder Guidance
+- [recommendation] Update or remove the `command -v waybar-module-pomodoro` guard (line 7 of pomodoro-preset.sh) since it checks bare PATH and will fail in the same environment that caused the original bug
+- [recommendation] Consider using `$HOME/.local/bin/waybar-module-pomodoro` to match existing config style conventions (lines 94, 138 already use `$HOME`)
+
+## Files Evaluated
+- `.config/waybar/config` (142 lines)
+- `.config/waybar/scripts/pomodoro-preset.sh` (33 lines)
+
+## Relations
+- gates [[waybar-pomodoro-not-showing]]
+- related_to [[knowledge]]

.memory/gates/gate-waybar-pomodoro-visibility-fix.md

@@ -0,0 +1,87 @@
+---
+title: gate-waybar-pomodoro-visibility-fix
+type: gate
+permalink: dotfiles/gates/gate-waybar-pomodoro-visibility-fix
+tags:
+- waybar
+- pomodoro
+- gate
+- pass
+---
+
+# Gate: Waybar Pomodoro Visibility Fix
+
+**Status:** PASS  
+**Date:** 2026-03-12  
+**Plan ref:** [[waybar-pomodoro-not-showing]]  
+**Scope:** `.config/waybar/config`, `.config/waybar/scripts/pomodoro-preset.sh`
+
+## Verdict Summary
+
+The implementation correctly addresses the root cause (PATH mismatch between Hyprland/Waybar environment and interactive shell). All four invocation points for `waybar-module-pomodoro` are now explicit, and no residual bare-binary references remain. Both standard and adversarial checks pass.
+
+## Standard Pass
+
+### Acceptance Criteria Verification
+
+| Criterion | Result |
+|---|---|
+| `custom/pomodoro` exec uses explicit path | ✅ Line 136: `$HOME/.local/bin/waybar-module-pomodoro --no-work-icons` |
+| on-click uses explicit path | ✅ Line 137: `$HOME/.local/bin/waybar-module-pomodoro toggle` |
+| on-click-middle uses explicit path | ✅ Line 139: `$HOME/.local/bin/waybar-module-pomodoro reset` |
+| on-click-right still delegates to preset script | ✅ Line 138 unchanged |
+| Preset script no longer uses PATH-dependent guard | ✅ `[[ ! -x "$POMODORO_BIN" ]]` replaces `command -v` |
+| Preset script routes all set-* calls through `$POMODORO_BIN` | ✅ Lines 30–32 |
+| Change is pomodoro-scoped only | ✅ No other modules touched |
+| Binary syntax check (`bash -n`) passes | ✅ (Lead evidence, exit 0) |
+| Binary exists and responds to `--help` | ✅ (Lead evidence, exit 0 with usage) |
+
+### Pre-mortem Risk Tracking
+
+| Risk | Status |
+|---|---|
+| Middle-click reset still using bare name | Resolved — line 139 uses explicit path |
+| Only one entry point updated | Resolved — all four updated |
+| Preset helper using `command -v` | Resolved — replaced with `[[ ! -x ... ]]` |
+| Binary path unstable across sessions | Not triggered — binary confirmed at path |
+
+## Adversarial Pass
+
+### Hypotheses
+
+| # | Hypothesis | Design | Expected failure | Observed |
+|---|---|---|---|---|
+| H1 | Empty/corrupt STATE_FILE causes crash | State file exists but empty | `current` reads as `""`, falls to else-branch | Safe: defaults to B-preset (short cycle), no crash |
+| H2 | Binary missing/non-executable | Guard `[[ ! -x ]]` fires | Exit 1 with stderr | Guard correctly triggers, script exits cleanly |
+| H3 | `$HOME` unset in Waybar env | `$HOME/.local/bin/...` fails to expand | Module fails silently | Same risk applies to all other modules using `$HOME` (line 94: `custom/uptime`); no regression introduced |
+| H4 | `set -e` aborts mid-preset (daemon down) | First `set-work` fails → remaining calls skipped | Partial preset applied | Pre-existing behavior; not a regression from this change |
+| H5 | STATE_FILE lost on reboot (`/tmp`) | Preset reverts to A-cycle | Unexpected preset on first right-click post-reboot | Intentional design, not a regression |
+| H6 | No bare `pomodoro` left anywhere in config | Grep scan | Old reference found | Zero old references found — clean |
+
+### Mutation Checks
+
+| Mutation | Would current tests detect? |
+|---|---|
+| One of exec/on-click/on-click-middle reverted to bare name | Yes — structural grep confirms all three use explicit path |
+| `POMODORO_BIN` guard inverted (`-x` instead of `! -x`) | Yes — guard would skip missing-binary error |
+| `read -r current` without fallback | Caught — `|| current="A"` handles failure |
+| `set-work` but not `set-short`/`set-long` through `$POMODORO_BIN` | Yes — all three lines verified |
+
+**MUTATION_ESCAPES: 0/4**
+
+## Unverified Aspects (Residual Risk)
+
+1. **Live Waybar rendering** — Cannot verify the module actually appears on the bar without a running Waybar session. The Lead noted this is impractical in the task context.
+2. **Binary behavior correctness** — `--help` confirms the binary exists and accepts the right subcommands, but actual timer JSON output format was not sampled. The `return-type: json` config assumes the binary outputs conforming JSON.
+3. **`$HOME` behavior under Waybar systemd unit** — Low risk (all other `$HOME`-using modules work), but not runtime-confirmed.
+
+These residual risks are infrastructure-gated (no running Wayland/Waybar session available in this context), not implementation defects.
+
+## Lesson Checks
+
+- [confirmed] PATH mismatch is the failure mode for Waybar custom modules — explicit paths are the correct fix pattern.
+- [confirmed] `[[ ! -x path ]]` guard is the right check for script-invoked binary dependencies.
+- [not observed] Any silent failures from the old `command -v` approach (fix is in place, no regression).
+
+## Relations
+- resolves [[waybar-pomodoro-not-showing]]

.memory/plans/fix-github-push-large-binary.md

@@ -17,11 +17,10 @@ tags:
 - [decision] Commit `2643a0a` later removed the file, but the blob still exists in local history, so GitHub rejects the push.
 
 ## Tasks
-- [ ] Rewrite the 4 local-only commits by soft-resetting to `origin/main`.
-- [ ] Recreate a clean commit set without the large binary in history.
-- [ ] Verify no large-file path remains in reachable history.
-- [ ] Retry `git push` and confirm success.
-
+- [x] Rewrite the 4 local-only commits by soft-resetting to `origin/main`.
+- [x] Recreate a clean commit set without the large binary in history.
+- [x] Verify no large-file path remains in reachable history.
+- [x] Retry `git push` and confirm success.
 ## Acceptance criteria
 - No reachable commit from `HEAD` contains `.local/bin/codebase-memory-mcp`.
 - `git push` to `origin/main` succeeds without GitHub large-file rejection.

.memory/plans/waybar-pomodoro-not-showing.md

@@ -0,0 +1,63 @@
+---
+title: waybar-pomodoro-not-showing
+type: note
+permalink: dotfiles/plans/waybar-pomodoro-not-showing
+tags:
+- waybar
+- pomodoro
+- plan
+---
+
+# Waybar Pomodoro Not Showing Implementation Plan
+
+> For implementation: use `subagent-driven-development` when subagents are available; otherwise use `executing-plans`.
+
+**Goal:** Restore the Waybar pomodoro module so it reliably appears on the bar.
+
+**Architecture:** The `custom/pomodoro` Waybar module depends on an external `waybar-module-pomodoro` binary and a preset helper script. The most likely failure mode is launch-time PATH mismatch between Hyprland/Waybar and the interactive shell, so the minimal fix is to make module and helper invocations explicit and independent of shell PATH.
+
+**Tech Stack:** JSONC-style Waybar config, shell script, Hyprland/Wayland desktop environment.
+
+## File map
+- Modify `.config/waybar/config` — make the pomodoro module invoke the binary explicitly.
+- Modify `.config/waybar/scripts/pomodoro-preset.sh` — make the preset helper use the same explicit binary path.
+
+## Task 1: Fix pomodoro command wiring
+
+**Files:**
+- Modify: `.config/waybar/config`
+- Modify: `.config/waybar/scripts/pomodoro-preset.sh`
+
+**Acceptance criteria:**
+- `custom/pomodoro` no longer depends on login-session PATH to find `waybar-module-pomodoro`.
+- Right-click preset switching still works.
+- The change is minimal and limited to pomodoro-related wiring.
+
+**Non-goals:**
+- Do not refactor unrelated Waybar modules.
+- Do not add system-wide installation steps or package management changes.
+
+**Verification:**
+- Run `bash -n /home/alex/dotfiles/.config/waybar/scripts/pomodoro-preset.sh` successfully.
+- Run `/home/alex/.local/bin/waybar-module-pomodoro --help` successfully to verify the explicit binary path exists.
+- Inspect resulting config references to confirm they use the explicit path consistently.
+
+**Likely regression surfaces:**
+- Right-click preset command path drift.
+- Middle-click reset command still using the old bare binary name.
+
+## Pre-mortem
+- Most likely failure: only one of the pomodoro entry points is updated, leaving click actions broken.
+- Fragile assumption: the binary remains at `/home/alex/.local/bin/waybar-module-pomodoro`.
+- Redesign trigger: if the binary path is unstable across sessions or machines, prefer a Hyprland PATH fix instead.
+- Easy-to-miss regression: preset helper still using `command -v` and failing under Waybar's environment.
+
+## Execution notes
+- Updated `.config/waybar/config` `custom/pomodoro` wiring to use `$HOME/.local/bin/waybar-module-pomodoro` for `exec`, `on-click`, and `on-click-middle`.
+- Updated `.config/waybar/scripts/pomodoro-preset.sh` to remove PATH reliance by introducing `POMODORO_BIN="$HOME/.local/bin/waybar-module-pomodoro"`, replacing the `command -v` guard with `[[ ! -x "$POMODORO_BIN" ]]`, and routing all `set-work`/`set-short`/`set-long` calls through `"$POMODORO_BIN"`.
+- Scope remained pomodoro-only; no unrelated Waybar modules or scripts were changed.
+
+## Outcomes
+- `bash -n /home/alex/dotfiles/.config/waybar/scripts/pomodoro-preset.sh` passed (no syntax errors).
+- `/home/alex/.local/bin/waybar-module-pomodoro --help` succeeded and printed usage, confirming explicit-path binary availability.
+- No practical automated test harness exists here for full Waybar runtime rendering in this task context; verification used the minimal command-level checks above.

.memory/research/waybar-pomodoro-not-showing.md

@@ -0,0 +1,148 @@
+---
+title: waybar-pomodoro-not-showing
+type: note
+permalink: dotfiles/research/waybar-pomodoro-not-showing
+tags:
+- waybar
+- pomodoro
+- debugging
+- risk
+---
+
+# Waybar Pomodoro Not Showing — Research Findings
+
+## Scope
+Investigation of why `custom/pomodoro` does not appear on the Waybar status bar.
+Files inspected: `.config/waybar/config`, `.config/waybar/style.css`, `.config/waybar/scripts/pomodoro-preset.sh`.
+
+## Module Wiring (as configured)
+
+### modules-left (config line 5–9)
+```json
+"modules-left": [
+  "backlight",
+  "wireplumber",
+  "custom/pomodoro",
+],
+```
+`custom/pomodoro` IS present in `modules-left`.
+
+### custom/pomodoro definition (config lines 133–140)
+```json
+"custom/pomodoro": {
+  "format": "{}",
+  "return-type": "json",
+  "exec": "waybar-module-pomodoro --no-work-icons",
+  "on-click": "waybar-module-pomodoro toggle",
+  "on-click-right": "$HOME/.config/waybar/scripts/pomodoro-preset.sh",
+  "on-click-middle": "waybar-module-pomodoro reset",
+},
+```
+
+### CSS selector (style.css lines 106–109)
+```css
+#custom-pomodoro {
+    padding: 0 4px;
+    color: @red;
+}
+```
+Selector is correct and present.
+
+### Script (scripts/pomodoro-preset.sh)
+- Guarded by `command -v waybar-module-pomodoro` check (exits 1 if not installed).
+- Sets work/short/long durations via `waybar-module-pomodoro set-*` subcommands.
+- Toggle cycles between preset A (50/10/20) and preset B (25/5/15).
+- **Script itself is logically correct.**
+
+---
+
+## Root Cause Analysis (ranked by confidence)
+
+### 🔴 #1 — `waybar-module-pomodoro` binary not installed / not on PATH (confidence: ~90%)
+- The `exec` command is `waybar-module-pomodoro --no-work-icons` — a **bare binary name**, resolved from PATH at Waybar launch time.
+- Waybar inherits the environment of its launcher (Hyprland `exec-once`), which may NOT include the user's shell PATH (`~/.local/bin`, `/usr/local/bin`, etc.).
+- `fish/config.fish` adds `/home/alex/dotfiles/.local/bin` to PATH, but that is only set in interactive Fish sessions — **Hyprland's exec-once does not source Fish config**.
+- No package manager manifest, AUR package list, or install script mentions `waybar-module-pomodoro`.
+- When `exec` fails to start, Waybar hides the module entirely (no fallback text) — the module disappears silently.
+- **This is the most likely cause.** Verify with: `which waybar-module-pomodoro` in a non-Fish shell, or check `journalctl --user -u waybar` for "Failed to execute".
+
+### 🟠 #2 — `interval` key absent on custom/pomodoro (confidence: ~65%)
+- `custom/pomodoro` has NO `interval` key. For a persistent daemon (`waybar-module-pomodoro` runs and writes JSON to stdout continuously), this is correct — Waybar treats it as a long-lived subprocess.
+- BUT if the binary is supposed to be polled (not a persistent daemon), missing `interval` means Waybar will only run it once and never refresh.
+- The `return-type: json` combined with no `interval` means Waybar expects the binary to **continuously emit newline-delimited JSON** to stdout. If the binary only emits once and exits, the module will show blank after the first read.
+- This is a secondary cause contingent on what `waybar-module-pomodoro` actually does. If it is a daemon that stays alive, #1 is the only blocker; if it exits after one line, `interval` is needed.
+
+### 🟡 #3 — Binary exists but crashes on `--no-work-icons` flag (confidence: ~25%)
+- The `--no-work-icons` flag may not be a valid flag for the installed version of `waybar-module-pomodoro`.
+- An unrecognized flag causing the binary to exit with a non-zero code would suppress the module.
+- Check: `waybar-module-pomodoro --help` or `waybar-module-pomodoro --no-work-icons` manually.
+
+### 🟡 #4 — Config JSON parse failure (confidence: ~15%)
+- The config uses tab-indented lines (lines 134–139 use `\t`) while the rest uses spaces — mixed indentation is cosmetically inconsistent but does NOT cause JSON parse errors.
+- Waybar's parser accepts JSON5/hjson (trailing commas, `//` comments) — both are used in this config and are fine.
+- No structural JSON error was found in the config.
+
+### ⚪ #5 — Hyprland not auto-starting Waybar at all (confidence: ~10%)
+- If `exec-once=waybar` in `hyprland.conf` is missing or commented out, the bar won't show at all (not just the pomodoro module). Not specific to this module.
+
+---
+
+## Concrete Edit Points
+
+### Fix #1 (most likely): Ensure binary is installed and PATH is set in Waybar launch environment
+
+**Option A — Install the binary system-wide:**
+Install `waybar-module-pomodoro` via your package manager (e.g. `paru -S waybar-module-pomodoro` on Arch) so it is in `/usr/bin` or `/usr/local/bin`, which is always in Waybar's inherited PATH.
+
+**Option B — Use absolute path in config:**
+```diff
+- "exec": "waybar-module-pomodoro --no-work-icons",
+- "on-click": "waybar-module-pomodoro toggle",
+- "on-click-middle": "waybar-module-pomodoro reset",
++ "exec": "$HOME/.local/bin/waybar-module-pomodoro --no-work-icons",
++ "on-click": "$HOME/.local/bin/waybar-module-pomodoro toggle",
++ "on-click-middle": "$HOME/.local/bin/waybar-module-pomodoro reset",
+```
+File: `.config/waybar/config`, lines 136–139.
+
+**Option C — Set PATH in Hyprland env (preferred for Wayland):**
+Add to `.config/hypr/hyprland.conf`:
+```
+env = PATH,$HOME/.local/bin:/usr/local/bin:/usr/bin:/bin
+```
+
+### Fix #2 (if binary is a one-shot, not a daemon): Add `interval` key
+```diff
+"custom/pomodoro": {
+  "format": "{}",
+  "return-type": "json",
++ "interval": 1,
+  "exec": "waybar-module-pomodoro --no-work-icons",
+```
+File: `.config/waybar/config`, line 134 (insert after `"return-type": "json",`).
+
+---
+
+## Files Involved
+
+| File | Role |
+|---|---|
+| `.config/waybar/config` | Module registration in `modules-left`, `custom/pomodoro` definition |
+| `.config/waybar/style.css` | `#custom-pomodoro` CSS selector (present, correct) |
+| `.config/waybar/scripts/pomodoro-preset.sh` | Right-click preset toggler (calls binary) |
+| `.config/hypr/hyprland.conf` | Waybar autostart + env block (outside Waybar dir) |
+| `waybar-module-pomodoro` binary | External binary — must be installed and on PATH |
+
+---
+
+## Likely Bug Surfaces (Adjacent Risk Areas)
+
+1. **`custom/uptime`** (config line 89–95): Also uses a bare script path `$HOME/.config/waybar/scripts/uptime.sh`. Same PATH-at-launch issue could affect it if shell env is not inherited. The script exists in the repo (`scripts/` dir shows only `pomodoro-preset.sh`) — **`uptime.sh` is missing from the repo**, meaning this module may also be broken.
+2. **`custom/music`** (config line 44–52): Uses `playerctl` — same PATH issue; no `playerctl` install evidence in the repo.
+3. **`hyprland/workspaces`** (config line 22–28): Defined in config but NOT in any of `modules-left`, `modules-center`, or `modules-right` — it is **a dead definition that never renders**.
+4. **`custom/lock`** (config line 127–131): Defined but also absent from all three module lists — another dead definition.
+5. **`network`** (config line 60–68): Defined but not in any module list — dead definition.
+6. **Trailing comma on line 8** of `modules-left`: Benign in Waybar's parser but would break standard JSON parsers if config is ever processed by tools expecting strict JSON.
+
+## Relations
+- related_to [[dotfiles/knowledge]]