fix help formatting and add missing triggers

- Restructure help sections to use gohelp.Item() instead of raw .Text() blocks
- Add missing .tappressrelease and .tapholdrelease to help and README
- Update restrictions to accurately list all array-command behaviors

Author: DeprecatedLuar

README.md

@@ -187,6 +187,8 @@ Config lives at `~/.config/akeyshually/`:
 | `.longpress` / `.longpress(ms)` | `"key.longpress(500)"` | Fire once after threshold (one-shot) |
 | `.holdrelease` / `.holdrelease(ms)` | `"key.holdrelease(500)" = ["hold_cmd", "release_cmd"]` | Execute at hold threshold and on release |
 | `.taplongpress` / `.taplongpress(tap_ms, long_ms)` | `"key.taplongpress" = ["tap_cmd", "long_cmd"]` | Tap once, or tap-then-longpress |
+| `.tappressrelease` / `.tappressrelease(tap_ms)` | `"key.tappressrelease(200)" = ["press_cmd", "release_cmd"]` | Tap then press fires first, release fires second |
+| `.tapholdrelease` / `.tapholdrelease(tap_ms, hold_ms)` | `"key.tapholdrelease" = ["hold_cmd", "release_cmd"]` | Tap then hold fires first, release fires second |
 
 **Modifiers** — change how the command executes:
 

internal/commands/help.go

