From f0c477104eae3003a69f0db1ed4b170324d86115 Mon Sep 17 00:00:00 2001
From: svxf <svxf@users.noreply.gitea.abra.me>
Date: Tue, 3 Mar 2026 22:16:11 +0000
Subject: [PATCH] Add README documenting dotfiles setup and per-file summaries

Nightshift-Task: docs-backfill
Nightshift-Ref: https://github.com/marcus/nightshift
---
 README.md | 92 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 92 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..931633e
--- /dev/null
+++ b/README.md
@@ -0,0 +1,92 @@
+# 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.
+
+## Bootstrap
+
+```bash
+# Clone bare repo
+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.
+
+## Usage
+
+The `.g` alias wraps `git --git-dir=$HOME/.dotgit/ --work-tree=$HOME`, so everyday operations look like:
+
+```bash
+.g status
+.g add ~/.vimrc
+.g commit -m "update vimrc"
+.g push
+```
+
+A background job in `.zshrc` auto-pulls once per day (`~/.cache/.dotfiles-pull` marker).
+
+## File summaries
+
+### .zshrc
+
+Shell configuration and the main entry point.
+
+- **Plugin manager**: Zinit (auto-installed from `zdharma-continuum/zinit`). Plugins: `zsh-autosuggestions`, `zsh-syntax-highlighting`, `zsh-completions`, `zsh-history-substring-search`.
+- **History**: 100k entries, shared across sessions, deduped, extended format.
+- **Completions**: Case-insensitive matching, menu selection.
+- **Keybindings**: Emacs mode. Ctrl+Q push-line, Alt+E / Ctrl+X,E edit-command-line, Up/Down prefix search.
+- **Prompt**: Starship (installed via Zinit from GitHub releases).
+- **fzf integration**: Keybindings and completion sourced when available; `--height 40% --reverse` default opts.
+- **PATH**: `/projects/bin`, `~/.local/bin`, `~/.cargo/bin`, `/usr/local/go/bin`, `~/go/bin`, `/opt/homebrew/bin`.
+- **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
+
+- **Mouse** enabled, clipboard passthrough on.
+- **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
+
+- `jk` mapped to Escape, Space as leader.
+- 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
+
+Two-line prompt:
+
+- **Line 1** (left → right): Docker container indicator (if inside), docker-compose service summary (running/stopped counts), git branch + status, fill, directory.
+- **Line 2**: `➤` character (green on success, red on error).
+- **Right prompt**: Command duration (>5s), `user@host`, time.
+- Docker-compose status uses `docker compose ps --format json | jq` to show `▲N/▼N` counts.
+
+### .gitignore_global
+
+Ignores: `*~`, `.DS_Store`, `.idea`, `.ipynb_checkpoints`, `__pycache__`.
-- 
2.49.1