NAVI // NAVIVIM FOR AGENTS

the contract.

The rules of the road for anyone — human or agent — working on NaviVim itself.

Mirrored from AGENTS.md in the NaviVim repo. The repo copy is the source of truth.

Share this file with humans and AI agents working on NaviVim. It is the contract for this project's editing experience. Source of truth: the NaviVim repo (~/NaviVim, live at ~/.config/nvim via symlink). Edit the repo, never the symlink target directly.

1. What this is

NaviVim is the default text-editing experience for Navi — a minimal, Debian-based, tiling-focused Linux environment. The distro has its own AGENTS.md and handbook; everything below is about NaviVim.

NaviVim's ambition is a premier, best-in-class Neovim experience: an in-terminal IDE that feels like a cohesive whole with the system it ships on — welcoming to newcomers (especially people arriving from VSCode) without dumbing anything down for veterans. Concretely that means:

2. Layout

~/.config/nvim/
  init.lua                        -> requires config.options, config.keymaps, config.autocmds, config.lazy
  lua/config/options.lua          -> vimrc migration + IDE defaults
  lua/config/keymaps.lua          -> all user keymaps (leader = <Space>)
  lua/config/autocmds.lua         -> yank-hl, resize, no-autocomment, transparency re-apply
  lua/config/lazy.lua             -> lazy.nvim bootstrap, spec = { import = "plugins" }
  lua/plugins/sidebar.lua         -> nvim-tree (toggleable file explorer)
  lua/plugins/completion.lua      -> blink.cmp + LuaSnip (toggleable autocomplete)
  lua/plugins/search.lua          -> telescope + fzf-native, flash, hlslens, which-key
  lua/plugins/lsp.lua             -> mason + native vim.lsp.config/enable + fidget + conform + nvim-lint
  lua/plugins/treesitter.lua      -> syntax + indent, polyglot parsers
  lua/plugins/ui.lua              -> lualine, bufferline, alpha dashboard, indent-blankline
                                  (dashboard: 8 shortcut buttons, random tip-of-day footer,
                                   boot reveal + neon header cycling when nightshadeNeon is active)
  lua/plugins/git.lua             -> gitsigns + lazygit
  lua/plugins/editing.lua         -> Comment, autopairs, surround, todo-comments
  lua/plugins/terminal.lua        -> toggleterm + vim-tmux-navigator + persistence
  lua/plugins/theme.lua           -> reads ~/.config/omaterm/nvim.theme, default nightshadeNeon
  colors/nightshadeNeon.lua       -> house colorscheme (#ff10f0 #39ff14 #00ffff #ff3131 #ffffff on #000000)
  after/plugin/transparency.lua   -> startup transparency trigger
  after/syntax/uxntal.vim         -> ported from ~/.vim/pack/plugins/start/uxntal.vim
  after/ftdetect/uxntal.vim       -> ported uxntal filetype detection
  after/ftdetect/gemtext.vim      -> belt-and-braces .gmi detection (syntax itself
                                     ships with Neovim; nightshadeNeon styles its
                                     Heading/LinkURL/Quote/List groups)

3. Key UX contract (do not break)

Leader is Space, tapped in sequence (e.g. <leader>ff = Space, f, f). Pressing Space and waiting shows which-key with every option.

Feature Keys Notes
Sidebar toggle <C-n>, <leader>e, focus <leader>o nvim-tree, 32 cols left
Autocomplete toggle <leader>ua flips vim.g.navi_completion_enabled, blink.cmp enabled() respects it
Search in file /, n/N centered, <Esc> clears ignorecase+smartcase, hlslens counts, s flash-jump
Project find/grep <leader>ff files, <leader>fg grep, <leader>fb buffers, <leader>/ buffer-fuzzy Telescope + ripgrep + fd
Save/quit <C-s> / <leader>w, <leader>q VSCode muscle memory
Splits <leader>\|, <leader>-, <C-h/j/k/l> tmux-aware via vim-tmux-navigator
Buffers <S-h> / <S-l>, <leader>bd bufferline
LSP gd gr K <leader>rn <leader>ca [d ]d attached via LspAttach autocmd
Format toggle <leader>uf conform.nvim, default ON
Git <leader>gg lazygit, <leader>gp/gb, [h/]h gitsigns gutter
Terminal <leader>tt or <C-\>, <Esc><Esc> exits term mode toggleterm
Session <leader>qs restore persistence.nvim
Relative numbers <leader>un toggles default ON with number

4. Dependencies (for distribution)

5. Commands agents should use

# install / sync plugins (headless)
nvim --headless "+Lazy! sync" +qa
# health
nvim --headless "+checkhealth" +qa
# LSP servers UI
nvim "+Mason"
# smoke test toggles (manual)
nvim -c "NvimTreeToggle" -c "Telescope find_files"

Test matrix before shipping: open .py .js .ts .lua .c .md .tal files, toggle sidebar (<C-n>), toggle completion (<leader>ua then type in insert mode), / search + Esc, :Telescope live_grep, :checkhealth clean (except optional clipboard warnings outside tmux).

6. Rules for contributors / agents

  1. Hand-rolled only — do NOT reintroduce LazyVim/NvChad as a dependency.
  2. Every new plugin gets its own lua/plugins/*.lua file + keymaps with desc (which-key discoverable).
  3. Every toggle (completion, format, tree) must have a <leader>u* or documented key and persist via vim.g.navi_*.
  4. Keep standalone-nvim working; tmux integration must degrade gracefully (see vim-tmux-navigator fallback to <C-w> maps).
  5. Keep transparency behavior: ColorScheme autocmd in config/autocmds.lua + startup trigger. Add new float groups there, not inline.
  6. Theme changes go through plugins/theme.lua + omaterm/nvim.theme, never hardcoded colorscheme elsewhere.
  7. Run stylua (2-space, 120 col per stylua.toml) on Lua edits.

7. Roadmap / ideas (not yet built)