Update documentation and add session management features

- Revise keymap documentation to include immediate updates
- Add session management: auto-load and auto-save Session.vim

.github/copilot-instructions.md

@@ -112,8 +112,9 @@ return {
 2. **Before large changes**: Update plan via CLI `update_plan` tool (if available)
 3. **After any change**: Immediately update `MIGRATION_PLAN.md` (check off items, add notes)
 4. **After decisions**: Update `README.md` decisions log
-5. Execute phases via subphases (N.x); one bullet = one implement-and-test step
-6. Archive legacy files to `legacy/` instead of deleting
+5. **After adding/removing/editing any keymaps**: Immediately update `KEYMAPS.md` with the change (add new entries, remove deleted mappings, or update descriptions)
+6. Execute phases via subphases (N.x); one bullet = one implement-and-test step
+7. Archive legacy files to `legacy/` instead of deleting
 
 ## Do NOT Reintroduce (from AGENTS.md)
 - Custom Vimscript tabline/statusline/foldtext

AGENTS.md

@@ -162,9 +162,10 @@ This repository is being migrated to a modern, minimal Neovim setup driven by Lu
 - Before large changes, update the task plan via the CLI `update_plan` tool.
 - Keep the live checklist in `MIGRATION_PLAN.md:1` up to date and in sync with changes.
 - After any config or plugin change, immediately update `MIGRATION_PLAN.md` (check off items, add notes, or adjust next steps).
- - After any change or decision, also update `README.md:1` (decisions log and design docs).
+- After any change or decision, also update `README.md:1` (decisions log and design docs).
+- **After adding/removing/editing any keymaps**, immediately update `KEYMAPS.md` with the change (add new entries, remove deleted mappings, or update descriptions).
 - At the start of each phase, confirm scope and priorities for that phase.
 - Execute phases via subphases (`N.x`), where each bullet under a phase is its own implement-and-test step (e.g., Phase 3.1, 3.2, 3.3, 3.4).
-- Record decisions and rationale in `README.md:1` as they’re made.
+- Record decisions and rationale in `README.md:1` as they're made.
 - Keep PR-sized patches; avoid broad unrelated edits.
 - Document non-obvious choices in commit messages or short comments near the code that needs it.

KEYMAPS.md

@@ -2,6 +2,25 @@
 
 Living reference of every explicit keymap defined in this config. Use `:KeymapsGuide` to open this file inside Neovim in a floating window.
 
+## Session Management
+
+Session support is automatic but user-controlled:
+
+**Manual session creation** (one-time):
+```vim
+:mksession        " Creates Session.vim in current directory
+```
+
+**Auto-load/save** (via `lua/autocmds.lua`):
+- On startup: auto-loads `Session.vim` if it exists (unless files specified on command line)
+- On exit: auto-saves to `Session.vim` if it already exists
+- Sessions are per-directory and opt-in (just create one to start using)
+
+**Stop using a session**:
+```bash
+rm Session.vim    # Won't auto-create a new one
+```
+
 ## `lua/keymaps.lua`
 
 | Mode | Key | Description | Notes |

lua/autocmds.lua

@@ -99,4 +99,35 @@ vim.api.nvim_create_autocmd("FileType", {
 	end,
 })
 
+-- Session management: auto-load on startup, auto-save on exit (only if Session.vim exists)
+local session_aug = vim.api.nvim_create_augroup("SessionManagement", { clear = true })
+
+-- Auto-load Session.vim if it exists in the current directory
+vim.api.nvim_create_autocmd("VimEnter", {
+	group = session_aug,
+	pattern = "*",
+	nested = true, -- Allow other autocmds to fire after loading session
+	callback = function()
+		-- Only auto-load if:
+		-- 1. Session.vim exists in cwd
+		-- 2. No files were specified on command line (vim.fn.argc() == 0)
+		-- 3. Not started with nvim -S (check if we already loaded a session)
+		if vim.fn.argc() == 0 and vim.fn.filereadable("Session.vim") == 1 and vim.v.this_session == "" then
+			vim.cmd("source Session.vim")
+		end
+	end,
+})
+
+-- Auto-save session on exit, but ONLY if Session.vim already exists
+vim.api.nvim_create_autocmd("VimLeavePre", {
+	group = session_aug,
+	pattern = "*",
+	callback = function()
+		-- Only save if Session.vim exists (user manually created it)
+		if vim.fn.filereadable("Session.vim") == 1 then
+			vim.cmd("mksession! Session.vim")
+		end
+	end,
+})
+
 return {}