add README with dotfiles documentation

Nightshift-Task: docs-backfill
Nightshift-Ref: https://github.com/marcus/nightshift

README.md

@@ -1,92 +1,132 @@
 # dotfiles
 
-Personal dotfiles managed as a bare Git repository. The repo lives at `~/.dotgit/` with the work tree set to `$HOME`, so tracked files sit at their real paths without symlinks.
+Bare-git managed dotfiles for zsh/vim/tmux on Linux and macOS.
 
-## Bootstrap
+## How it works
+
+This repo uses a **bare git repository** at `~/.dotgit` with the work tree set to `$HOME`. This avoids symlinks and lets dotfiles live at their native paths.
+
+The alias that drives everything:
 
 ```bash
-# Clone bare repo
+alias .g='git --git-dir=$HOME/.dotgit/ --work-tree=$HOME'
-git clone --bare https://gitea.abra.me/svxf/dotfiles.git "$HOME/.dotgit"
-
-# Checkout files into $HOME
-git --git-dir="$HOME/.dotgit/" --work-tree="$HOME" checkout
-
-# Hide untracked files from status noise
-git --git-dir="$HOME/.dotgit/" --work-tree="$HOME" config status.showUntrackedFiles no
 ```
 
-After checkout, restart your shell. Zinit and Starship will self-install on first launch.
+`.g status`, `.g add`, `.g diff`, `.g commit`, `.g push` — same as git, just scoped to the dotfiles repo. Untracked files are hidden by default (`showUntrackedFiles = no` in config).
 
-## Usage
+## Bootstrap on a new machine
-
-The `.g` alias wraps `git --git-dir=$HOME/.dotgit/ --work-tree=$HOME`, so everyday operations look like:
 
 ```bash
-.g status
+git clone --bare https://gitea.abra.me/svxf/dotfiles.git $HOME/.dotgit
-.g add ~/.vimrc
+alias .g='git --git-dir=$HOME/.dotgit/ --work-tree=$HOME'
-.g commit -m "update vimrc"
+.g checkout
-.g push
+.g config status.showUntrackedFiles no
 ```
 
-A background job in `.zshrc` auto-pulls once per day (`~/.cache/.dotfiles-pull` marker).
+If checkout conflicts with existing files, back them up first:
 
-## File summaries
+```bash
+.g checkout 2>&1 | grep "^\t" | xargs -I{} mv {} {}.bak
+.g checkout
+```
 
-### .zshrc
+On next shell start, zinit will bootstrap itself and install all plugins automatically.
 
-Shell configuration and the main entry point.
+## Tracked files
 
-- **Plugin manager**: Zinit (auto-installed from `zdharma-continuum/zinit`). Plugins: `zsh-autosuggestions`, `zsh-syntax-highlighting`, `zsh-completions`, `zsh-history-substring-search`.
+| File | What it does |
-- **History**: 100k entries, shared across sessions, deduped, extended format.
+|---|---|
-- **Completions**: Case-insensitive matching, menu selection.
+| `.zshrc` | Shell config — plugins, aliases, functions, keybindings, PATH |
-- **Keybindings**: Emacs mode. Ctrl+Q push-line, Alt+E / Ctrl+X,E edit-command-line, Up/Down prefix search.
+| `.vimrc` | Vim config — space-leader, persistent undo, arrow keys disabled |
-- **Prompt**: Starship (installed via Zinit from GitHub releases).
+| `.tmux.conf` | tmux config — mouse, green accent, fzf window switcher, auto-rename |
-- **fzf integration**: Keybindings and completion sourced when available; `--height 40% --reverse` default opts.
+| `.starship.toml` | Prompt — two-line, git status, docker indicators, command duration |
-- **PATH**: `/projects/bin`, `~/.local/bin`, `~/.cargo/bin`, `/usr/local/go/bin`, `~/go/bin`, `/opt/homebrew/bin`.
+| `.gitignore_global` | Global ignores — `*~`, `.DS_Store`, `__pycache__`, `.idea`, `.ipynb_checkpoints` |
-- **Aliases**:
-  - `.g` — bare-repo git wrapper
-  - `tmuxr` / `tmuxn` / `tmuxa` — tmux attach-or-create helpers
-  - `,dcdu` / `,dcdd` / `,dcdl` — docker-compose dev-profile shortcuts
-  - `dcu` / `dcd` / `dcl` — generic docker-compose shortcuts
-  - `c` / `,cd` — Claude CLI / Claude with sandbox skip
-  - `LATEST` — global alias expanding to most-recently-modified file
-- **Functions**:
-  - `y` — yazi file manager wrapper that `cd`s to the selected directory on exit
-  - `pj` — fuzzy project switcher (searches `/projects` and `~/projects` via fzf)
-  - `clip` — pipe stdin to system clipboard via OSC 52 escape sequence
-  - `mkcd` — mkdir + cd in one step
-  - `cdtmp` — create and cd into a timestamped temp directory under `~/tmp/`
-- **Extras**: `~/.zshrc-extra` sourced at end for machine-local overrides (not tracked).
 
-### .tmux.conf
+## Key features
 
