From 1babd404f9f2933b066959dc4fe340c468aca6ca Mon Sep 17 00:00:00 2001
From: mr-forust <vzlomdsisma@gmail.com>
Date: Sun, 5 Jul 2026 02:33:21 +0200
Subject: [PATCH] docs: document timer utilities

---
 AGENTS.md |  4 +++-
 README.md | 39 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 42 insertions(+), 1 deletion(-)

diff --git a/AGENTS.md b/AGENTS.md
index 49e31db..cce889d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -46,10 +46,12 @@ Use a temporary config path so local tests do not mutate the user's real config:
 ```bash
 tmpdir="$(mktemp -d)"
 cargo run -- --config "$tmpdir/config.yaml" init
+cargo run -- --config "$tmpdir/config.yaml" validate
+cargo run -- --config "$tmpdir/config.yaml" status
 cargo run -- --config "$tmpdir/config.yaml" preview
 ```
 
-For `run` smoke tests, disable actions first so the command does not call `playerctl`, `systemctl`, `pkill`, workspace tools, or custom shell commands.
+For `run` smoke tests, pass `--no-actions` or disable actions first so the command does not call `playerctl`, `systemctl`, `pkill`, workspace tools, or custom shell commands.
 
 ## Versioning
 
diff --git a/README.md b/README.md
index 21bbc9d..29a8414 100644
--- a/README.md
+++ b/README.md
@@ -60,6 +60,24 @@ Preview commands that will run after the countdown:
 gosleep-timer preview
 ```
 
+Show the current config, enabled actions, and dangerous-action markers:
+
+```bash
+gosleep-timer status
+```
+
+Validate the config without starting the timer:
+
+```bash
+gosleep-timer validate
+```
+
+Open the config in `$VISUAL`, `$EDITOR`, or `vi`:
+
+```bash
+gosleep-timer edit
+```
+
 Run the saved timer config:
 
 ```bash
@@ -73,6 +91,20 @@ gosleep-timer run 45m
 gosleep-timer run 1h30m
 ```
 
+Run the countdown without executing post-timer actions:
+
+```bash
+gosleep-timer run --dry-run 10s
+gosleep-timer run --no-actions 10s
+```
+
+Inspect recorded sessions and aggregate stats:
+
+```bash
+gosleep-timer history
+gosleep-timer stats
+```
+
 Use a custom config path:
 
 ```bash
@@ -89,6 +121,7 @@ gosleep-timer --config ./config.yaml preview
 | `Enter` while editing | Apply edit |
 | `Esc` while editing | Cancel edit |
 | `r` | Start/restart timer |
+| `p` | Pause/resume running timer |
 | `x` | Stop timer |
 | `s` | Save config |
 | `q` / `Esc` | Quit |
@@ -154,6 +187,12 @@ Other actions use common Linux desktop tools:
 - `systemctl`
 
 Install only the tools needed for the actions you enable.
+Dangerous actions such as `pkill`, power actions, and common destructive custom commands are highlighted in red in the TUI preview.
+
+## History
+
+Completed timer sessions are appended to `history.yaml` next to the active config file.
+If no poweroff or reboot action is configured, CLI `run` asks for wake confirmation after the timer finishes and records the elapsed sleep time.
 
 ## Development