docs: document man page install and compact --help

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2 files changed, 23 insertions, 0 deletions

diff --git a/CLAUDE.md b/CLAUDE.md
index 5c62bf2..4a011ab 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -169,4 +169,12 @@ When adding new features, add a corresponding test case to `tests/mkhint_test.sh
 ```bash
 sudo cp mkhint /usr/local/bin/mkhint
 sudo cp mkhint.bash-completion /etc/bash-completion.d/mkhint
+sudo cp mkhint.1.gz /usr/local/man/man1/mkhint.1.gz
 ```
+
+Man page source is `mkhint.1.md`; the committed `mkhint.1.gz` is rebuilt with
+`pandoc mkhint.1.md -s -t man -o mkhint.1 && gzip -9 -n -f mkhint.1`. Option
+names are `\--`-escaped in the source so pandoc's man output renders the
+double-dash flags. `--help` is a compact summary that points at `man mkhint`;
+the full reference (usage examples, configuration, exit codes) lives in the
+man page.
diff --git a/README.md b/README.md
index e055848..919618e 100644
--- a/README.md
+++ b/README.md
@@ -16,6 +16,21 @@ sudo cp mkhint /usr/local/bin/mkhint
 sudo cp mkhint.bash-completion /etc/bash-completion.d/mkhint
 ```
 
+### Man Page
+
+```bash
+sudo cp mkhint.1.gz /usr/local/man/man1/mkhint.1.gz
+```
+
+The man page is pre-built and committed. To regenerate it from source (requires
+pandoc):
+
+```bash
+pandoc mkhint.1.md -s -t man -o mkhint.1 && gzip -9 -n -f mkhint.1
+```
+
+`mkhint --help` is a compact summary; the man page holds the full reference.
+
 ### Dependencies
 
 - `wget` — for downloading archives and calculating checksums