-- **Mouse** enabled, clipboard passthrough on.
+### Zinit plugin stack (`.zshrc`)
-- **Splits** preserve current path.
-- **Navigation**: Shift+Arrow switches windows (no wrap), Alt+Arrow switches panes, PgUp/PgDn swaps window order.
-- **Window naming**: Auto-rename to `command@dir`.
-- **Fuzzy switcher**: `prefix + f` opens fzf popup to pick a window.
-- **Status bar**: Dark theme (colour235 bg), green session indicator, powerline-style window tabs with alternating shading, no right-side status.
-- **Pane borders**: Green active, grey inactive.
-- **Base index**: 1 (not 0).
 
-### .vimrc
+- **zsh-autosuggestions** — inline fish-style suggestions
+- **zsh-syntax-highlighting** — live command coloring
+- **zsh-completions** — extra completion definitions
+- **zsh-history-substring-search** — up/down searches from prefix
+- **starship** — installed via zinit from GitHub releases
 
-- `jk` mapped to Escape, Space as leader.
+### Async dotfiles pull
-- 4-space soft tabs, syntax on, cursor line highlighted.
-- Persistent undo (`~/.vim/undo/`), swap and backup dirs under `~/.vim/`.
-- Smart case search, incremental + highlighted.
-- Arrow keys disabled in normal mode (forces hjkl).
-- Mouse support enabled, 8-line scroll margin.
 
-### .starship.toml
+On shell start, a background job pulls `--ff-only` from origin once per day (marker at `~/.cache/.dotfiles-pull`). Silent, non-blocking.
 
-Two-line prompt:
+### Starship prompt (`.starship.toml`)
 
-- **Line 1** (left → right): Docker container indicator (if inside), docker-compose service summary (running/stopped counts), git branch + status, fill, directory.
+Two-line layout:
-- **Line 2**: `➤` character (green on success, red on error).
+- **Line 1**: docker container indicator → docker-compose status → git branch/status → (fill) → directory
-- **Right prompt**: Command duration (>5s), `user@host`, time.
+- **Line 2**: `➤` character (green=ok, red=error)
-- Docker-compose status uses `docker compose ps --format json | jq` to show `▲N/▼N` counts.
+- **Right**: command duration (>5s) → user@host → time
 
-### .gitignore_global
+Custom modules detect `/.dockerenv` for container awareness and parse `docker compose ps` for service status.
 
-Ignores: `*~`, `.DS_Store`, `.idea`, `.ipynb_checkpoints`, `__pycache__`.
+### fzf integration (`.zshrc`)
+
+Sources fzf keybindings and completion when available. Default opts: `--height 40% --reverse`.
+
+### Project switcher — `pj` (`.zshrc`)
+
+Fuzzy-finds directories under `/projects` or `~/projects` using fzf. `pj foo` pre-fills the query.
+
+### Yazi wrapper — `y` (`.zshrc`)
+
+Wraps the yazi file manager so the shell `cd`s to wherever you navigated on exit.
+
+### Docker compose aliases (`.zshrc`)
+
+| Alias | Expands to |
+|---|---|
+| `,dcdu` | `docker compose --profile dev up service_dev --force-recreate --detach` |
+| `,dcdd` | `docker compose --profile dev down --remove-orphans` |
+| `,dcdl` | `docker compose --profile dev logs -f service_dev` |
+| `dcu` | `docker compose up --force-recreate --detach` |
+| `dcd` | `docker compose down --remove-orphans` |
+| `dcl` | `docker compose logs -f` |
+
+### Tmux aliases (`.zshrc`)
+
+| Alias | What it does |
+|---|---|
+| `tmuxr` | Attach-or-create session named "auto" |
+| `tmuxn` | Same + opens a new window |
+| `tmuxa NAME` | Attach-or-create a named session |
+
+### Tmux keybindings (`.tmux.conf`)
+
+- **Shift+Left/Right** — switch windows (no wrap)
+- **PgUp/PgDn** — swap window position left/right
+- **prefix+f** — fzf fuzzy window switcher
+- **prefix+R** — rename window
+- Splits retain current path. 1-indexed windows, auto-rename shows `command@directory`.
+
+### Vim (`.vimrc`)
+
+Space as leader. `jk` exits insert mode. Persistent undo in `~/.vim/undo/`. Arrow keys disabled (hjkl only). Mouse enabled. Smart case search. 8-line scroll margin.
+
+### Utility functions (`.zshrc`)
+
+| Function | Purpose |
+|---|---|
+| `clip` | Pipe stdin to system clipboard via OSC 52 (works over SSH/tmux) |
+| `mkcd DIR` | mkdir + cd in one step |
+| `cdtmp [label]` | Create and cd into a timestamped temp dir under `~/tmp/` |
+
+### Other aliases (`.zshrc`)
+
+- `c` → `claude`
+- `,cd` → `claude --dangerously-skip-permissions` (with sandbox flag)
+- `zshreload` → `exec zsh`
+- `LATEST` — global alias expanding to `*(om[1])` (most recently modified file)
+
+### Shell options (`.zshrc`)
+
+Extended history (100k lines, shared, deduped). Case-insensitive globbing. Auto-pushd on cd. No flow control (Ctrl-S disabled). Emacs keybindings with Ctrl+X,E / Alt+E for `$EDITOR`.
+
+### Machine-local overrides
+
+`~/.zshrc-extra` is sourced at the end if it exists — for per-machine config that doesn't belong in version control.