add runtime debugging signals and convert to magev0.10.0

- Add SIGUSR1 handler for goroutine stack dumps when app hangs
- Add SIGUSR2 handler for full profiling (heap, cpu, block)
- Add --debug-dir flag for configurable debug output location
- Convert build system from go-task to mage
- Update documentation with debugging workflow
- Bump version to 0.10.0

1 files changed, 84 insertions, 3 deletions

diff --git a/README.md b/README.md
index e6c9e6d..94359f8 100644
--- a/README.md
+++ b/README.md
@@ -35,10 +35,10 @@ go install codeberg.org/snonux/tasksamurai/cmd/tasksamurai@latest
 Alternatively, clone this repository and run:
 
 ```bash
-go-task install
+mage install
 ```
 
-The second method requires [go-task](https://taskfile.dev/) to be installed.
+The second method requires [mage](https://magefile.org/) to be installed.
 
 ### Usage
 
@@ -58,4 +58,85 @@ tasksamurai -- -excludetag +includetag
 
 ### Flags
 
-- `--disco`: start Task Samurai in disco mode, changing the theme every time a task is modified.
+- `--browser-cmd <command>`: command used to open URLs (default: firefox on Linux, open on macOS)
+- `--debug-log <path>`: path to debug log file for Taskwarrior commands
+- `--debug-dir <directory>`: directory for runtime debug output (goroutine dumps, profiles)
+- `--disco`: start Task Samurai in disco mode, changing the theme every time a task is modified
+
+## Debugging
+
+If Task Samurai appears to hang or freeze, you can capture runtime diagnostics using signal handlers to help diagnose the issue.
+
+### Signal Handlers (Unix/Linux/macOS only)
+
+Task Samurai supports two debugging signals:
+
+#### SIGUSR1 - Quick Goroutine Dump
+
+Captures all goroutine stacks to a timestamped text file for quick inspection:
+
+```bash
+# Find the Task Samurai process ID
+ps aux | grep tasksamurai
+
+# Send signal to dump goroutines
+kill -SIGUSR1 <pid>
+```
+
+This creates a file like `tasksamurai-goroutines-20260204-143022.txt` showing what each goroutine is doing.
+
+#### SIGUSR2 - Full Profile Dump
+
+Captures comprehensive profiling data for deeper analysis:
+
+```bash
+# Send signal to dump full profiles
+kill -SIGUSR2 <pid>
+```
+
+This creates multiple files:
+- `tasksamurai-TIMESTAMP-goroutines.txt` - Goroutine stacks (text)
+- `tasksamurai-TIMESTAMP-heap.pprof` - Memory allocations
+- `tasksamurai-TIMESTAMP-cpu.pprof` - CPU profile (5 second sample)
+- `tasksamurai-TIMESTAMP-block.pprof` - Lock contention events
+
+### Analyzing Profiles
+
+Use Go's pprof tool to analyze the binary profile files:
+
+```bash
+# Interactive analysis
+go tool pprof tasksamurai-TIMESTAMP-heap.pprof
+
+# Generate visualization (requires graphviz)
+go tool pprof -web tasksamurai-TIMESTAMP-cpu.pprof
+
+# Top functions by CPU usage
+go tool pprof -top tasksamurai-TIMESTAMP-cpu.pprof
+```
+
+### Specifying Output Location
+
+By default, debug files are written to the current working directory. Use the `--debug-dir` flag to specify a different location:
+
+```bash
+tasksamurai --debug-dir=/tmp/tasksamurai-debug
+```
+
+### Example Debugging Workflow
+
+When Task Samurai hangs:
+
+1. **Keep the hung process running** - Don't kill it yet!
+2. Find the process ID: `pgrep tasksamurai` or `ps aux | grep tasksamurai`
+3. Dump goroutines: `kill -SIGUSR1 <pid>`
+4. Open the generated file to see what goroutines are blocked
+5. If needed, dump full profiles: `kill -SIGUSR2 <pid>`
+6. Analyze with pprof to identify the bottleneck
+
+Common issues revealed by goroutine dumps:
+- External `task` command hanging (stuck in syscall)
+- Waiting for terminal input (blocked on I/O)
+- External editor not responding
+
+**Note:** Signal handlers are not available on Windows. Consider using `GODEBUG` environment variables or running under a debugger instead.