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
+3. Implement a `help` subcommand: check for `help` as `_dot_<name>`'s first
-   `fishtape ~/.config/dot/tests/dot.fish` until it passes.
+   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

.config/fish/functions/dot.fish

@@ -98,17 +98,19 @@ end
 # named after that function; a shared helper would go undefined if `dot help`
 # ran in a completion context before `dot` itself had ever been sourced.
 function __dot_help
-    echo "dot: manage dotfiles via a bare repo checked out over \$HOME"
+    echo "dot: manage dotfiles via a bare repo checked out over \$HOME
-    echo
+
-    echo "Commands:"
+Commands:
-    echo "  init    bootstrap the dotfiles repo on a new machine"
+  init    bootstrap the dotfiles repo on a new machine
-    echo "  help    show this message"
+  help    show this message"
 
     for f in $HOME/.config/dot/commands/*.fish
         test -e $f; or continue
         echo "  "(path basename $f | path change-extension '')
     end
 
-    echo
+    echo "
-    echo "Any other command is passed through to git (dot status, dot add, dot commit, dot push, ...)."
+Run 'dot <command> help' for flags on a specific command.
+
+Any other command is passed through to git (dot status, dot add, dot commit, dot push, ...)."
 end

.gitea/README.md

@@ -15,10 +15,11 @@ fish -c 'dot init'
 ## Commands
 
 | Command                 | Description                                                                              |
-| -------------- | ----------------------------------------------------------------------------------------- |
+| ----------------------- | ----------------------------------------------------------------------------------------- |
 | `dot help`              | Lists available commands.                                                                |
 | `dot init`              | Bootstraps the dotfiles repo on a new machine.                                           |
-| `dot <custom>` | Any file under `~/.config/dot/commands/` (currently `install`); run `dot help` for the live list. |
+| `dot install <pkgs>`    | Installs the given pacman packages and appends them to the tracked list (`~/.config/dot/packages/pacman`). |
+| `dot install --restore` | Reinstalls every package from the tracked list.                                          |
 | `dot <git>`             | Everything else is passed to `git`.                                                      |
 
 See [CLAUDE.md](../.config/dot/CLAUDE.md) for the `dot` tool's internal