Add comprehensive snacks.nvim integration with documentation and templates

.github/copilot-instructions.md

@@ -1,3 +1,37 @@
+RECURSIVE_START
+Recognize that all repositories are nix flake based and often use each other as inputs. Sometimes the options and configuration for one repository will be in another as an input which can be found in the flake.nix file of the repo that calls another as an input. 
+
+common input names as they link to repos:
+- gigdot & dotfiles refer to @gignsky/dotfiles
+- wrap, wrapd, wrapper, & tarballer refer to @gignsky/wrap
+- nufetch & neofetch refer to @gignsky/nufetch
+- gigvim refers to @gignsky/gigvim
+
+Below are rules that must ALWAYS be followed:
+1. All progression steps should be displayed as NEW comments with checkbox lists of tasks to be completed, to be checked off via a comment edit while adding a timestamp as well as legnth of time taken to progress to this point and notes about the task, including links to relevant commits, PRs, or issues, etc...
+2. Original prompt for agents should be preserved as a comment at the beginning of a PR or issue as well as in the description of the copilot's initial commit on a new PR
+3. Make every effort to make every ai agent call as effective as possible in order to preserve as many premium requests as possible
+4. ALWAYS attempt to verify that changes compile, often this is as simple as running `nix flake check` or `nix build` in the repository, if the checks fail, continue iterating until they pass
+5. Document as much as possible in markdown files either in the docs/ dir or in logical places alongside files and in files
+
+In all sessions, the order of operations is as follows:
+0. Read all of these operations and understand them before continuing
+0.a. Create a new comment in the issue or PR that reflects this order of operations with checkboxes and edit the comment marking the checkboxes as you progress
+0.a.NOTE: Refer to rule #1
+0.b. Analyze all repository's copilot-instructions looking specifically for the RECURSIVE block described in step x+4, find the diff between these versions, determine the most recent / logical state of the block and immediately replace the block in the active repos instructions with it
+1. Analyze the active repos' .github/ folder and its contents for repo specific instructions
+2. Analyze the other repo's .github/ fiolder and its contents for general ecosystem updates since last checked
+3. Analyze the @gignsky/dotfiles .github/ cortana chatbot markdown file and understand the way in which your are supposed to interact based off of that file
+4. Analyze the active repo and ALL its elements and compare and contrast with the active repo's .github/copilot-instructions.md file
+5. Based off of information gathered in the previous steps please analyze the expected and actual state of ci/cd in the current repository and make note that the ci/cd pipeline for the current repository exists within the copilot-instructions
+6. Update the instructions file to include updated information based off of data gathered in steps 1-5
+7. Step 7 (here) should be replaced with 7..x where x equals the total number of steps that cortana determines are neccary to complete the request from the all powerful lord gig minus seven. Steps continue at item x+1 below.
+x+1. Testing pipeline should start here, at a minimum a `nix flake check` needs to pass before this item can be marked completed, if this can't be done then detailed error messages should be left in the comments
+x+2. Testing pipeline continues, if changes to the repository would have an effect on the flake outputs the changed outputs themselves should be checked here in as many check boxes as is nececcary
+x+3. After flake testing in items x+1 & x+2 (which can be multiple checkboxes and steps) Repeat steps 0-6 and then continue below on step x+4
+x+4. All text between RECURSIVE_START & RECURSIVE_END should be placed at the top of each copilot-instructions.md file in every repository, at this point replace the version from step 0.b with an updated version based on all changes made before this step
+RECURSIVE_END
+
 # GigVim - Nix-based Neovim Configuration
 
 GigVim is a Nix Flake-based Neovim configuration using the nvf (NeoVim Flake) framework. It provides a highly customizable and reproducible development environment with language support, plugins, and themes configured declaratively.
@@ -190,4 +224,4 @@ The configuration automatically includes these tools:
 - `nix develop` (first time): 15-30 minutes
 - `nix develop` (incremental): 1-2 minutes
 
-Always set timeouts to at least double these estimates to account for network variability and system performance differences.
+Always set timeouts to at least double these estimates to account for network variability and system performance differences.

.gitignore

@@ -1,2 +1,11 @@
 result
+result-*
 .direnv
+.DS_Store
+*.log
+/tmp/
+.cache/
+.local/
+node_modules/
+dist/
+build/

docs/plugins/README.md

