docs: convention for usage documentation.

.config/dot/CLAUDE.md

@@ -24,6 +24,12 @@ deliberately hides all of it.
 any wildcard add — that would try to stage the entire home directory (caches,
 secrets, everything).
 
+**Stage automatically after changes.** Once a tracked file is edited, run
+`dot add <specific-path>` for it right away rather than waiting to be asked —
+one explicit path per changed file, still never a wildcard. This does not
+extend to `dot commit` or `dot push`, which still require an explicit
+request.
+
 ## The dot CLI
 
 ### Architecture
@@ -72,8 +78,21 @@ of `dot` itself.
    `~/.config/fish/completions/dot.fish` and `__dot_help` both discover new
    command files by globbing that directory, and `--wraps=git` still covers
    raw git subcommands.
-3. Add a case to `~/.config/dot/tests/dot.fish` covering it and run
-   `fishtape ~/.config/dot/tests/dot.fish` until it passes.
+3. Implement a `help` subcommand: check for `help` as `_dot_<name>`'s first
+   positional argument before `argparse`, and call a `_dot_<name>_usage`
+   function that prints usage and every flag. If `_dot_<name>` itself
+   dispatches to nested subcommands, apply this same check-then-dispatch
+   pattern at that level too — there's no central `--help` handling in
+   `dot.fish` to lean on; each level is responsible for its own.
+   `_dot_<name>_usage` should print its text as a single multi-line
+   `echo "..."` string (fish preserves literal newlines inside double
+   quotes) rather than one `echo` per line.
+4. Add a row to `~/.gitea/README.md`'s command table for it — one row per
+   distinct use case, with paths written relative to `$HOME`
+   (`~/.config/dot/...`), not relative to the README's own location.
+5. Add a case to `~/.config/dot/tests/dot.fish` covering it, including its
+   `help` output, and run `fishtape ~/.config/dot/tests/dot.fish` until it
+   passes.
 
 ### Testing
 

.config/dot/commands/install.fish

@@ -1,4 +1,15 @@
+function _dot_install_usage
+    echo "usage: dot install [--restore] [--no-sync] [package ...]
+  --restore   reinstall every package from the tracked list
+  --no-sync   skip 'pacman -Sy' before installing"
+end
+
 function _dot_install
+    if test "$argv[1]" = help
+        _dot_install_usage
+        return 0
+    end
+
     argparse 'restore' 'no-sync' -- $argv
     or return 1
 

.config/dot/tests/dot.fish

@@ -83,6 +83,7 @@ set -l help_status $status
 @test "dot help succeeds" $help_status -eq 0
 @test "dot help lists init" (string match -q '*init*' -- $help_output; echo $status) -eq 0
 @test "dot help mentions git passthrough" (string match -q '*git*' -- $help_output; echo $status) -eq 0
+@test "dot help hints at per-command help" (string match -q "*dot <command> help*" -- $help_output; echo $status) -eq 0
 
 mkdir -p $HOME/.config/dot/commands
 echo "function _dot_mark
@@ -228,3 +229,19 @@ set -l pacman_called_conflict (test -s $PACMAN_LOG; and echo yes; or echo no)
 
 @test "--restore combined with package names fails" $restore_conflict_status -ne 0
 @test "--restore combined with package names never calls pacman" $pacman_called_conflict = no
+
+# --- help prints usage instead of touching pacman ---
+set -gx HOME (mktemp -d)
+dot init --url $remote >/dev/null 2>&1
+mkdir -p $HOME/.config/dot/commands
+cp $commands_dir/install.fish $HOME/.config/dot/commands/install.fish
+set -gx PACMAN_LOG (mktemp)
+
+set -l help_output (dot install help)
+set -l help_status $status
+set -l pacman_called_help (test -s $PACMAN_LOG; and echo yes; or echo no)
+
+@test "dot install help succeeds" $help_status -eq 0
+@test "dot install help mentions --restore" (string match -q '*--restore*' -- $help_output; echo $status) -eq 0
+@test "dot install help mentions --no-sync" (string match -q '*--no-sync*' -- $help_output; echo $status) -eq 0
+@test "dot install help never calls pacman" $pacman_called_help = no