@@ -29,23 +29,27 @@ var (
 	helpConfig = gohelp.NewPage("config", "configuration file documentation").
 		Text("Config File: ~/.config/akeyshually/config.toml").
 		Section("[settings]",
-			gohelp.Item("default_interval", "Default interval for repeat behaviors (milliseconds, default: 150)"),
-			gohelp.Item("disable_media_keys", "Forward media keys to system (default: false)"),
-			gohelp.Item("shell", "Shell to use for commands (default: $SHELL, fallback: sh)"),
-			gohelp.Item("env_file", "File to source before command execution (optional)"),
-			gohelp.Item("notify_on_overlay_change", "Desktop notifications when overlays change (default: false)"),
+			gohelp.Item("default_interval", "Default interval for repeat behaviors (milliseconds)", "default_interval = 150"),
+			gohelp.Item("disable_media_keys", "Forward media keys to system", "disable_media_keys = false"),
+			gohelp.Item("shell", "Shell to use for commands (default: $SHELL, fallback: sh)", "shell = \"/bin/bash\""),
+			gohelp.Item("env_file", "File to source before command execution", "env_file = \"~/.profile\""),
+			gohelp.Item("notify_on_overlay_change", "Desktop notifications when overlays change", "notify_on_overlay_change = true"),
 			gohelp.Item("devices", "List of device name substrings to grab (case-insensitive)", "devices = [\"Huion\", \"Xbox Controller\"]"),
 		).
-		Text("[settings]\ndefault_interval = 150\ndisable_media_keys = false\nshell = \"/bin/bash\"\nenv_file = \"~/.profile\"\nnotify_on_overlay_change = false").
 		Section("[shortcuts]",
 			gohelp.Item("Key modifiers", "super, ctrl, alt, shift (lowercase, no left/right distinction)"),
 			gohelp.Item("Keys", "lowercase letters, numbers, special keys (print, space, etc.)"),
 			gohelp.Item("Axis inputs", "x, y, z, rx, ry, rz, abs_x, abs_y, etc. with +/- direction (see 'help axis')"),
-			gohelp.Item("Syntax", "Use + to separate modifiers and key"),
+			gohelp.Item("Syntax", "Use + to separate modifiers and key", "\"super+t\" = \"alacritty\""),
 			gohelp.Item("Triggers", ".onpress (default), .hold, .doubletap, .taphold, .pressrelease, .longpress, etc."),
 			gohelp.Item("Modifiers", ".switch, .repeat, .passthrough"),
 		).
-		Text("[shortcuts]\n\"super.pressrelease\" = [\"\", \"rofi\"]  # Tap modifier key\n\"super+t\" = \"alacritty\"\n\"f9.onpress.repeat\" = \"xdotool click 1\"  # Toggle auto-clicker\n\"rx+\" = \">scrollup\"  # Axis input (drawing tablet touchstrip)").
+		Section("Examples",
+			gohelp.Item("Tap modifier key", "Execute command on modifier release", "\"super.pressrelease\" = [\"\", \"rofi\"]"),
+			gohelp.Item("Launch terminal", "Simple key combo", "\"super+t\" = \"alacritty\""),
+			gohelp.Item("Toggle auto-clicker", "Repeat while held or toggle on press", "\"f9.onpress.repeat\" = \"xdotool click 1\""),
+			gohelp.Item("Axis scrolling", "Touchstrip or peripheral axis input", "\"rx+\" = \">scrollup\""),
+		).
 		Section("[command_variables]",
 			gohelp.Item("browser", "Reusable command alias", "browser = \"brave-browser --new-window\""),
 			gohelp.Item("terminal", "Reusable command alias", "terminal = \"alacritty --working-directory ~\""),
@@ -66,15 +70,14 @@ var (
 		).
 		Section("Commands",
 			gohelp.Item("enable gaming.toml", "Enable overlay and restart daemon", "akeyshually enable gaming.toml"),
-			gohelp.Item("disable gaming.toml", "Disable overlay and restart daemon"),
-			gohelp.Item("list", "Show all config files and their status"),
-			gohelp.Item("clear", "Disable all overlays"),
-			gohelp.Item("config gaming", "Edit gaming.toml overlay"),
+			gohelp.Item("disable gaming.toml", "Disable overlay and restart daemon", "akeyshually disable gaming.toml"),
+			gohelp.Item("list", "Show all config files and their status", "akeyshually list"),
+			gohelp.Item("clear", "Disable all overlays", "akeyshually clear"),
+			gohelp.Item("config gaming", "Edit gaming.toml overlay", "akeyshually config gaming"),
 		).
 		Section("Settings",
-			gohelp.Item("notify_on_overlay_change", "Desktop notifications when overlays change (default: false)"),
-		).
-		Text("Enable in config.toml:\n[settings]\nnotify_on_overlay_change = true")
+			gohelp.Item("notify_on_overlay_change", "Desktop notifications when overlays change", "notify_on_overlay_change = true"),
+		)
 
 	helpModifiers = gohelp.NewPage("modifiers", "triggers and modifiers syntax reference").
 		Text("Triggers define when the action fires. Modifiers stack on top to change execution behavior.").
@@ -87,13 +90,18 @@ var (
 			gohelp.Item(".longpress(ms)", "Fire once after threshold (one-shot)", "\"super+h.longpress(1000)\" = \"shutdown\""),
 			gohelp.Item(".holdrelease(ms)", "Execute at hold threshold AND on release (2-command array)", "\"mute.holdrelease(500)\" = [\"enable-mic\", \"disable-mic\"]"),
 			gohelp.Item(".taplongpress(tap_ms, long_ms)", "Tap fires first, tap-then-longpress fires second (2-command array)", "\"super+space.taplongpress\" = [\"quick\", \"long\"]"),
+			gohelp.Item(".tappressrelease(tap_ms)", "Tap then press fires first, release fires second (2-command array)", "\"mute.tappressrelease(200)\" = [\"start\", \"stop\"]"),
+			gohelp.Item(".tapholdrelease(tap_ms, hold_ms)", "Tap then hold fires first, release fires second (2-command array)", "\"f1.tapholdrelease\" = [\"hold-start\", \"hold-end\"]"),
 		).
 		Section("Modifiers",
 			gohelp.Item(".switch", "Cycle through array of commands on each press", "\"f2.switch\" = [\"cmd1\", \"cmd2\", \"cmd3\"]"),
 			gohelp.Item(".repeat", "Loop command: with .hold (while held) or .onpress (toggle)", "\"f9.onpress.repeat\" = \"xdotool click 1\""),
 			gohelp.Item(".passthrough", "Match regardless of modifier state", "\"v.passthrough\" = \"copyq toggle\""),
 		).
-		Text("Restrictions:\n  • .doubletap and .taphold only work on single keys (no combos)\n  • .switch, .taphold, .pressrelease, .holdrelease, and .taplongpress require command arrays")
+		Section("Restrictions",
+			gohelp.Item("Single keys only", ".doubletap and .taphold only work on single keys (no combos)"),
+			gohelp.Item("Array commands", ".switch, .pressrelease, .holdrelease, .taplongpress, .tappressrelease, and .tapholdrelease require 2+ commands"),
+		)
 
 	helpAxis = gohelp.NewPage("axis", "absolute axis and peripheral support").
 		Text("akeyshually supports absolute axis (ABS) events from evdev devices - bind any peripheral with axis input.").
@@ -103,14 +111,18 @@ var (
 		).
 		Section("Syntax",
 			gohelp.Item("Direction suffix", "Append + or - to axis name for direction", "\"rx+\" or \"abs_y-\""),
-			gohelp.Item("Commands", "Any command works, including remap scroll output", "\">scrollup\", \">scrolldown\", \">scrollleft\", \">scrollright\""),
+			gohelp.Item("Scroll output", "Remap to scroll events", "\">scrollup\", \">scrolldown\", \">scrollleft\", \">scrollright\""),
+			gohelp.Item("Shell command", "Any shell command works", "\"volume_up\", \"brightness-control +10\""),
+		).
+		Section("Examples",
+			gohelp.Item("Touchstrip scroll up", "Positive direction triggers scroll up", "\"rx+\" = \">scrollup\""),
+			gohelp.Item("Touchstrip scroll down", "Negative direction triggers scroll down", "\"rx-\" = \">scrolldown\""),
+			gohelp.Item("Axis volume control", "Map axis movement to shell commands", "\"abs_y+\" = \"volume_up\""),
 		).
-		Text("[shortcuts]\n\"rx+\" = \">scrollup\"      # Touchstrip up → scroll up\n\"rx-\" = \">scrolldown\"    # Touchstrip down → scroll down\n\"abs_y+\" = \"volume_up\"   # Axis movement → volume control").
 		Section("Device Detection",
 			gohelp.Item("Auto-detection", "Most devices auto-detected by capability flags"),
-			gohelp.Item("Explicit grab", "Add device name substring to [settings] devices array if not detected", "devices = [\"Tablet Monitor Touch Strip\"]"),
-		).
-		Text("Example: Huion Kamvas Pro 13 touchstrip scrolling\n\n[settings]\ndevices = [\"Tablet Monitor Touch Strip\"]\n\n[shortcuts]\n\"rx+\" = \">scrollup\"\n\"rx-\" = \">scrolldown\"")
+			gohelp.Item("Explicit grab", "Add device name substring to [settings] devices array", "devices = [\"Tablet Monitor Touch Strip\"]"),
+		)
 )
 
 // Help displays usage information or topic-specific help.