@@ -0,0 +1,236 @@
+# Snacks.nvim Integration for GigVim
+
+## Overview
+
+This directory contains a comprehensive integration of [folke/snacks.nvim](https://github.com/folke/snacks.nvim) into the GigVim nvf-based Neovim configuration. Snacks.nvim is a collection of 26+ small quality-of-life plugins that enhance the Neovim experience.
+
+## Files Structure
+
+```
+docs/plugins/
+├── snacks-nvim.md                    # Comprehensive documentation
+├── snacks-nvim-integration.md       # Integration guide
+└── snacks-nvim-full-example.nix     # Example full configuration
+
+plugins/optional/
+├── snacks-nvim.nix                  # Default configuration (recommended)
+├── TEMPLATE-snacks-nvim-minimal.nix # Conservative setup
+├── TEMPLATE-snacks-nvim-dev.nix     # Development-focused setup
+└── TEMPLATE-snacks-nvim-full.nix    # Comprehensive setup
+
+flake.nix                            # Updated with snacks-nvim input
+```
+
+## Configuration Options
+
+### 1. Default Configuration (`snacks-nvim.nix`)
+**Recommended for most users**
+
+- **Enabled snacks**: bigfile, dashboard, explorer, indent, input, notifier, picker, quickfile, scope, scroll, statuscolumn, words
+- **Features**: Core QoL improvements, file explorer, picker, notifications, smooth scrolling
+- **Conflicts**: Moderate - may conflict with existing dashboard or file explorer
+- **Usage**: Basic setup with essential enhancements
+
+### 2. Minimal Configuration (`TEMPLATE-snacks-nvim-minimal.nix`)
+**Conservative setup for cautious users**
+
+- **Enabled snacks**: bigfile, input, notifier, quickfile
+- **Features**: Essential improvements only
+- **Conflicts**: Minimal - very low risk
+- **Usage**: When you want snacks benefits with minimal changes
+
+### 3. Developer Configuration (`TEMPLATE-snacks-nvim-dev.nix`)
+**Development-focused workflows**
+
+- **Enabled snacks**: Core + debug, picker, profiler, git integration, terminal, scratch buffers
+- **Features**: Enhanced development tools, debugging, git integration
+- **Conflicts**: Moderate - may conflict with existing git/terminal plugins
+- **Usage**: Development environments with enhanced tooling
+
+### 4. Full Configuration (`TEMPLATE-snacks-nvim-full.nix`)
+**Power users wanting all features**
+
+- **Enabled snacks**: All 26+ snacks with comprehensive configuration
+- **Features**: Complete snacks.nvim experience
+- **Conflicts**: High - extensive potential conflicts
+- **Usage**: Power users who want to fully leverage snacks.nvim
+
+## Quick Start
+
+### 1. Choose Configuration
+Copy the desired configuration template or use the default:
+
+```nix
+# In your full.nix
+let
+  snacksModule = import ./plugins/optional/snacks-nvim.nix { inherit inputs pkgs; };
+in
+{
+  imports = [
+    ./minimal.nix
+    snacksModule
+  ];
+}
+```
+
+### 2. Build and Test
+```bash
+# Validate
+nix flake check
+
+# Build
+nix build
+
+# Test
+./result/bin/nvim
+```
+
+### 3. Health Check
+```vim
+:checkhealth snacks
+```
+
+## Key Features by Configuration
+
+### Default Configuration Features
+
+| Feature | Description | Keybind |
+|---------|-------------|---------|
+| **File Picker** | Smart file finding with fuzzy search | `<leader>ff` |
+| **Recent Files** | Quick access to recently opened files | `<leader>fr` |
+| **Text Search** | Grep across project files | `<leader>fg` |
+| **Buffer Picker** | Navigate between open buffers | `<leader>fb` |
+| **File Explorer** | Built-in file tree explorer | `<leader>e` |
+| **Dashboard** | Beautiful startup dashboard | Auto on startup |
+| **Notifications** | Enhanced notification system | `<leader>n` (history) |
+| **Big File Handling** | Optimized handling of large files | Automatic |
+| **Smooth Scrolling** | Smooth scrolling animations | Automatic |
+| **Status Column** | Enhanced gutter with git signs | Automatic |
+| **Word Navigation** | LSP reference navigation | `]]` / `[[` |
+
+### Developer Configuration Additions
+
+| Feature | Description | Keybind |
+|---------|-------------|---------|
+| **Git Browse** | Open files in browser (GitHub/GitLab) | `<leader>gB` |
+| **LazyGit** | Integrated LazyGit terminal | `<leader>gg` |
+| **Terminal** | Floating terminal windows | `<C-/>` |
+| **Scratch Buffers** | Temporary scratch files | `<leader>.` |
+| **Debug Tools** | Enhanced debugging utilities | `dd()`, `bt()` |
+| **Profiler** | Lua performance profiling | `:lua Snacks.profiler` |
+| **LSP Integration** | Enhanced LSP pickers | `gd`, `gr`, `gI` |
+
+## Plugin Integrations
+
+### Compatible with GigVim
+- ✅ **Themes**: Works with all GigVim themes
+- ✅ **Language Servers**: Enhances LSP experience
+- ✅ **nvf core**: Fully compatible with nvf framework
+- ✅ **Mini plugins**: Can coexist with mini.nvim suite
+
+### Potential Conflicts
+- ⚠️ **Telescope**: Picker conflicts (choose one or use different keymaps)
+- ⚠️ **Dashboard-nvim**: Dashboard conflicts (disable one)
+- ⚠️ **Nvim-tree/Neo-tree**: Explorer conflicts (choose one)
+- ⚠️ **Nvim-notify**: Notification conflicts (snacks.notifier replaces)
+
+## Configuration Examples
+
+### Enable Additional Snacks
+```nix
+# Add to your configuration
+config.vim.extraPlugins.snacks.setup = ''
+  require('snacks').setup({
+    -- Enable git features
+    git = { enabled = true },
+    gitbrowse = { enabled = true },
+    lazygit = { enabled = true },
+
+    -- Enable zen mode
+    zen = { 
+      enabled = true,
+      width = 0.8,
+      height = 0.8,
+    },
+  })
+'';
+```
+
+### Custom Keymaps
+```nix
+# Add custom keymaps
+vim.keymap.set("n", "<leader>my", function() 
+  require("snacks").picker.files({ cwd = "~/my-project" }) 
+end, { desc = "My Project Files" })
+```
+
+### Custom Styling
+```nix
+# Customize appearance
+styles = {
+  picker = {
+    border = "double",
+    width = 0.9,
+    height = 0.9,
+  },
+  notification = {
+    border = "rounded",
+    wo = { wrap = true },
+  },
+}
+```
+
+## Performance Considerations
+
+1. **Animations**: Disabled by default in templates for better performance
+2. **Lazy Loading**: Some snacks support lazy loading patterns
+3. **Selective Enabling**: Only enable needed snacks
+4. **Startup Time**: Monitor with profiler snack
+
+## Migration Guide
+
+### From Telescope
+1. Test snacks.picker functionality
+2. Migrate custom telescope configurations
+3. Update keymaps gradually
+4. Disable telescope when satisfied
+
+### From Other Plugins
+- **Dashboard**: Compare dashboard features and migrate sections
+- **File Explorer**: Test file operations and git integration
+- **Notifications**: Update notification handling code
+
+## Troubleshooting
+
+### Common Issues
+1. **Build failures**: Check flake.nix input declaration
+2. **Plugin not loading**: Verify extraPlugins configuration
+3. **Keymaps conflicts**: Review existing keymaps
+4. **Performance issues**: Disable unused snacks
+
+### Debug Commands
+```vim
+:lua print(vim.inspect(require("snacks.config")))
+:checkhealth snacks
+:lua require("snacks").profiler.start()
+```
+
+## External Resources
+
+- [Main Repository](https://github.com/folke/snacks.nvim)
+- [Official Documentation](https://github.com/folke/snacks.nvim/tree/main/docs)
+- [Examples Directory](https://github.com/folke/snacks.nvim/tree/main/docs/examples)
+- [Individual Snack Docs](https://github.com/folke/snacks.nvim/tree/main/docs)
+
+## Contributing
+
+To improve this integration:
+
+1. Test with different nvf setups
+2. Document conflicts and solutions
+3. Add new configuration patterns
+4. Update documentation
+
+---
+
+*This integration provides a comprehensive, documented, and templated approach to using snacks.nvim within the nvf framework, following GigVim's patterns and best practices.*