Skip to content

AGENTS.md

Latest commit

 

History

History
111 lines (83 loc) · 4.38 KB

AGENTS.md

File metadata and controls

111 lines (83 loc) · 4.38 KB
Raw

AGENTS.md

Notes for AI agents working in this repository.

Two things that change how you should act

1. This repository is public. It is public on purpose — it can be cloned without credentials when setting up a new or contract machine, which a private repo cannot. That makes it the wrong place for anything personal:

  • No personal filesystem paths, note-vault locations, or private repo names.
  • No private or work email addresses, tokens, hostnames, or client/employer names.
  • Machine-specific and personal settings belong in a local, untracked file, not in a commit here.

2. Edits are live. ~/.vim is a symlink to this repository, and the Neovim config is symlinked out of it:

~/.vim                          -> this repo
~/.config/nvim/init.vim         -> nvim_init.vim
~/.config/nvim/mac_appearance.vim -> mac_appearance.vim
~/.config/nvim/keymap           -> keymap/
~/.vimrc                        -> vimrc
~/.mvimrc                       -> mvimrc
~/.ideavimrc                    -> ideavimrc

There is no install or copy step: editing a file here changes the running configuration on the next launch. Conversely, a new Neovim-side file needs its own symlink into ~/.config/nvim/ or it will never be read.

Local machine settings

local.vim at the repository root is the one exception: it is ignored by Git and sourced conditionally by both nvim_init.vim and vimrc. Put personal paths, note locations, machine-specific provider paths, and private mappings there. Never force-add or commit it. Neovim loads it early so provider settings are available before plugins initialize; legacy Vim loads it last so local settings can override tracked defaults.

Verify the git identity before committing

git config --local --get user.email

Do this in every fresh clone. If it is empty or shows a private/work address, do not commit until the maintainer has configured a public or GitHub noreply address with git config --local user.email. Commit identities are permanently public; the repository-local setting prevents a machine's work identity from leaking into the history.

Layout

Two independent lineages. Do not assume a change to one affects the other.

editor plugin manager plugins live in state
vimrc plain vim / MacVim pathogen (autoload/pathogen.vim) bundle/ submodules legacy
nvim_init.vim Neovim vim-plug ~/.local/share/nvim/plugged active

The bundle/ submodules are not checked out — pathogen loads nothing, so the plain-vim side is effectively inert. Do not try to update, init, or "fix" those submodules unless explicitly asked; an empty bundle/ is the normal state here, not breakage.

Other files: mac_appearance.vim (macOS light/dark), keymap/ (Russian and Ukrainian phonetic layouts), ideavimrc, mvimrc, after/, syntax/, spell/.

nvim_init.vim: ordering constraint

The appearance block must stay at the end of the file, in this order:

  1. source ~/.config/nvim/mac_appearance.vim — sets 'background' from macOS.
  2. set termguicolors.
  3. The Cursor highlight function and 'guicursor'.
  4. colorscheme rose-pine — reads 'background' to pick dawn (light) or main (dark).

Moving the colorscheme earlier makes it paint the wrong variant on startup. See the README's Appearance section for why the cursor colour is set here rather than left to the terminal.

Verifying a change

This config is vimscript, not Lua. Load it headlessly rather than assuming it parses — errors are printed and the exit status stays 0, so read the output:

# loads clean, and reports what it resolved to
nvim -i NONE --headless -u nvim_init.vim \
  -c 'echo "bg=".&background."  scheme=".g:colors_name' -c 'qa'

# inspect a highlight group in a specific variant
nvim -i NONE --headless -u nvim_init.vim -c 'set background=dark' \
  -c 'redir=>o|silent hi Cursor|redir END|echo o' -c 'qa'

Anything that depends on the system appearance can be forced with -c 'set background=light|dark' instead of toggling macOS.

Known rough edges

  • 'pastetoggle' was removed in Neovim 0.10 and errors with E519. It is commented out; do not restore it.
  • deoplete + deoplete-jedi are the current completion stack. nvim_init.vim carries commented-out TODO blocks proposing an LSP/treesitter migration — those are notes, not pending work. Do not enable them uninvited.