internal/config/config.go

@@ -45,6 +45,8 @@ const (
 	BehaviorHoldRelease         // Commands[0] at hold threshold (can be ""), Commands[1] on release after threshold
 	BehaviorTapHold             // tap fires Commands[0], tap-then-hold sustains Commands[1]
 	BehaviorTapLongPress        // tap fires Commands[0], tap-then-longpress fires Commands[1] once
+	BehaviorTapPressRelease     // tap, then Commands[0] on second press, Commands[1] on release
+	BehaviorTapHoldRelease      // tap, then Commands[0] at hold threshold, Commands[1] on release
 	BehaviorEscapePending       // pseudo-candidate: prevents early resolution when escape hatches exist
 )
 
@@ -430,6 +432,8 @@ func ParseShortcut(key string, value interface{}) (*ParsedShortcut, error) {
 	intervalRegex := regexp.MustCompile(`^(hold|longpress|doubletap|holdrelease)\((\d+\.?\d*|\d*\.\d+)\)$`)
 	tapHoldRegex := regexp.MustCompile(`^tap(?:\((\d+\.?\d*|\d*\.\d+)\))?hold(?:\((\d+\.?\d*|\d*\.\d+)\))?$`)
 	tapLongPressRegex := regexp.MustCompile(`^tap(?:\((\d+\.?\d*|\d*\.\d+)\))?longpress(?:\((\d+\.?\d*|\d*\.\d+)\))?$`)
+	tapPressReleaseRegex := regexp.MustCompile(`^tap(?:\((\d+\.?\d*|\d*\.\d+)\))?pressrelease$`)
+	tapHoldReleaseRegex := regexp.MustCompile(`^tap(?:\((\d+\.?\d*|\d*\.\d+)\))?holdrelease(?:\((\d+\.?\d*|\d*\.\d+)\))?$`)
 
 	for i := 1; i < len(parts); i++ {
 		part := strings.ToLower(parts[i])
@@ -462,6 +466,30 @@ func ParseShortcut(key string, value interface{}) (*ParsedShortcut, error) {
 			continue
 		}
 
+		// Check for tappressrelease with optional interval: tap(N)pressrelease
+		if matches := tapPressReleaseRegex.FindStringSubmatch(part); matches != nil {
+			shortcut.Behavior = BehaviorTapPressRelease
+			if matches[1] != "" {
+				interval, _ := strconv.ParseFloat(matches[1], 64)
+				shortcut.Interval = normalizeInterval(interval)
+			}
+			continue
+		}
+
+		// Check for tapholdrelease with optional intervals: tap(N)holdrelease(N)
+		if matches := tapHoldReleaseRegex.FindStringSubmatch(part); matches != nil {
+			shortcut.Behavior = BehaviorTapHoldRelease
+			if matches[1] != "" {
+				interval, _ := strconv.ParseFloat(matches[1], 64)
+				shortcut.Interval = normalizeInterval(interval)
+			}
+			if matches[2] != "" {
+				interval, _ := strconv.ParseFloat(matches[2], 64)
+				shortcut.HoldInterval = normalizeInterval(interval)
+			}
+			continue
+		}
+
 		// Check for interval notation: hold(N), longpress(N), doubletap(N)
 		if matches := intervalRegex.FindStringSubmatch(part); matches != nil {
 			modifierName := matches[1]
@@ -497,6 +525,10 @@ func ParseShortcut(key string, value interface{}) (*ParsedShortcut, error) {
 			shortcut.Behavior = BehaviorDoubleTap
 		case "pressrelease":
 			shortcut.Behavior = BehaviorPressRelease
+		case "tappressrelease":
+			shortcut.Behavior = BehaviorTapPressRelease
+		case "tapholdrelease":
+			shortcut.Behavior = BehaviorTapHoldRelease
 		case "onrelease":
 			return nil, fmt.Errorf("onrelease removed: use .pressrelease = [\"\", \"cmd\"]")
 		case "onpress":
@@ -532,6 +564,10 @@ func behaviorName(b BehaviorMode) string {
 		return "taphold"
 	case BehaviorTapLongPress:
 		return "taplongpress"
+	case BehaviorTapPressRelease:
+		return "tappressrelease"
+	case BehaviorTapHoldRelease:
+		return "tapholdrelease"
 	default:
 		return "unknown"
 	}

internal/config/validate.go

@@ -255,15 +255,17 @@ func validateRemapCommand(cmd string) error {
 
 // Lookup table mapping behaviors to their validation functions
 var behaviorValidators = map[BehaviorMode]func(*ParsedShortcut) error{
-	BehaviorNormal:       validateNormal,
-	BehaviorHold:         validateHold,
-	BehaviorLongPress:    validateLongPress,
-	BehaviorSwitch:       validateSwitch,
-	BehaviorDoubleTap:    validateDoubleTap,
-	BehaviorPressRelease: validatePressRelease,
-	BehaviorHoldRelease:  validateHoldRelease,
-	BehaviorTapHold:      validateTapHold,
-	BehaviorTapLongPress: validateTapLongPress,
+	BehaviorNormal:          validateNormal,
+	BehaviorHold:            validateHold,
+	BehaviorLongPress:       validateLongPress,
+	BehaviorSwitch:          validateSwitch,
+	BehaviorDoubleTap:       validateDoubleTap,
+	BehaviorPressRelease:    validatePressRelease,
+	BehaviorHoldRelease:     validateHoldRelease,
+	BehaviorTapHold:         validateTapHold,
+	BehaviorTapLongPress:    validateTapLongPress,
+	BehaviorTapPressRelease: validateTapPressRelease,
+	BehaviorTapHoldRelease:  validateTapHoldRelease,
 }
 
 // Individual behavior validators - each validates command count and behavior-specific rules
@@ -333,3 +335,17 @@ func validateTapLongPress(p *ParsedShortcut) error {
 	}
 	return nil
 }
+
+func validateTapPressRelease(p *ParsedShortcut) error {
+	if len(p.Commands) != 2 {
+		return fmt.Errorf("tappressrelease behavior requires exactly 2 commands")
+	}
+	return nil
+}
+
+func validateTapHoldRelease(p *ParsedShortcut) error {
+	if len(p.Commands) != 2 {
+		return fmt.Errorf("tapholdrelease behavior requires exactly 2 commands")
+	}
+	return nil
+}

internal/ladder/ladder.go

@@ -69,7 +69,7 @@ func Run(
 	// BUT: Skip early exit if the candidate is EscapePending (needs to wait for actual key events)
 	if len(candidates) == 1 && len(ladder) == 0 && candidates[0].Shortcut.Behavior != config.BehaviorEscapePending {
 		common.LogDebug(">>> LADDER %s: single candidate no timers, firing immediately", combo)
-		fireWinner(combo, keyCode, value, &candidates[0], cfg, loopState, injector, virtual, modifiers, ctx, state)
+		fireWinner(combo, keyCode, value, &candidates[0], cfg, loopState, injector, virtual, modifiers, ctx, state, pressed)
 		return
 	}
 
@@ -153,7 +153,7 @@ func Run(
 				if timer != nil {
 					timer.Stop()
 				}
-				fireWinner(combo, keyCode, value, &candidates[0], cfg, loopState, injector, virtual, modifiers, ctx, state)
+				fireWinner(combo, keyCode, value, &candidates[0], cfg, loopState, injector, virtual, modifiers, ctx, state, pressed)
 				return
 			}
 
@@ -181,7 +181,7 @@ func Run(
 				if timer != nil {
 					timer.Stop()
 				}
-				fireWinner(combo, keyCode, value, &candidates[0], cfg, loopState, injector, virtual, modifiers, ctx, state)
+				fireWinner(combo, keyCode, value, &candidates[0], cfg, loopState, injector, virtual, modifiers, ctx, state, pressed)
 				return
 			}
 
@@ -198,7 +198,7 @@ func Run(
 			// Last standing wins
 			if len(candidates) == 1 {
 				common.LogDebug(">>> LADDER %s: WINNER=%s (last standing after timer)", combo, behaviorName(candidates[0].Shortcut.Behavior))
-				fireWinner(combo, keyCode, value, &candidates[0], cfg, loopState, injector, virtual, modifiers, ctx, state)
+				fireWinner(combo, keyCode, value, &candidates[0], cfg, loopState, injector, virtual, modifiers, ctx, state, pressed)
 				return
 			}
 
@@ -259,8 +259,8 @@ func buildTimerLadder(candidates []timers.Candidate, defaultInterval float64) []
 		interval := intervalOrDefault(c.Shortcut.Interval, defaultInterval)
 
 		switch c.Shortcut.Behavior {
-		case config.BehaviorDoubleTap:
-			// Needs Phase 1 timer for doubletap window
+		case config.BehaviorDoubleTap, config.BehaviorTapPressRelease:
+			// Needs Phase 1 timer for doubletap/tap window
 			if existing, ok := thresholds[1]; !ok || ms(interval) > existing {
 				thresholds[1] = ms(interval)
 			}
@@ -271,7 +271,7 @@ func buildTimerLadder(candidates []timers.Candidate, defaultInterval float64) []
 				thresholds[1] = ms(interval)
 			}
 
-		case config.BehaviorTapHold, config.BehaviorTapLongPress:
+		case config.BehaviorTapHold, config.BehaviorTapLongPress, config.BehaviorTapHoldRelease:
 			// Needs Phase 1 timer for tap window
 			if existing, ok := thresholds[1]; !ok || ms(interval) > existing {
 				thresholds[1] = ms(interval)
@@ -332,7 +332,7 @@ func isEliminated(b config.BehaviorMode, count int, pressed bool, phase int, has
 		}
 		return false
 
-	case config.BehaviorDoubleTap:
+	case config.BehaviorDoubleTap, config.BehaviorTapPressRelease:
 		// Eliminated by window expiry with no second press
 		if phase >= 1 && count < 2 {
 			return true
@@ -343,7 +343,7 @@ func isEliminated(b config.BehaviorMode, count int, pressed bool, phase int, has
 		}
 		return false
 
-	case config.BehaviorTapHold, config.BehaviorTapLongPress:
+	case config.BehaviorTapHold, config.BehaviorTapLongPress, config.BehaviorTapHoldRelease:
 		// Eliminated by releasing after tap window expired without second press
 		if !pressed && count < 2 && phase >= 1 {
 			return true
@@ -386,6 +386,7 @@ func fireWinner(
 	modifiers matcher.ModifierState,
 	ctx context.Context,
 	state *timers.ComboState,
+	pressed bool,
 ) {
 	s := winner.Shortcut
 
@@ -418,14 +419,23 @@ func fireWinner(
 			common.LogTrigger(resolvedCmd)
 			executor.Run(resolvedCmd, execCtx)
 		}
-		// 10ms gap between press and release commands
-		time.AfterFunc(10*time.Millisecond, func() {
-			if s.Commands[1] != "" {
-				resolvedCmd := cfg.ResolveCommand(s.Commands[1])
-				common.LogTrigger(resolvedCmd)
-				executor.Run(resolvedCmd, execCtx)
+		// If key is still pressed, wait for release (seesaw behavior)
+		// If key already released, fire second command immediately (rapid succession)
+		if pressed {
+			// Seesaw: wait for actual release event
+			select {
+			case <-ctx.Done():
+			case <-state.ReleaseCh:
 			}
-		})
+		} else {
+			// Rapid succession: 10ms gap (key already released)
+			time.Sleep(10 * time.Millisecond)
+		}
+		if s.Commands[1] != "" {
+			resolvedCmd := cfg.ResolveCommand(s.Commands[1])
+			common.LogTrigger(resolvedCmd)
+			executor.Run(resolvedCmd, execCtx)
+		}
 
 	case config.BehaviorHold, config.BehaviorLongPress:
 		common.LogMatch(combo+".hold", combo)
@@ -505,6 +515,42 @@ func fireWinner(
 		common.LogTrigger(resolvedCmd)
 		executor.Run(resolvedCmd, execCtx)
 
+	case config.BehaviorTapPressRelease:
+		common.LogMatch(combo+".tappressrelease", combo)
+		if s.Commands[0] != "" {
+			resolvedCmd := cfg.ResolveCommand(s.Commands[0])
+			common.LogTrigger(resolvedCmd)
+			executor.Run(resolvedCmd, execCtx)
+		}
+		// Wait for release
+		select {
+		case <-ctx.Done():
+		case <-state.ReleaseCh:
+		}
+		if s.Commands[1] != "" {
+			resolvedCmd := cfg.ResolveCommand(s.Commands[1])
+			common.LogTrigger(resolvedCmd)
+			executor.Run(resolvedCmd, execCtx)
+		}
+
+	case config.BehaviorTapHoldRelease:
+		common.LogMatch(combo+".tapholdrelease", combo)
+		if s.Commands[0] != "" {
+			resolvedCmd := cfg.ResolveCommand(s.Commands[0])
+			common.LogTrigger(resolvedCmd)
+			executor.Run(resolvedCmd, execCtx)
+		}
+		select {
+		case <-ctx.Done():
+		case <-state.ReleaseCh:
+		}
+		if s.Commands[1] != "" {
+			resolvedCmd := cfg.ResolveCommand(s.Commands[1])
+			common.LogMatch(combo+".tapholdrelease.release", combo)
+			common.LogTrigger(resolvedCmd)
+			executor.Run(resolvedCmd, execCtx)
+		}
+
 	case config.BehaviorEscapePending:
 		// No-op: this should never fire (eliminated before it can win)
 		common.LogDebug("BUG: EscapePending won the ladder for %s (should be impossible)", combo)
@@ -588,6 +634,10 @@ func behaviorName(b config.BehaviorMode) string {
 		return "taphold"
 	case config.BehaviorTapLongPress:
 		return "taplongpress"
+	case config.BehaviorTapPressRelease:
+		return "tappressrelease"
+	case config.BehaviorTapHoldRelease:
+		return "tapholdrelease"
 	case config.BehaviorEscapePending:
 		return "escape_pending"
 	default: