consolidate and update agent instruction files

AGENTS.md

@@ -158,6 +158,43 @@ This repository is being migrated to a modern, minimal Neovim setup driven by Lu
 - **Features**: Incremental selection (CR/BS), textobjects (functions, classes, parameters), autotag
 - **Custom queries**: `after/queries/css/highlights.scm`, `after/queries/html/highlights.scm`
 
+### Session Management
+- **Auto-load**: On `VimEnter`, loads `Session.vim` if it exists (unless files specified on command line)
+- **Auto-save**: On `VimLeavePre`, saves to `Session.vim` if it already exists
+- **Manual control**: Create with `:mksession` to enable; delete to disable
+- **Per-directory**: Sessions are opt-in and workspace-specific
+
+## Developer Workflows
+
+### Testing Changes
+```bash
+# Quick syntax check
+nvim --headless -c 'lua print("Config loads")' -c 'quitall'
+
+# Check LSP status in test workspace
+cd ~/.config/nvim/WORKSPACE_TEST
+nvim site/external.php  # Then :LspInfo
+
+# Validate goto-definition for external libs
+# In external.php, cursor on Util::greetExternal, press gd
+```
+
+### Validation Workspaces
+- `WORKSPACE_TEST/`: PHP project with `.nvim.lua` and `.git`
+- `EXTERNAL_TEST/`: External library referenced via includePaths
+- Test that `gd` resolves symbols in EXTERNAL_TEST from WORKSPACE_TEST
+
+## Common Issues
+
+### lua_ls Won't Start
+Mason-installed lua_ls may fail with missing `libbfd-2.38-system.so`. Install via system package manager instead.
+
+### LSP Root Detection
+If parent repo picked as root, create empty `.git` or `.nvimroot` marker in intended workspace root.
+
+### Duplicate gd Results (Fixed)
+Was caused by settings loading at wrong time; fixed by using `LspAttach` autocmd with actual `root_dir`.
+
 ## Process
 - 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.