diff --git a/README.md b/README.md
index 0f43b86..9457d87 100644
--- a/README.md
+++ b/README.md
@@ -296,6 +296,32 @@ picker · `SUPER+SHIFT+T` next wallpaper · `SUPER+X` power menu ·
 clipboard history · `SUPER+Q`
 close · `SUPER+1..9` workspaces · `Print` region screenshot.
 
+Shell aliases (zsh, gated on `nomarchy.shell.enable`) — `alias` lists them
+all; the curated set:
+
+```sh
+# navigation
+..   ...   ....                 # cd up 1 / 2 / 3 levels
+
+# git
+g    gst                        # git · git status -sb
+ga   gaa                        # git add · git add -A
+gc   gcm                        # git commit · git commit -m
+gco  gsw   gb                   # checkout · switch · branch
+gd   gds                        # diff · diff --staged
+gl   glg                        # log graph (last 20 · all branches)
+gp   gpl   gf                   # push · pull · fetch --all --prune
+
+# nix  (system/home rebuilds keep their full sys-update / home-update names)
+ns   nr                         # nix shell · nix run   (e.g. ns nixpkgs#ripgrep)
+nfu  nfc                        # nix flake update · check
+nsearch    ngc                  # nix search nixpkgs · nix-collect-garbage -d
+
+# misc
+path                            # print $PATH, one entry per line
+reload                          # exec zsh (reload the shell)
+```
+
 ## 6. Extending
 
 - **New theme:** drop a JSON into `themes/` (schema = any existing preset),
diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md
index 19f954d..a3e04b7 100644
--- a/docs/ROADMAP.md
+++ b/docs/ROADMAP.md
@@ -120,7 +120,8 @@ how to override it. Items marked ✓ are shipped.
   `nsearch`, `ngc`), plus `path` and `reload`. Scope decision: short where it
   helps but **never shadow a real binary** (same rule as rg/fd — the git block
   deliberately avoids `gs`/ghostscript); system/home rebuilds keep their full
-  `sys-update`/`home-update` names rather than getting cryptic aliases.
+  `sys-update`/`home-update` names rather than getting cryptic aliases. The set
+  is documented in README §5 (Day-to-day), and `alias` lists them in-shell.
 - **Theme-switch feedback:** ✓ the "rebuilding…" notification is now
   persistent (timeout 0) and replaced in place by "applied ✓" / failure
   via a synchronous tag, so a multi-minute switch never reads as a failed