@icarusmx/creta 1.5.17 → 1.5.19

package/lib/exercises/15-nvim-plugin-architecture.md

@@ -0,0 +1,564 @@
+# Understanding LazyVim Plugin Architecture
+
+<!-- vim: set foldmethod=marker foldlevel=0: -->
+
+## 📖 LazyVim Reading Guide {{{
+
+**Start with:** `zM` (close all folds) → Navigate with `za` (toggle fold)
+
+**Keys for navigation:**
+- `}` - Jump to next section
+- `{` - Jump to previous section
+- `zM` - Close all folds (overview mode)
+- `zR` - Open all folds (detailed mode)
+
+}}}
+
+## 🎯 Purpose {{{
+
+**What:** Understand your LazyVim plugin configuration structure
+**Why:** Know where to add/modify plugins without breaking your setup
+**Time:** 20 minutes
+**Level:** 🟡 Intermediate
+
+**Entrypoint for ariadna nvim configuration:**
+`~/.config/nvim/lua/plugins/`
+
+Each `.lua` file = one plugin configuration (auto-loaded by LazyVim)
+
+}}}
+
+## Plugin Configuration Locations {{{
+
+### Two Important Directories {{{
+
+1. **`~/.config/nvim/lua/config/`** - LazyVim core settings
+   - `lazy.lua` - Plugin manager setup
+   - `options.lua` - Vim options (tab width, line numbers, etc)
+   - `keymaps.lua` - Custom keybindings
+   - `autocmds.lua` - Auto-commands (events)
+
+2. **`~/.config/nvim/lua/plugins/`** - Your plugin overrides
+   - Each file adds/modifies plugins
+   - Auto-loaded alphabetically
+   - This is where YOU make changes
+
+}}}
+
+### Current Plugin Files {{{
+
+```bash
+~/.config/nvim/lua/plugins/
+├── colorscheme.lua           # Theme (Catppuccin Latte)
+├── example.lua               # Reference examples (disabled)
+├── markdown.lua              # Markdown rendering + Glow preview
+├── neo-tree.lua              # File explorer filters
+├── svelte.lua                # Svelte support
+└── telescope_noignore.lua    # Search hidden/ignored files
+```
+
+}}}
+
+}}}
+
+## Part 1: Color Scheme Configuration {{{
+
+### File: `colorscheme.lua` {{{
+
+**Location:** `~/.config/nvim/lua/plugins/colorscheme.lua`
+
+**Purpose:** Override LazyVim's default theme
+
+**Current Setup:**
+```lua
+return {
+  {
+    "catppuccin/nvim",
+    name = "catppuccin",
+    priority = 1000,
+    opts = {
+      flavour = "latte",              -- Light theme
+      transparent_background = true,   -- See terminal bg
+      color_overrides = {
+        latte = {
+          blue = "#1e66f5",            -- Vibrant blues
+        },
+      },
+    },
+  },
+  {
+    "LazyVim/LazyVim",
+    opts = {
+      colorscheme = "catppuccin",
+    },
+  },
+}
+```
+
+**To change theme:**
+1. Edit this file
+2. Save
+3. Run `:Lazy sync` in nvim
+4. Restart nvim
+
+}}}
+
+### Practice: Try Different Flavors {{{
+
+Catppuccin has 4 flavors. Try changing `flavour = "latte"` to:
+
+- `"latte"` - Light (current)
+- `"frappe"` - Light-ish
+- `"macchiato"` - Dark-ish
+- `"mocha"` - Dark
+
+**Exercise:**
+1. Open `~/.config/nvim/lua/plugins/colorscheme.lua`
+2. Change `flavour = "mocha"`
+3. Save (`:w`)
+4. Quit nvim (`:q`)
+5. Reopen nvim
+6. Notice the dark theme
+7. Change back to `"latte"` if you prefer light
+
+}}}
+
+}}}
+
+## Part 2: Markdown Workflow {{{
+
+### File: `markdown.lua` {{{
+
+**Two plugins for different needs:**
+
+1. **render-markdown.nvim** - Inline preview
+   - Auto-renders when you open `.md` files
+   - Shows formatted headings, code blocks, bullets
+   - Works in normal mode (not insert)
+
+2. **glow.nvim** - Full preview
+   - Press `Shift+L` to open terminal preview
+   - Better for reviewing whole documents
+   - Dark theme, 120 char width
+
+**When to use which:**
+- Editing docs → render-markdown (always on)
+- Reviewing docs → Shift+L for glow
+- Presenting docs → Shift+L for clean view
+
+}}}
+
+### Practice: Test Markdown Preview {{{
+
+**Exercise:**
+1. Create a test markdown file: `nvim ~/test-doc.md`
+2. Type this content:
+
+```markdown
+# Test Document
+
+This is a **bold** paragraph with some *italic* text.
+
+## Code Example
+
+```javascript
+console.log("Hello from markdown!");
+```
+
+- Bullet one
+- Bullet two
+```
+
+3. Save (`:w`) and notice render-markdown formatting
+4. Press `Shift+L` to see Glow preview
+5. Press `q` to exit Glow
+6. Delete the test file: `:!rm %`
+
+}}}
+
+}}}
+
+## Part 3: Project-Specific Configs {{{
+
+### File: `neo-tree.lua` {{{
+
+**Hides config clutter from file explorer**
+
+Files hidden:
+- `eslint.config.js`
+- `jsconfig.json`
+- `vite.config.js`
+- `svelte.config.js`
+- `package-lock.json`
+- `.prettierrc`, `.prettierignore`
+- `.npmrc`, `.gitignore`
+
+**Why:** Keep file tree focused on actual code
+
+**To modify:**
+Add filenames to the `hide_by_name` and `never_show` arrays.
+
+}}}
+
+### File: `svelte.lua` {{{
+
+**Sets up Svelte development:**
+
+1. Treesitter parsers: svelte, html, css, js, ts
+2. Svelte LSP with Svelte 5 support
+3. Disables annoying a11y warnings
+
+**Critical for icarus.mx work**
+
+**The config:**
+```lua
+return {
+  -- Treesitter parsers
+  {
+    "nvim-treesitter/nvim-treesitter",
+    opts = function(_, opts)
+      vim.list_extend(opts.ensure_installed, {
+        "svelte", "html", "css", "javascript", "typescript",
+      })
+    end,
+  },
+  -- LSP support
+  {
+    "neovim/nvim-lspconfig",
+    opts = {
+      servers = {
+        svelte = {
+          settings = {
+            svelte = {
+              plugin = {
+                svelte = {
+                  compilerWarnings = {
+                    ["a11y-autofocus"] = "ignore",
+                    ["a11y-click-events-have-key-events"] = "ignore",
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+}}}
+
+### File: `telescope_noignore.lua` {{{
+
+**Overrides LazyVim defaults to search EVERYTHING:**
+
+- `--hidden` - Search dotfiles
+- `--no-ignore` - Search node_modules, .git, etc.
+- Shows gitignored files in neo-tree
+
+**When you need it:**
+- Finding files in node_modules
+- Debugging .git issues
+- Exploring hidden config files
+
+**The config:**
+```lua
+return {
+  {
+    "nvim-telescope/telescope.nvim",
+    opts = function(_, opts)
+      opts.defaults = vim.tbl_deep_extend("force", opts.defaults or {}, {
+        vimgrep_arguments = {
+          "rg", "--color=never", "--no-heading",
+          "--with-filename", "--line-number", "--column",
+          "--smart-case", "--hidden", "--no-ignore",
+        },
+      })
+      opts.pickers = vim.tbl_deep_extend("force", opts.pickers or {}, {
+        find_files = {
+          find_command = { "rg", "--files", "--hidden", "--no-ignore" },
+        },
+      })
+    end,
+  },
+}
+```
+
+}}}
+
+}}}
+
+## Part 4: Adding New Plugins {{{
+
+### The Pattern {{{
+
+**Create a new file:** `~/.config/nvim/lua/plugins/my-plugin.lua`
+
+```lua
+return {
+  {
+    "author/plugin-name",
+    opts = {
+      -- plugin options here
+    },
+  },
+}
+```
+
+**LazyVim automatically loads it** - no imports needed!
+
+}}}
+
+### Example: Add GitHub Copilot {{{
+
+**File:** `~/.config/nvim/lua/plugins/copilot.lua`
+
+```lua
+return {
+  {
+    "zbirenbaum/copilot.lua",
+    cmd = "Copilot",
+    event = "InsertEnter",
+    opts = {
+      suggestion = { enabled = true, auto_trigger = true },
+      panel = { enabled = true },
+    },
+  },
+}
+```
+
+Save → `:Lazy sync` → Restart → Done
+
+}}}
+
+### Example: Add a File Icon Theme {{{
+
+**File:** `~/.config/nvim/lua/plugins/devicons.lua`
+
+```lua
+return {
+  {
+    "nvim-tree/nvim-web-devicons",
+    opts = {
+      override = {
+        md = {
+          icon = "📝",
+          color = "#519aba",
+          name = "Markdown",
+        },
+      },
+    },
+  },
+}
+```
+
+This changes the markdown file icon in neo-tree and telescope.
+
+}}}
+
+### Practice: Add Your Own Plugin {{{
+
+**Exercise: Add a TODO comment highlighter**
+
+1. Create the file:
+```bash
+nvim ~/.config/nvim/lua/plugins/todo-comments.lua
+```
+
+2. Add this config:
+```lua
+return {
+  {
+    "folke/todo-comments.nvim",
+    dependencies = { "nvim-lua/plenary.nvim" },
+    opts = {
+      signs = true,
+      keywords = {
+        TODO = { icon = "✓", color = "info" },
+        HACK = { icon = "⚠", color = "warning" },
+        WARN = { icon = "⚠", color = "warning" },
+        NOTE = { icon = "ℹ", color = "hint" },
+      },
+    },
+  },
+}
+```
+
+3. Save and run `:Lazy sync`
+4. Restart nvim
+5. Try it in a JavaScript file:
+
+```javascript
+// TODO: This will be highlighted
+// HACK: So will this
+// NOTE: And this too
+```
+
+6. Search todos with `:TodoTelescope`
+
+}}}
+
+}}}
+
+## Part 5: Understanding Plugin Loading {{{
+
+### How LazyVim Loads Plugins {{{
+
+When nvim starts:
+
+1. Reads `~/.config/nvim/lua/config/lazy.lua`
+2. This file tells Lazy.nvim to load all files in `plugins/`
+3. Each `.lua` file returns a table of plugin specs
+4. Lazy.nvim merges all specs together
+5. Plugins install/load based on events (`VeryLazy`, `InsertEnter`, etc.)
+
+**Key insight:** Files in `plugins/` don't need to import each other. They're all loaded automatically.
+
+}}}
+
+### Plugin Loading Events {{{
+
+Common events you'll see:
+
+- `VeryLazy` - Load after startup (most plugins)
+- `InsertEnter` - Load when entering insert mode
+- `BufRead` - Load when reading a buffer
+- `FileType` - Load for specific file types
+- `cmd` - Load when command is run
+
+**Example:**
+```lua
+return {
+  {
+    "ellisonleao/glow.nvim",
+    cmd = "Glow",           -- Only loads when :Glow is run
+    ft = { "markdown" },    -- Only for .md files
+  },
+}
+```
+
+This keeps nvim startup fast!
+
+}}}
+
+### Overriding vs Extending {{{
+
+**Overriding** - Replace default config:
+```lua
+opts = {
+  theme = "latte",  -- Replaces entire opts table
+}
+```
+
+**Extending** - Add to default config:
+```lua
+opts = function(_, opts)
+  vim.list_extend(opts.ensure_installed, {
+    "svelte",  -- Adds to existing list
+  })
+end
+```
+
+**Use `opts = function` when you want to keep LazyVim defaults.**
+
+}}}
+
+}}}
+
+## Part 6: Debugging Plugin Issues {{{
+
+### Common Issues {{{
+
+**1. Plugin not loading**
+```vim
+:Lazy           " Open Lazy.nvim UI
+:Lazy log       " Check for errors
+:Lazy sync      " Force re-sync
+```
+
+**2. Config not applying**
+- Did you save the file?
+- Did you restart nvim?
+- Did you run `:Lazy sync`?
+
+**3. Conflicting configs**
+- Check if another file overrides the same plugin
+- LazyVim loads files alphabetically
+- Later files can override earlier ones
+
+}}}
+
+### Useful Commands {{{
+
+```vim
+:Lazy                 " Open plugin manager UI
+:Lazy update          " Update all plugins
+:Lazy sync            " Install/update/clean plugins
+:Lazy clean           " Remove unused plugins
+:Lazy profile         " See plugin load times
+:Lazy log             " View error logs
+
+:checkhealth          " Check nvim health
+:LspInfo              " Check LSP status
+:Mason                " Manage LSP/formatters
+```
+
+}}}
+
+### Practice: Debug a Plugin {{{
+
+**Exercise:**
+
+1. Open Lazy UI: `:Lazy`
+2. Press `p` to see profile (load times)
+3. Press `l` to see logs
+4. Find the `catppuccin` plugin
+5. Press `?` to see help
+6. Press `q` to close
+
+This UI shows you:
+- Which plugins are installed
+- Load order and timing
+- Error messages
+- Update status
+
+}}}
+
+}}}
+
+## 🎯 Outcomes {{{
+
+After this exercise, you can:
+
+✅ Find where your plugins are configured
+✅ Modify existing plugin settings
+✅ Add new plugins without breaking LazyVim
+✅ Understand the difference between `config/` and `plugins/`
+✅ Know your Neovim ariadna entrypoint: `~/.config/nvim/lua/plugins/`
+✅ Debug plugin issues using `:Lazy` commands
+✅ Extend vs override plugin configs
+✅ Use lazy loading for fast startup
+
+**Next Steps:**
+- Explore `example.lua` for more patterns
+- Try adding a plugin you've been wanting
+- Customize keybindings in a new plugin file
+- Browse LazyVim extras: `:LazyExtras`
+
+}}}
+
+## 🧭 Reference Links {{{
+
+- LazyVim docs: https://lazyvim.org
+- Lazy.nvim plugin manager: https://github.com/folke/lazy.nvim
+- Catppuccin theme: https://github.com/catppuccin/nvim
+- Plugin examples: `~/.config/nvim/lua/plugins/example.lua`
+- LazyVim plugins list: https://www.lazyvim.org/plugins
+
+**Your actual config:**
+- Main directory: `~/.config/nvim/`
+- Plugin configs: `~/.config/nvim/lua/plugins/`
+- Core settings: `~/.config/nvim/lua/config/`
+
+}}}

package/lib/exercises/16-nvim-fold-keymaps.md

@@ -0,0 +1,310 @@
+# Exercise 16: Customizing Fold Keymaps in Neovim (zN instead of zR)
+
+**Objective:** Replace the default `zR` (unfold all) mapping with `zN` so you can unfold all folds with a more intuitive keymap that aligns with your nvim muscle memory.
+
+**Time to complete:** 15 minutes
+
+---
+
+## Why This Matters
+
+Neovim's default fold keymaps follow traditional Vi conventions:
+- `zR` = unfold all (Reduce folds)
+- `zM` = fold all (More folds)
+
+The letter choices are cryptic. If you prefer mnemonics like:
+- `zN` = unfold all (N for "opeN")
+- `zM` = fold all (M stays the same - "More folds" works)
+
+...then this exercise shows you how to map them in your `init.lua`.
+
+---
+
+## Step 1: Understand the Default Fold Keymaps
+
+First, let's see what fold mappings exist by default.
+
+Open your Neovim and check the current mappings:
+
+```vim
+:help fold-commands
+```
+
+The key ones are:
+| Mapping | Action | Default |
+|---------|--------|---------|
+| `zR` | Unfold all | Open all folds in buffer |
+| `zM` | Fold all | Close all folds in buffer |
+| `zr` | Unfold one level | Open one level of folds |
+| `zm` | Fold one level | Close one level of folds |
+| `za` | Toggle fold | Toggle fold at cursor |
+
+---
+
+## Step 2: Locate Your init.lua
+
+Your Neovim configuration file is typically at one of these locations:
+
+```bash
+# Check which one exists
+ls ~/.config/nvim/init.lua
+ls ~/AppData/Local/nvim/init.lua  # Windows
+ls ~/.config/nvim/init.vim         # Old init.vim (less common now)
+```
+
+The standard location on macOS/Linux:
+
+```bash
+~/.config/nvim/init.lua
+```
+
+---
+
+## Step 3: Add the Custom Keymap
+
+Open your `init.lua` in Neovim:
+
+```bash
+nvim ~/.config/nvim/init.lua
+```
+
+Add these lines to create the `zN` mapping:
+
+```lua
+-- Fold keymaps customization
+-- Use zN to unfold all (instead of zR)
+vim.keymap.set('n', 'zN', 'zR', { noremap = true, silent = true, desc = 'Unfold all' })
+
+-- Optional: keep zR as a backup
+-- (Remove this line if you want to completely replace zR with zN)
+-- vim.keymap.set('n', 'zR', 'zN', { noremap = true, silent = true, desc = 'Unfold all (backup)' })
+```
+
+**What each part does:**
+- `'n'` - Normal mode only
+- `'zN'` - The new key you want to press
+- `'zR'` - The command it executes (the built-in unfold all)
+- `noremap = true` - Don't remap recursively
+- `silent = true` - Don't show the command in status line
+- `desc` - Help text when you do `:map zN`
+
+---
+
+## Step 4: Remove or Remap zR
+
+If you want `zR` to stop working (force yourself to use `zN`), add this:
+
+```lua
+-- Disable zR so only zN works
+vim.keymap.set('n', 'zR', '<nop>', { noremap = true, silent = true, desc = 'Disabled - use zN instead' })
+```
+
+Or remap `zR` to something else:
+
+```lua
+-- Remap zR to unfold one level (what zr does)
+vim.keymap.set('n', 'zR', 'zr', { noremap = true, silent = true, desc = 'Unfold one level' })
+```
+
+---
+
+## Step 5: Save and Reload
+
+In Neovim:
+
+```vim
+:w                 " Save the file
+:source %          " Reload the configuration
+```
+
+Or exit and restart Neovim:
+
+```bash
+exit
+nvim
+```
+
+---
+
+## Step 6: Test Your New Mapping
+
+1. Open any file with folds (or create one with folds using `:set foldmethod=syntax`)
+2. Press `zM` to fold all
+3. Press `zN` to unfold all
+4. Verify it works!
+
+---
+
+## Complete Configuration Example
+
+Here's what your `~/.config/nvim/init.lua` fold section should look like:
+
+```lua
+-- ============================================================================
+-- FOLD KEYMAPS
+-- ============================================================================
+
+-- Custom fold mappings for better muscle memory
+vim.keymap.set('n', 'zN', 'zR', { noremap = true, silent = true, desc = 'Unfold all (zN)' })
+vim.keymap.set('n', 'zM', 'zM', { noremap = true, silent = true, desc = 'Fold all (zM)' })
+
+-- Optional: Disable zR to force zN usage
+-- vim.keymap.set('n', 'zR', '<nop>', { noremap = true, silent = true })
+
+-- Optional: Map for one-level fold/unfold with intuitive keys
+-- vim.keymap.set('n', 'zn', 'zr', { noremap = true, silent = true, desc = 'Unfold one level' })
+-- vim.keymap.set('n', 'zm', 'zm', { noremap = true, silent = true, desc = 'Fold one level' })
+
+-- ============================================================================
+```
+
+---
+
+## Verification: Check Your Mapping
+
+After reloading, verify the mapping exists:
+
+```vim
+:map zN
+```
+
+You should see:
+```
+n  zN           zR
+```
+
+This confirms `zN` now executes `zR` (unfold all).
+
+---
+
+## Advanced: Create a Fold Mode Function
+
+If you want even more control, create a function:
+
+```lua
+-- Function-based fold toggle
+local function toggle_fold_level()
+  -- Get current fold level
+  local fold_level = vim.fn.foldlevel(vim.fn.line('.'))
+
+  if fold_level > 0 then
+    vim.cmd('zN')  -- Unfold all
+  else
+    vim.cmd('zM')  -- Fold all
+  end
+end
+
+vim.keymap.set('n', 'z<Space>', toggle_fold_level, { noremap = true, silent = true, desc = 'Toggle fold state' })
+```
+
+Then pressing `z<Space>` intelligently toggles between fold all and unfold all.
+
+---
+
+## Troubleshooting
+
+### Mapping doesn't work
+**Problem:** You press `zN` and nothing happens.
+
+**Solution:**
+1. Verify the mapping was loaded: `:map zN`
+2. Check for conflicts: `:verbose map zN`
+3. Make sure you're in Normal mode (press `Esc` first)
+4. Reload config: `:source %`
+
+### Old mapping still works
+**Problem:** `zR` still unfolds even though you wanted to disable it.
+
+**Solution:**
+- Make sure you added the `<nop>` mapping for `zR`
+- Restart Neovim completely (`:q!` then `nvim`)
+- Check if another plugin is defining `zR`: `:verbose map zR`
+
+### Fold commands not working
+**Problem:** `zN` executes but nothing happens.
+
+**Solution:**
+- Make sure the buffer has folds: `:set foldmethod=syntax` or `:set foldmethod=manual`
+- The buffer must have fold markers (depends on `foldmethod`)
+- Check the file type supports folding
+
+---
+
+## Related Keymaps Worth Adding
+
+While you're customizing folds, consider these related mappings:
+
+```lua
+-- Complete fold mapping suite
+vim.keymap.set('n', 'zN', 'zR', { noremap = true, silent = true, desc = 'Unfold all' })
+vim.keymap.set('n', 'zM', 'zM', { noremap = true, silent = true, desc = 'Fold all' })
+vim.keymap.set('n', 'zn', 'zr', { noremap = true, silent = true, desc = 'Unfold one level' })
+vim.keymap.set('n', 'zm', 'zm', { noremap = true, silent = true, desc = 'Fold one level' })
+vim.keymap.set('n', 'zc', 'zc', { noremap = true, silent = true, desc = 'Close fold' })
+vim.keymap.set('n', 'zo', 'zo', { noremap = true, silent = true, desc = 'Open fold' })
+vim.keymap.set('n', 'za', 'za', { noremap = true, silent = true, desc = 'Toggle fold' })
+```
+
+---
+
+## Pro Tips
+
+1. **Use modelines** - Add to the top of files you edit frequently:
+```vim
+" vim: set foldmethod=syntax foldlevel=1 :
+```
+
+2. **Set default foldlevel** - Add to `init.lua`:
+```lua
+vim.opt.foldlevel = 1  -- Start with one level of folds open
+```
+
+3. **Use with LazyVim** - If using LazyVim, add to `~/.config/nvim/lua/config/keymaps.lua`:
+```lua
+-- Already might have keymaps there
+vim.keymap.set('n', 'zN', 'zR', { desc = 'Unfold all' })
+```
+
+4. **Vim muscle memory** - Remember: `z` is for "**z**ones" (folds), then:
+   - `N` = ope**N** all
+   - `M` = **M**ore closed
+   - `C` = **C**lose
+   - `O` = **O**pen
+   - `A` = **A**lternate (toggle)
+
+---
+
+## Summary
+
+You've successfully:
+- ✅ Understood Neovim's default fold keymaps
+- ✅ Located your `init.lua` configuration
+- ✅ Created a custom `zN` mapping for unfold all
+- ✅ Optionally disabled the old `zR` mapping
+- ✅ Tested your new configuration
+- ✅ Verified the mapping is active
+
+Your new `zN` keymap is now part of your Neovim muscle memory. Use it consistently in your workflow.
+
+---
+
+## Next Steps
+
+1. Create this mapping in your actual `init.lua` right now
+2. Test it for the next week in your daily editing
+3. If you like it, consider adding the one-level mappings (`zn` and `zm`)
+4. Move on to Exercise 17 when you're comfortable with fold navigation
+
+---
+
+## Resources
+
+- `:help fold-commands` - Full fold command documentation
+- `:help mapping` - Full mapping documentation
+- `:help option-window` - View all fold-related options
+- `:map` - List all current mappings
+- `:verbose map zN` - See where a mapping is defined
+
+---
+
+**Keep it simple.** Just two lines for the basic mapping. Everything else is optional optimization.

package/lib/exercises/17-ariadna-custom-fold-keymaps.md

@@ -0,0 +1,373 @@
+# Customizing Fold Keymaps in Ariadna (zN instead of zR)
+
+<!-- vim: set foldmethod=marker foldlevel=0: -->
+
+## 📖 Ariadna Reading Guide {{{
+
+**Start with:** `zM` (close all folds) → Navigate with `za` (toggle fold under cursor)
+
+**Keys for navigation:**
+- `}` - Jump to next section
+- `{` - Jump to previous section
+- `zM` - Close all folds (overview mode)
+- `zN` - Open all folds (will use this after implementing!)
+
+}}}
+
+## 🎯 Purpose {{{
+
+**What:** Replace Neovim's default fold keymaps with more intuitive ones
+**Why:** The default `zR` is cryptic; `zN` (for "opeN") is more memorable
+**Time:** 10 minutes
+**Level:** 🟢 Beginner
+**Entrypoint for ariadna setup:** `~/.config/nvim/lua/plugins/`
+
+}}}
+
+## Part 1: Understanding Default Fold Commands {{{
+
+### Why Fold Commands Matter {{{
+
+Ariadna uses fold markers (`{{{` and `}}}`) throughout documentation to create navigable sections. But the default Neovim keymaps are cryptic:
+
+- `zR` = unfold all (Reduce? No one knows...)
+- `zM` = fold all (More folds? Still confusing!)
+- `zr` = unfold one level
+- `zm` = fold one level
+
+These follow old Vi conventions, not modern mnemonics.
+
+}}}
+
+### The Better Alternative {{{
+
+We want:
+- `zN` = unfold all (N for "**opeN**")
+- `zM` = fold all (M for "**More** closed" - keep this)
+- `zn` = unfold one level (lowercase n)
+- `zm` = fold one level (lowercase m)
+
+This is much more memorable and aligns with your muscle memory.
+
+}}}
+
+}}}
+
+## Part 2: Creating the Plugin File {{{
+
+### Step 1: Create the Folds Plugin {{{
+
+Create a new file in Ariadna's plugin directory:
+
+```bash
+nvim ~/.config/nvim/lua/plugins/folds.lua
+```
+
+This is where all Ariadna plugins live. LazyVim auto-loads every `.lua` file in this directory.
+
+}}}
+
+### Step 2: Add the Configuration {{{
+
+Add this to `folds.lua`:
+
+```lua
+-- Custom fold keymaps for Ariadna
+-- Replace cryptic zR/zM with intuitive zN/zM
+
+return {
+  {
+    "fold-keymaps/custom",
+    init = function()
+      local map = vim.keymap.set
+
+      -- Main fold commands
+      map("n", "zN", "zR", { desc = "Unfold all (zN = opeN)" })
+      map("n", "zM", "zM", { desc = "Fold all (zM = More closed)" })
+
+      -- Optional: One-level fold/unfold
+      map("n", "zn", "zr", { desc = "Unfold one level" })
+      map("n", "zm", "zm", { desc = "Fold one level" })
+
+      -- Optional: Disable zR to force zN usage
+      -- Uncomment if you want to completely replace zR
+      -- map("n", "zR", "<nop>", { desc = "Use zN instead (unfold all)" })
+    end,
+  },
+}
+```
+
+**What each mapping does:**
+- `map("n", "zN", "zR", ...)` - In Normal mode, pressing `zN` executes `zR` (unfold all)
+- `desc` - Help text for `:map zN` or which-key
+
+}}}
+
+### Step 3: Save and Reload {{{
+
+In Neovim:
+
+```vim
+:w                " Save folds.lua
+:source %         " Reload configuration
+```
+
+Or exit and restart Neovim - LazyVim will auto-load the new plugin.
+
+}}}
+
+}}}
+
+## Part 3: Testing Your Custom Keymaps {{{
+
+### Test Zone: Try Your New Keymaps {{{
+
+Now that you've created `folds.lua`, test it:
+
+1. **Fold all content:**
+   Press `zM` (or `zm zm zm...` to fold level by level)
+
+2. **Unfold all content:**
+   Press `zN` (this is your new mapping!)
+
+3. **Verify it works:**
+   Check the output shows all sections visible again
+
+4. **One-level folds:**
+   Try `zn` (unfold one level) and `zm` (fold one level)
+
+The keymaps should respond immediately. If they don't:
+- Did you save `folds.lua`?
+- Did you reload nvim?
+- Check: `:map zN` should show the mapping
+
+}}}
+
+### Advanced: Verify the Mapping {{{
+
+In Neovim, run:
+
+```vim
+:map zN
+```
+
+You should see output like:
+
+```
+n  zN           zR
+```
+
+This confirms `zN` is mapped to `zR` (unfold all). If nothing shows, the mapping didn't load.
+
+}}}
+
+}}}
+
+## Part 4: Ariadna-Specific Context {{{
+
+### Why This Matters for Ariadna Users {{{
+
+Ariadna documents are built with fold markers for optimal navigation:
+
+```lua
+-- These fold markers structure everything
+-- {{{ = start fold
+-- }}} = end fold
+```
+
+When you're reading Ariadna docs or editing structured Lua files, you'll:
+
+1. Start with `zM` (fold all) to see structure
+2. Navigate with `}` to jump sections
+3. Use `za` to toggle individual folds
+4. Use `zN` to unfold everything when you need full content
+
+This is the "Ariadna way" of reading documentation.
+
+}}}
+
+### Where You'll Use This {{{
+
+Every Ariadna document uses this pattern:
+
+- `01-developing-muscle-for-nvim.md` - Has fold markers
+- `15-nvim-plugin-architecture.md` - Heavily folded
+- Your own `.md` files - You'll add fold markers too
+
+Plus any Lua files you write in `~/.config/nvim/lua/` will benefit from custom fold navigation.
+
+}}}
+
+}}}
+
+## Part 5: Optional Customizations {{{
+
+### Option 1: Disable Old zR Mapping {{{
+
+If you want to completely replace `zR` with `zN` (force new muscle memory):
+
+**Edit** `~/.config/nvim/lua/plugins/folds.lua`:
+
+```lua
+-- Disable zR to force zN usage
+map("n", "zR", "<nop>", { desc = "Use zN instead" })
+```
+
+This makes `zR` do nothing, so you're forced to use `zN`.
+
+}}}
+
+### Option 2: Add Custom Fold Default Level {{{
+
+You can set the default fold level when opening files:
+
+```lua
+vim.opt.foldlevel = 1  -- Start with one level open
+```
+
+Add this to `~/.config/nvim/lua/config/options.lua` (or create a new section in folds.lua):
+
+```lua
+init = function()
+  -- Set default fold behavior
+  vim.opt.foldlevel = 1
+  vim.opt.foldmethod = "marker"  -- Use {{{ }}} markers
+end
+```
+
+}}}
+
+### Option 3: Add Smart Fold Toggle {{{
+
+Create a function that intelligently toggles between fold all/unfold all:
+
+```lua
+local function smart_fold_toggle()
+  local fold_level = vim.fn.foldlevel(vim.fn.line('.'))
+  if fold_level > 0 then
+    vim.cmd('zN')  -- Unfold all
+  else
+    vim.cmd('zM')  -- Fold all
+  end
+end
+
+map("n", "z<Space>", smart_fold_toggle, { desc = "Smart fold toggle" })
+```
+
+Now `z<Space>` intelligently switches between folded/unfolded state.
+
+}}}
+
+}}}
+
+## Part 6: Troubleshooting {{{
+
+### Mapping Doesn't Work {{{
+
+**Problem:** You press `zN` and nothing happens.
+
+**Solutions:**
+1. Verify mapping loaded: `:map zN` (should show output)
+2. Reload config: `:source %` or restart nvim
+3. Check you're in Normal mode (press `Esc` first)
+4. Verify `folds.lua` file exists: `ls ~/.config/nvim/lua/plugins/folds.lua`
+
+}}}
+
+### Old zR Mapping Still Works {{{
+
+**Problem:** `zR` still unfolds even though you wanted to disable it.
+
+**Solutions:**
+1. Make sure you added the `<nop>` mapping in `folds.lua`
+2. Restart Neovim completely (`:q!` then `nvim`)
+3. Check for conflicts: `:verbose map zR`
+
+}}}
+
+### File Has No Folds {{{
+
+**Problem:** `zM` doesn't do anything.
+
+**Solutions:**
+1. File must use fold markers: `{{{` and `}}}`
+2. Set foldmethod: `:set foldmethod=marker`
+3. Try on an Ariadna document that has fold markers
+
+}}}
+
+}}}
+
+## 🎯 Outcomes {{{
+
+After this exercise, you can:
+
+✅ Create custom Neovim keymaps in Ariadna plugin files
+✅ Replace cryptic default keymaps with intuitive ones
+✅ Use `zN` instead of `zR` for "open" all folds
+✅ Structure your Lua files with fold markers for navigation
+✅ Read Ariadna documentation using fold navigation
+✅ Customize Ariadna's behavior without forking the repo
+✅ Debug and verify custom keymaps with `:map`
+
+**Your new workflow:**
+- `zM` - Fold all (see structure)
+- `}` - Jump to next section
+- `za` - Toggle individual fold
+- `zN` - Unfold all (see content)
+
+**Next Steps:**
+- Try the custom `zN` mapping in actual Ariadna files
+- Add fold markers to your own documentation
+- Experiment with one-level folds (`zn`/`zm`)
+- Move on to Exercise 18 when comfortable
+
+}}}
+
+## 🧭 Reference Links {{{
+
+**Ariadna Locations:**
+- Plugin files: `~/.config/nvim/lua/plugins/`
+- Core settings: `~/.config/nvim/lua/config/`
+- Your config: `~/.config/nvim/init.lua`
+
+**Neovim Documentation:**
+- `:help fold-commands` - Full fold documentation
+- `:help map` - Mapping documentation
+- `:help foldmethod` - Fold detection options
+
+**Vim Mnemonics:**
+- `z` = zones (folds)
+- `N` = ope**N** (unfold all)
+- `M` = **M**ore folds (fold all)
+- `n` = ope**n** (unfold one level)
+- `m` = **m**ore folds (fold one level)
+
+**Related Exercises:**
+- Exercise 01 - Developing Muscle Memory (uses fold navigation)
+- Exercise 15 - LazyVim Plugin Architecture (plugin structure)
+
+}}}
+
+## 📝 Quick Reference: What You Just Created {{{
+
+**File:** `~/.config/nvim/lua/plugins/folds.lua`
+
+**What it does:**
+1. Maps `zN` to `zR` (unfold all)
+2. Maps `zM` to `zM` (fold all - no change needed)
+3. Maps `zn` to `zr` (unfold one level - optional)
+4. Maps `zm` to `zm` (fold one level - optional)
+
+**How to modify:**
+- Edit the file and save
+- Reload: `:source %` or restart nvim
+- Verify: `:map zN`
+
+**How to remove:**
+```bash
+rm ~/.config/nvim/lua/plugins/folds.lua
+# Then restart nvim
+```
+
+}}}

package/lib/exercises/README.md

@@ -112,6 +112,12 @@ Each phase builds on knowledge from previous phases.
 **Time:** Design exercise
 **Level:** 🔴 Advanced
 
+### 15. [Understanding LazyVim Plugin Architecture](./15-nvim-plugin-architecture.md)
+**What:** Master your Neovim plugin configuration structure
+**Why:** Add/modify plugins without breaking your setup
+**Time:** 20 minutes
+**Level:** 🟡 Intermediate
+
 ---
 
 ## 🎯 How to Use These Guides
@@ -153,6 +159,10 @@ Prefer to browse by subject?
 - [Shell Aliases](./13-shell-aliases.md)
 - [curl + Pipes](./06-curl-and-pipes.md)
 
+### Neovim Configuration
+- [Developing Muscle Memory for Neovim](./01-developing-muscle-for-nvim.md)
+- [Understanding LazyVim Plugin Architecture](./15-nvim-plugin-architecture.md)
+
 ### JavaScript & Development
 - [Array & Object Manipulation](./04-array-object-manipulation.md)
 - [SvelteKit First Steps](./05-svelte-first-steps.md)
@@ -170,6 +180,7 @@ Prefer to browse by subject?
 
 ### Meta/Tooling
 - [Install Skills Command](./12-install-skills.md)
+- [Understanding LazyVim Plugin Architecture](./15-nvim-plugin-architecture.md)
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@icarusmx/creta",
-  "version": "1.5.17",
+  "version": "1.5.19",
   "description": "Salgamos de este laberinto.",
   "type": "module",
   "bin": {