aspauldingcode · aspauldingcode · May 28, 2026 · May 10, 2026 · May 10, 2026 · May 10, 2026
diff --git a/README.md b/README.md
@@ -9,11 +9,11 @@ Following the [dendritic pattern](https://github.com/mightyiam/dendritic), this
 | Platform | Path |
 |---|---|
 | **NixOS** | `/etc/nixos/` |
-| **macOS (nix-darwin)** | `/etc/nix-darwin/` |
+| **macOS (nix-darwin)** | `/etc/nix-darwin/.dotfiles/` |
 
 ```bash
 # macOS
-sudo git clone git@github.com:aspauldingcode/.dotfiles.git /etc/nix-darwin
+sudo git clone git@github.com:aspauldingcode/.dotfiles.git /etc/nix-darwin/.dotfiles
 
 # NixOS
 sudo git clone git@github.com:aspauldingcode/.dotfiles.git /etc/nixos
@@ -23,7 +23,7 @@ sudo git clone git@github.com:aspauldingcode/.dotfiles.git /etc/nixos
 
 You can bootstrap this dotfiles configuration directly on a fresh macOS machine with Nix installed by running a single command.
 
-The install script will automatically clone the repository to `/etc/nix-darwin` (or `/etc/nixos` on NixOS) and apply the system configuration. We use the tarball link so it works even if your brand-new Mac doesn't have `git` installed yet:
+The install script will automatically clone the repository to `/etc/nix-darwin/.dotfiles` (or `/etc/nixos` on NixOS) and apply the system configuration. We use the tarball link so it works even if your brand-new Mac doesn't have `git` installed yet:
 
 ```bash
 nix run github:aspauldingcode/.dotfiles#install
@@ -37,21 +37,26 @@ Once the system is installed, you can apply changes to your configuration using
 
 ```bash
 # Navigate to your config
-cd /etc/nix-darwin   # macOS
+cd /etc/nix-darwin/.dotfiles   # macOS
 cd /etc/nixos        # NixOS
 
 # Standard rebuild (uses the NH_FLAKE variable we configured)
 nh darwin switch
 
 # Manual rebuild (if variable is not yet active or you are on a new host)
-nh darwin switch /etc/nix-darwin -H mba
+nh darwin switch /etc/nix-darwin/.dotfiles -H mba
 nh os switch /etc/nixos -H my-nixos-host
 ```
 
 ### Pro Tips for `nh`
 - Use **`--ask`** to see a diff of what will change before confirming.
 - Use **`--update`** to update all your flake inputs (packages) to their latest versions.
-- The `NH_FLAKE` variable is set to `/etc/nix-darwin#mba` (macOS) or `/etc/nixos` (NixOS), so `nh` always knows which host to build by default.
+- The `NH_FLAKE` variable is set to `/etc/nix-darwin/.dotfiles#mba` (macOS) or `/etc/nixos` (NixOS), so `nh` always knows which host to build by default.
+
+## Documentation
+
+- **[Zsh Plugins & Shell Extensions](docs/zsh-plugins.md)** — Full reference of all curated zsh plugins, CLI tools, and Nix-specific integrations.
+- **[Tmux Master Guide](docs/tmux.md)** — Learn how to use your optimized terminal multiplexer with interactive hints.
 
 ## Uninstallation
 

diff --git a/build.log b/build.log
diff --git a/docs/tmux.md b/docs/tmux.md
@@ -0,0 +1,69 @@
+# Tmux Master Guide
+
+Welcome to your optimized **Tmux** environment. This setup is designed to be ergonomic, persistent, and beginner-friendly with interactive hints.
+
+## ⌨️ The Prefix: `Ctrl-a`
+The default prefix has been changed from `Ctrl-b` to **`Ctrl-a`** for better ergonomics.
+> In this guide, `prefix` refers to pressing `Ctrl-a` then releasing before the next key.
+
+---
+
+## 🆘 How to learn keybinds (Interactive)
+If you ever forget a keybind, just press:
+### **`prefix + ?`**
+This opens an interactive **Which-Key** menu where you can search and execute any tmux command. This is your best friend for learning!
+
+---
+
+## 🏗️ Managing Panes & Windows
+
+| Action | Keybind |
+|---|---|
+| **Split Vertical** | `prefix + |` |
+| **Split Horizontal** | `prefix + -` |
+| **Kill Pane** | `prefix + x` |
+| **Create Window** | `prefix + c` |
+| **Next Window** | `prefix + n` |
+| **Previous Window** | `prefix + p` |
+| **Zoom Pane** | `prefix + z` |
+
+---
+
+## 🖱️ Mouse Support
+Mouse mode is **ON**. You can:
+- Click to select panes
+- Drag to resize panes
+- Scroll to enter copy-mode
+- Use your mouse to select text
+
+---
+
+## 🏃 Navigation (Vim-Style)
+You can navigate between Tmux panes and Neovim splits seamlessly using:
+- `Ctrl-h` (Left)
+- `Ctrl-j` (Down)
+- `Ctrl-k` (Up)
+- `Ctrl-l` (Right)
+
+---
+
+## 📋 Copy & Paste (Vi-Mode)
+Enter copy mode with `prefix + [`:
+1. Navigate with `h`, `j`, `k`, `l`
+2. Start selection with `v`
+3. Copy with `y` (automatically syncs to system clipboard)
+4. Paste with `prefix + ]`
+
+---
+
+## 💾 Session Persistence
+Your sessions are automatically saved and restored:
+- **Save manually:** `prefix + Ctrl-s`
+- **Restore manually:** `prefix + Ctrl-r`
+- **Continuum:** Automatically saves every 15 minutes and restores on startup.
+
+---
+
+## 🔗 URLs
+Want to open a link in your terminal?
+Press **`prefix + u`** to fuzzy-search all URLs in the current pane and open them in your browser.
diff --git a/docs/zsh-plugins.md b/docs/zsh-plugins.md
@@ -0,0 +1,197 @@
+# Zsh Plugins & Shell Extensions
+
+Curated set of zsh plugins and CLI tools integrated into the Dendritic Nix configuration. All plugins are installed declaratively via Nix (home-manager modules or nixpkgs) — no external plugin managers required.
+
+> **Config location:** [`modules/shell.nix`](../modules/shell.nix)
+
+---
+
+## Core Productivity & UX
+
+### zsh-autosuggestions *(pre-existing)*
+Fish-like inline autosuggestions as you type, drawn from command history.
+- Suggestions appear in gray — press `→` or `End` to accept.
+- **Package:** `programs.zsh.autosuggestion.enable`
+
+### zsh-syntax-highlighting *(pre-existing)*
+Real-time syntax highlighting in the terminal. Valid commands turn green, errors turn red.
+- **Package:** `programs.zsh.syntaxHighlighting.enable`
+
+### zsh-completions *(pre-existing)*
+Additional completion definitions for common tools not covered by default zsh.
+- **Package:** `pkgs.zsh-completions`
+
+### zsh-history-substring-search
+Search history by **substring** rather than prefix. Much more powerful than default `up-arrow` behavior.
+- **Keybindings:**
+  - `↑` / `↓` — search history for commands containing the current input
+  - Type `git co`, press `↑` → finds `git commit`, `git checkout`, etc.
+- **Package:** `programs.zsh.historySubstringSearch.enable`
+
+### zsh-you-should-use
+Reminds you when an alias exists for a command you just typed manually.
+```
+$ git status
+Found existing alias for "git status". You should use: "gst"
+```
+- Trains muscle memory over time. Zero friction — just prints a reminder.
+- **Package:** `pkgs.zsh-you-should-use` (sourced via `initContent`)
+
+### sudo (ESC ESC)
+Double-tap `Escape` to prepend `sudo` to the current or last command. Simple, indispensable.
+- **Implementation:** Custom zsh widget in `initContent`
+
+### colored-man-pages
+Adds color to `man` pages using `LESS_TERMCAP` environment variables. Zero performance cost.
+- **Implementation:** Environment variables in `initContent`
+
+### extract
+Smart archive extraction — `extract foo.tar.gz` handles `.tar.gz`, `.zip`, `.7z`, `.rar`, `.bz2`, `.xz`, and more.
+```bash
+extract archive.tar.xz    # Just works, no flags to remember
+```
+- **Implementation:** Shell function in `initContent`
+
+---
+
+## Fuzzy Finding & Navigation
+
+### fzf
+General-purpose command-line fuzzy finder. Powers `Ctrl+R` history search, file search, and more.
+- **Keybindings:**
+  - `Ctrl+R` — fuzzy search command history
+  - `Ctrl+T` — fuzzy find files in current directory
+  - `Alt+C` — fuzzy `cd` into subdirectories
+- **Package:** `programs.fzf.enable` with `enableZshIntegration`
+
+### fzf-tab
+Replaces zsh's default tab-completion menu with fzf. Every `<Tab>` becomes a fuzzy search.
+```bash
+cd /etc/<Tab>        # Fuzzy-filter all dirs under /etc
+git checkout <Tab>   # Fuzzy-filter branches
+kill <Tab>           # Fuzzy-filter running processes
+```
+- **Package:** `pkgs.zsh-fzf-tab` (sourced via `initContent`)
+
+### zoxide
+Smarter `cd` that learns your most-used directories. Replaces `cd` with `z`.
+```bash
+z darwin       # Jumps to /etc/nix-darwin (if visited before)
+z mod shell    # Jumps to /etc/nix-darwin/modules/shell.nix dir
+zi             # Interactive fuzzy directory picker
+```
+- **Package:** `programs.zoxide.enable` with `enableZshIntegration`
+
+---
+
+## Git Enhancements
+
+### forgit
+Interactive git wrapper powered by fzf. Makes git operations browsable and visual.
+```bash
+forgit::log     # or gl  — interactive git log with diff preview
+forgit::diff    # or gd  — interactive diff viewer
+forgit::add     # or ga  — interactive staging
+forgit::stash   # interactive stash browser
+```
+- **Package:** `pkgs.zsh-forgit` (sourced via `initContent`)
+
+---
+
+## Vim Integration
+
+### zsh-vi-mode
+Full vim-mode editing for the zsh command line. Consistent with Neovim muscle memory.
+- **Modes:** Normal, Insert, Visual, Replace — just like Vim.
+- `Escape` enters Normal mode, `i`/`a` return to Insert.
+- Visual block selection, text objects (`ciw`, `da"`, etc.) all work.
+- Cursor shape changes to indicate mode (beam = insert, block = normal).
+- **Package:** `pkgs.zsh-vi-mode` (sourced via `initContent`)
+
+---
+
+## Developer Experience (CLI Tools)
+
+### bat
+`cat` replacement with syntax highlighting, line numbers, and git integration.
+```bash
+bat shell.nix            # Syntax-highlighted file viewing
+bat --diff shell.nix     # Shows git diff inline
+```
+- Aliased as `cat` → `bat` for seamless adoption.
+- **Package:** `programs.bat.enable`
+
+---
+
+## Nix-Specific Integrations
+
+### direnv + nix-direnv
+Automatically loads/unloads `nix develop` shell environments when you `cd` into a project with a `flake.nix`.
+```bash
+cd ~/myproject/    # devShell activates automatically
+cd ~               # devShell deactivates
+```
+- Uses cached evaluations via `nix-direnv` — fast re-entry on subsequent visits.
+- Requires a `.envrc` file in the project root containing `use flake`.
+- **Package:** `programs.direnv.enable` + `programs.direnv.nix-direnv.enable`
+
+### any-nix-shell
+Keeps you in **zsh** when entering `nix-shell` or `nix develop`. Without this, Nix drops you into bash.
+- **Package:** `pkgs.any-nix-shell` (sourced via `initContent`)
+
+### comma (`,`)
+Run any program from nixpkgs **without installing it**.
+```bash
+, cowsay "hello"     # Downloads, runs cowsay, doesn't persist
+, httpie GET api.io  # One-off HTTP request
+```
+- Powered by `nix-index` — needs an initial index build (runs automatically).
+- **Package:** `pkgs.comma`
+
+### nix-index + command-not-found
+When you type a command that isn't installed, suggests which Nix package provides it.
+```
+$ rg
+nix-index: rg is provided by nixpkgs#ripgrep
+```
+- **Package:** `programs.nix-index.enable` with `enableZshIntegration`
+
+### nix-zsh-completions
+Tab completions for all `nix` CLI subcommands (`nix build`, `nix develop`, `nix flake show`, etc.).
+- **Package:** `pkgs.nix-zsh-completions`
+
+### manix
+Fast CLI documentation search for NixOS / home-manager options.
+```bash
+manix "programs.zsh"           # Search all option docs
+manix "services.openssh"       # Find SSH service options
+```
+- **Package:** `pkgs.manix`
+
+---
+
+## Prompt
+
+### Starship *(pre-existing)*
+Cross-shell prompt with git status, nix-shell indicator, language versions, and more. Already configured with performance optimizations.
+- **Package:** `programs.starship.enable`
+
+---
+
+## File Management
+
+### Yazi *(pre-existing)*
+Terminal file manager with image preview support. Invoked via `y` wrapper.
+- **Package:** `programs.yazi.enable`
+
+---
+
+## System Monitoring
+
+### btop *(pre-existing)*
+Resource monitor themed by Stylix.
+- **Package:** `programs.btop.enable`
+
+### htop *(pre-existing)*
+Classic process viewer.
+- **Package:** `programs.htop.enable`