fix: remaining usability and design improvements

.vimrc: - Remove path+=** (hangs on large repos with node_modules) - Add plugin guards for FZF, Git, ALE, Markdown, EasyMotion, UndoTree mappings (prevent E492 when plugins not loaded) - Replace SmartFiles system() subprocess with isdirectory/finddir (no more synchronous fork on every Ctrl+p) - Remove duplicate SLDefineColors VimEnter call (ColorScheme alone suffices) - Convert all remaining nmap/map to nnoremap/noremap (eliminate recursive mapping risk and visual/operator-pending mode contamination) - Expand cheat sheet with spell checking, utilities, window resize, F-key toggles, EasyMotion line motions, buffer management get.sh: - Support NO_COLOR and non-TTY output - Show version tag or commit hash after clone/pull QUICKSTART.md: - Warn about first-launch plugin install (30-60s wait) - Note that some language servers need Node.js
fix: usability and design improvements across .vimrc, install.sh, README
2026-05-10 19:10:59 +08:00 · 2026-04-15 10:15:07 +08:00 · 2026-04-15 10:08:10 +08:00 · 2026-04-15 09:57:26 +08:00
6 changed files with 284 additions and 146 deletions
--- a/.vimrc
+++ b/.vimrc
@ -44,7 +44,7 @@ set wildmode=list:longest
 set wildignorecase
 set wildignore=*.docx,*.jpg,*.png,*.gif,*.pdf,*.pyc,*.exe,*.flv,*.img,*.xlsx
 set wildignore+=*/node_modules/*,*/.git/*,*/__pycache__/*,*/dist/*,*/build/*
-set path+=**
+" path+=** removed: hangs on large repos (node_modules); use Ctrl+p (FZF) instead
 set mouse=a
 set encoding=utf-8
 set foldmethod=indent
@ -96,7 +96,10 @@ let data_dir = has('nvim') ? stdpath('data') . '/site' : '~/.vim'
 if empty(glob(data_dir . '/autoload/plug.vim'))
    silent execute '!curl -fLo '.data_dir.'/autoload/plug.vim --create-dirs '
        \ . 'https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim'
-    autocmd VimEnter * PlugInstall --sync | source $MYVIMRC
+    augroup PlugBootstrap
+        autocmd!
+        autocmd VimEnter * PlugInstall --sync | source $MYVIMRC
+    augroup END
 endif

 call plug#begin('~/.vim/plugged')
@ -157,6 +160,9 @@ call plug#end()
 " ============================================================================

 if g:has_true_color && has('termguicolors') && !g:is_tty
+    " Required for true color inside tmux
+    let &t_8f = "\<Esc>[38;2;%lu;%lu;%lum"
+    let &t_8b = "\<Esc>[48;2;%lu;%lu;%lum"
    set termguicolors
 endif

@ -208,42 +214,42 @@ set smartindent
 let mapleader = ","

 " Saving / quitting
-nmap <leader>w :w!<cr>
-nmap <leader>q :q<cr>
-nmap <leader>x :x<cr>
+nnoremap <leader>w :w!<cr>
+nnoremap <leader>q :q<cr>
+nnoremap <leader>x :x<cr>

 " Clear search highlight
-map <silent> <leader><cr> :noh<cr>
+nnoremap <silent> <leader><cr> :noh<cr>

 " Buffer navigation
-map <leader>bd :Bclose<cr>
-map <leader>ba :bufdo bd<cr>
-map <leader>l  :bnext<cr>
-map <leader>h  :bprevious<cr>
+nnoremap <leader>bd :Bclose<cr>
+nnoremap <leader>ba :bufdo bd<cr>
+nnoremap <leader>l  :bnext<cr>
+nnoremap <leader>h  :bprevious<cr>

 " Tab management
-map <leader>tn :tabnew<cr>
-map <leader>to :tabonly<cr>
-map <leader>tc :tabclose<cr>
-map <leader>tm :tabmove
-map <leader>t<leader> :tabnext<cr>
+nnoremap <leader>tn :tabnew<cr>
+nnoremap <leader>to :tabonly<cr>
+nnoremap <leader>tc :tabclose<cr>
+nnoremap <leader>tm :tabmove
+nnoremap <leader>t<leader> :tabnext<cr>

 let g:lasttab = 1
-nmap <Leader>tl :exe "tabn ".g:lasttab<CR>
+nnoremap <Leader>tl :exe "tabn ".g:lasttab<CR>
 augroup ChopstickTabHistory
    autocmd!
    autocmd TabLeave * let g:lasttab = tabpagenr()
 augroup END

-map <leader>te :tabedit <C-r>=expand("%:p:h")<cr>/
-map <leader>cd :lcd %:p:h<cr>:pwd<cr>
+nnoremap <leader>te :tabedit <C-r>=expand("%:p:h")<cr>/
+nnoremap <leader>cd :lcd %:p:h<cr>:pwd<cr>

 " File browser (netrw — built-in, no plugins)
 nnoremap <leader>e :Explore<CR>
 nnoremap <leader>E :Vexplore<CR>

-" Remap 0 to first non-blank
-map 0 ^
+" Remap 0 to first non-blank (all modes intentional)
+noremap 0 ^

 " Reselect last paste
 nnoremap gV `[v`]
@ -252,18 +258,18 @@ nnoremap gV `[v`]
 cnoremap <C-p> <Up>
 cnoremap <C-n> <Down>

-" Move lines
-nmap <M-j> mz:m+<cr>`z
-nmap <M-k> mz:m-2<cr>`z
-vnoremap J :m '>+1<CR>gv=gv
-vnoremap K :m '<-2<CR>gv=gv
+" Move lines (Alt+j / Alt+k in both normal and visual mode)
+nnoremap <M-j> :m .+1<CR>==
+nnoremap <M-k> :m .-2<CR>==
+vnoremap <M-j> :m '>+1<CR>gv=gv
+vnoremap <M-k> :m '<-2<CR>gv=gv

 " Spell checking
-map <leader>ss :setlocal spell!<cr>
-map <leader>sn ]s
-map <leader>sp [s
-map <leader>sa zg
-map <leader>s? z=
+nnoremap <leader>ss :setlocal spell!<cr>
+nnoremap <leader>sn ]s
+nnoremap <leader>sp [s
+nnoremap <leader>sa zg
+nnoremap <leader>s? z=

 " Toggle modes
 set pastetoggle=<F2>
@ -348,19 +354,21 @@ let g:netrw_list_hide   .= ',\.pyc$,node_modules,\.git,__pycache__,\.DS_Store'

 " Ctrl+p: git-aware file search (GFiles inside repo, Files outside)
 function! s:SmartFiles() abort
-    if !empty(system('git rev-parse --show-toplevel 2>/dev/null'))
+    if isdirectory('.git') || finddir('.git', '.;') !=# ''
        GFiles
    else
        Files
    endif
 endfunction

-map <C-p>     :call <SID>SmartFiles()<CR>
-map <leader>b :Buffers<CR>
-map <leader>rg :Rg<CR>
-map <leader>rG :Rg -F <C-r><C-w><CR>
-map <leader>rt :Tags<CR>
-map <leader>gF :GFiles<CR>
+if exists('g:plugs["fzf.vim"]')
+    nnoremap <C-p>     :call <SID>SmartFiles()<CR>
+    nnoremap <leader>b :Buffers<CR>
+    nnoremap <leader>rg :Rg<CR>
+    nnoremap <leader>rG :RgWord<CR>
+    nnoremap <leader>rt :Tags<CR>
+    nnoremap <leader>gF :GFiles<CR>
+endif

 let g:fzf_layout = { 'down': '40%' }

@ -384,6 +392,19 @@ else
    command! -bang GFiles call fzf#vim#gitfiles('', fzf#vim#with_preview(), <bang>0)
 endif

+" RgWord: fixed-string search for word under cursor (flags before --)
+if g:is_tty
+    command! -bang -nargs=* RgWord
+        \ call fzf#vim#grep(
+        \   'rg --column --line-number --no-heading --color=always --smart-case -F -- '
+        \   .shellescape(expand('<cword>')), 1, <bang>0)
+else
+    command! -bang -nargs=* RgWord
+        \ call fzf#vim#grep(
+        \   'rg --column --line-number --no-heading --color=always --smart-case -F -- '
+        \   .shellescape(expand('<cword>')), 1, fzf#vim#with_preview(), <bang>0)
+endif
+
 " ============================================================================
 " => GitGutter
 " ============================================================================
@ -439,9 +460,11 @@ let g:ale_lint_on_text_changed = 'normal'
 let g:ale_lint_on_insert_leave = 1
 let g:ale_lint_on_enter        = 1

-nmap <silent> [e :ALEPrevious<cr>
-nmap <silent> ]e :ALENext<cr>
-nmap <silent> <leader>aD :ALEDetail<cr>
+if exists('g:plugs["ale"]')
+    nnoremap <silent> [e :ALEPrevious<cr>
+    nnoremap <silent> ]e :ALENext<cr>
+    nnoremap <silent> <leader>aD :ALEDetail<cr>
+endif

 " ============================================================================
 " => vim-go
@ -450,8 +473,8 @@ nmap <silent> <leader>aD :ALEDetail<cr>
 " vim-lsp (gopls) handles all Go intelligence; disable vim-go's own LSP layer
 let g:go_gopls_enabled            = 0
 let g:go_code_completion_enabled  = 0
-let g:go_def_mode                 = 'gopls'
-let g:go_info_mode                = 'gopls'
+let g:go_def_mode                 = 'godef'
+let g:go_info_mode                = 'godef'
 let g:go_fmt_autosave             = 0  " ALE handles format-on-save
 let g:go_imports_autosave         = 0
 let g:go_highlight_types          = 1
@ -490,7 +513,11 @@ let g:lsp_signs_warning     = {'text': '!'}
 let g:lsp_signs_information = {'text': 'i'}
 let g:lsp_signs_hint        = {'text': '>'}

-set completeopt=menuone,noinsert,noselect
+if has('patch-8.1.1517')
+    set completeopt=menuone,noinsert,noselect,popup
+else
+    set completeopt=menuone,noinsert,noselect
+endif
 set pumheight=15
 let g:asyncomplete_auto_popup       = 1
 let g:asyncomplete_auto_completeopt = 1
@ -550,15 +577,19 @@ let g:vim_markdown_follow_anchor      = 1
 let g:vim_markdown_new_list_item_indent = 2
 let g:vim_markdown_strikethrough      = 1

-" Table of contents in quickfix
-nnoremap <leader>mt :Toc<CR>
+" Table of contents (side window)
+if exists('g:plugs["vim-markdown"]')
+    nnoremap <leader>mt :Toc<CR>
+endif

 " ============================================================================
 " => previm  (Markdown browser preview)
 " ============================================================================

 " <leader>mp   open live-reloading preview in browser
-nnoremap <leader>mp :PrevimOpen<CR>
+if exists('g:plugs["previm"]')
+    nnoremap <leader>mp :PrevimOpen<CR>
+endif
 let g:previm_enable_realtime = 1

 " ============================================================================
@ -568,19 +599,22 @@ let g:previm_enable_realtime = 1
 let g:EasyMotion_do_mapping = 0
 let g:EasyMotion_smartcase  = 1

-" s + two chars: jump anywhere on screen
-nmap s <Plug>(easymotion-overwin-f2)
-
-" J/K: line motions
-map <Leader>j <Plug>(easymotion-j)
-map <Leader>k <Plug>(easymotion-k)
+if exists('g:plugs["vim-easymotion"]')
+    " s + two chars: jump anywhere on screen
+    nmap s <Plug>(easymotion-overwin-f2)
+    " Line motions
+    nmap <Leader>j <Plug>(easymotion-j)
+    nmap <Leader>k <Plug>(easymotion-k)
+endif

 " ============================================================================
 " => UndoTree
 " ============================================================================

-nnoremap <F5>       :UndotreeToggle<CR>
-nnoremap <leader>u  :UndotreeToggle<CR>
+if exists('g:plugs["undotree"]')
+    nnoremap <F5>       :UndotreeToggle<CR>
+    nnoremap <leader>u  :UndotreeToggle<CR>
+endif

 " ============================================================================
 " => IndentLine  (non-TTY only)
@ -604,12 +638,12 @@ endif

 if exists('g:plugs["vim-startify"]')
    let g:startify_custom_header = [
-        \ '  ███╗   ███╗ ██╗███╗   ██╗ ██████╗ ███████╗ █████╗ ███╗   ███╗ █████╗  ',
-        \ '  ████╗ ████║███║████╗  ██║██╔════╝ ██╔════╝██╔══██╗████╗ ████║██╔══██╗ ',
-        \ '  ██╔████╔██║╚██║██╔██╗ ██║██║  ███╗███████╗███████║██╔████╔██║███████║  ',
-        \ '  ██║╚██╔╝██║ ██║██║╚██╗██║██║   ██║╚════██║██╔══██║██║╚██╔╝██║██╔══██║ ',
-        \ '  ██║ ╚═╝ ██║ ██║██║ ╚████║╚██████╔╝███████║██║  ██║██║ ╚═╝ ██║██║  ██║ ',
-        \ '  ╚═╝     ╚═╝ ╚═╝╚═╝  ╚═══╝ ╚═════╝ ╚══════╝╚═╝  ╚═╝╚═╝     ╚═╝╚═╝  ╚═╝',
+        \ '         ██████╗██╗  ██╗ ██████╗ ██████╗ ███████╗████████╗██╗ ██████╗██╗  ██╗███████╗',
+        \ '        ██╔════╝██║  ██║██╔═══██╗██╔══██╗██╔════╝╚══██╔══╝██║██╔════╝██║ ██╔╝██╔════╝',
+        \ '        ██║     ███████║██║   ██║██████╔╝███████╗   ██║   ██║██║     █████╔╝ ███████╗',
+        \ '        ██║     ██╔══██║██║   ██║██╔═══╝ ╚════██║   ██║   ██║██║     ██╔═██╗ ╚════██║',
+        \ '        ╚██████╗██║  ██║╚██████╔╝██║     ███████║   ██║   ██║╚██████╗██║  ██╗███████║',
+        \ '         ╚═════╝╚═╝  ╚═╝ ╚═════╝ ╚═╝     ╚══════╝   ╚═╝   ╚═╝ ╚═════╝╚═╝  ╚═╝╚══════╝',
        \ '',
        \ ]

@ -620,11 +654,16 @@ if exists('g:plugs["vim-startify"]')
        \ { 'type': 'bookmarks', 'header': ['   Bookmarks']    },
        \ ]

-    let g:startify_bookmarks = [
-        \ {'v': '~/.vimrc'},
-        \ {'z': '~/.zshrc'},
-        \ {'b': '~/.bashrc'},
-        \ ]
+    let g:startify_bookmarks = [{'v': '~/.vimrc'}]
+    if filereadable(expand('~/.zshrc'))
+        call add(g:startify_bookmarks, {'z': '~/.zshrc'})
+    endif
+    if filereadable(expand('~/.bashrc'))
+        call add(g:startify_bookmarks, {'b': '~/.bashrc'})
+    endif
+    if filereadable(expand('~/.config/fish/config.fish'))
+        call add(g:startify_bookmarks, {'f': '~/.config/fish/config.fish'})
+    endif

    let g:startify_session_persistence = 1
    let g:startify_session_autoload    = 1
@ -685,7 +724,6 @@ endfunction
 augroup SLColors
    autocmd!
    autocmd ColorScheme * call s:SLDefineColors()
-    autocmd VimEnter    * call s:SLDefineColors()
 augroup END

 " Current mode → [label, highlight-group]
@ -781,7 +819,7 @@ endfunc
 " Suppress comment continuation on Enter / o / O
 augroup ChopstickFormatOptions
    autocmd!
-    autocmd BufEnter * setlocal formatoptions-=c formatoptions-=r formatoptions-=o
+    autocmd FileType * setlocal formatoptions-=c formatoptions-=r formatoptions-=o
 augroup END

 " Auto-disable paste mode on leaving insert
@ -790,13 +828,6 @@ augroup ChopstickPaste
    autocmd InsertLeave * set nopaste
 augroup END

-" Strip trailing whitespace on save (real files only)
-augroup ChopstickCleanup
-    autocmd!
-    autocmd BufWritePre *
-        \ if empty(&buftype) && !empty(expand('<afile>')) | call CleanExtraSpaces() | endif
-augroup END
-
 augroup ChopstickFiletype
    autocmd!

@ -891,7 +922,7 @@ nnoremap <leader><leader> <c-^>
 nnoremap <leader>W :%s/\s\+$//<CR>:let @/=''<CR>

 " Source helpers
-nnoremap <leader>so :source %<CR>
+nnoremap <leader>so :if &filetype ==# 'vim' <Bar> source % <Bar> echo "Sourced " . expand('%') <Bar> else <Bar> echo "Not a vim file" <Bar> endif<CR>
 nnoremap <leader>ev :edit $MYVIMRC<CR>
 nnoremap <leader>sv :source $MYVIMRC<CR>:echo "vimrc reloaded"<CR>

@ -899,11 +930,13 @@ nnoremap <leader>sv :source $MYVIMRC<CR>:echo "vimrc reloaded"<CR>
 nnoremap <leader>* :%s/\<<C-r><C-w>\>//g<Left><Left>

 " Copy path / filename to clipboard
-nnoremap <leader>cp :let @+ = expand("%:p")<CR>:echo "Copied: " . expand("%:p")<CR>
-nnoremap <leader>cf :let @+ = expand("%:t")<CR>:echo "Copied: " . expand("%:t")<CR>
+if has('clipboard')
+    nnoremap <leader>cp :let @+ = expand("%:p")<CR>:echo "Copied: " . expand("%:p")<CR>
+    nnoremap <leader>cf :let @+ = expand("%:t")<CR>:echo "Copied: " . expand("%:t")<CR>
+endif

 " Scratch markdown buffer
-map <leader>m :e ~/buffer.md<cr>
+nnoremap <leader>ms :e ~/buffer.md<cr>

 " Auto-create parent directories on save
 function! s:MkNonExDir(file, buf)
@ -926,12 +959,14 @@ augroup END
 " => Git Shortcuts
 " ============================================================================

-nnoremap <leader>gs :Git status<CR>
-nnoremap <leader>gc :Git commit<CR>
-nnoremap <leader>gp :Git push<CR>
-nnoremap <leader>gl :Git pull<CR>
-nnoremap <leader>gd :Gdiff<CR>
-nnoremap <leader>gb :Git blame<CR>
+if exists('g:plugs["vim-fugitive"]')
+    nnoremap <leader>gs :Git status<CR>
+    nnoremap <leader>gc :Git commit<CR>
+    nnoremap <leader>gp :Git push<CR>
+    nnoremap <leader>gl :Git pull<CR>
+    nnoremap <leader>gd :Gdiffsplit<CR>
+    nnoremap <leader>gb :Git blame<CR>
+endif

 " ============================================================================
 " => Terminal Integration
@ -965,9 +1000,8 @@ augroup END
 function! LargeFileSettings()
    setlocal bufhidden=unload
    setlocal undolevels=-1
-    setlocal eventignore+=FileType
    setlocal noswapfile
-    setlocal syntax=OFF
+    setlocal syntax=
    let b:ale_enabled = 0
    echo "Large file (>10 MB): syntax, undo, and linting disabled."
 endfunction
@ -977,7 +1011,7 @@ if g:is_tty
        autocmd!
        autocmd BufReadPre *
            \ if !empty(expand('<afile>')) && getfsize(expand('<afile>')) > 512000 |
-            \     setlocal syntax=OFF |
+            \     setlocal syntax= |
            \ endif
    augroup END

@ -1051,9 +1085,20 @@ function! s:CheatSheet() abort
        \ 'EDITING',
        \ '  gc            Toggle comment (visual mode too)',
        \ '  s + 2 chars   EasyMotion — jump anywhere on screen',
-        \ '  ,u            Undo tree (visual branch history)',
+        \ '  ,j / ,k       EasyMotion — line motions',
+        \ '  ,u / F5       Undo tree (visual branch history)',
        \ '  ,y / ,Y       Yank / yank line to system clipboard',
-        \ '  ,p / ,P       Paste from system clipboard (after / before)',
+        \ '  ,p / ,P       Paste from system clipboard',
+        \ '  Alt+j / Alt+k Move line down / up (also visual mode)',
+        \ '  ,F            Re-indent entire file',
+        \ '  ,W            Strip trailing whitespace',
+        \ '  ,*            Search and replace word under cursor',
+        \ '',
+        \ 'SPELLING',
+        \ '  ,ss           Toggle spell checking',
+        \ '  ,sn / ,sp     Next / prev misspelling',
+        \ '  ,sa           Add word to dictionary',
+        \ '  ,s?           Suggest corrections',
        \ '',
        \ 'GIT',
        \ '  ,gs  Status   ,gd  Diff   ,gb  Blame',
@ -1062,8 +1107,19 @@ function! s:CheatSheet() abort
        \ 'WINDOWS & PANES',
        \ '  Ctrl+h/j/k/l  Navigate Vim splits and tmux panes',
        \ '  ,h / ,l       Prev / next buffer',
+        \ '  ,bd            Close buffer (keep layout)',
+        \ '  ,tn / ,tc     New tab / close tab  |  ,tl  Last tab',
        \ '  ,tv / ,th     Open terminal (vertical / horizontal)',
        \ '  Esc Esc       Exit terminal mode',
+        \ '  ,= / ,-       Resize height (grow / shrink)',
+        \ '  ,+ / ,_       Resize width  (grow / shrink)',
+        \ '',
+        \ 'UTILITIES',
+        \ '  ,ev / ,sv     Edit / reload ~/.vimrc',
+        \ '  ,cp / ,cf     Copy file path / filename to clipboard',
+        \ '  ,ms           Open scratch markdown buffer',
+        \ '  ,cd           Change CWD to current file directory',
+        \ '  F2  Paste   F3  Line#   F4  Relative#   F6  Invisible',
        \ '',
        \ 'SESSION',
        \ '  :Obsess       Start tracking session',
@ -1081,7 +1137,7 @@ nnoremap <silent> <leader>? :call <SID>CheatSheet()<CR>
 " ============================================================================

 " Show syntax highlight stack for word under cursor
-nmap <leader>sh :call <SID>SynStack()<CR>
+nnoremap <leader>sh :call <SID>SynStack()<CR>
 function! <SID>SynStack()
    if !exists("*synstack") | return | endif
    echo map(synstack(line('.'), col('.')), 'synIDattr(v:val, "name")')
--- a/QUICKSTART.md
+++ b/QUICKSTART.md
@ -56,6 +56,10 @@ vim .        # startup dashboard, current directory listed
 vim myfile   # edit a specific file
 ```

+> **First launch:** Vim will automatically install plugins on the first open
+> (takes 30–60 seconds depending on network). This is normal — wait for it
+> to finish, then restart Vim.
+
 ---

 ## Step 3: Set Up LSP
@ -67,7 +71,9 @@ Open a source file, then run:
 ```

 This auto-detects the filetype and installs the correct language server.
-No Node.js required — vim-lsp runs on pure VimScript.
+vim-lsp itself runs on pure VimScript — no Node.js required. However,
+some language servers (JS/TS, HTML, CSS, JSON, YAML) are npm packages
+that need Node.js to run. Python, Go, and Rust servers don't need it.

 Check status:
 ```vim
@ -142,7 +148,7 @@ K               Show documentation
 | Key | Action |
 |-----|--------|
 | `,mp` | Open live preview in browser |
-| `,mt` | Table of contents |
+| `,mt` | Table of contents (side window) |
 | `zr` / `zm` | Unfold / fold all headings |

 Formatting in the buffer is live: `**bold**` renders as bold,
--- a/README.md
+++ b/README.md
@ -86,11 +86,10 @@ cd ~/.vim && ./install.sh
 3. Backs up existing `~/.vimrc`, then symlinks `~/.vimrc → ~/.vim/.vimrc`
 4. Installs vim-plug and runs `:PlugInstall`
 5. Offers to install system tools (ripgrep, fzf, ctags, shellcheck, hadolint, marksman)
-6. Offers to install Node.js via nvm (for npm formatters — optional)
-7. Offers to install npm formatters (prettier, eslint, etc.)
-8. Offers to install Python formatters/linters (black, isort, flake8, etc.)
-9. Offers to install Go tools (gopls, goimports, staticcheck)
-10. Offers to append vim-tmux-navigator bindings to `~/.tmux.conf`
+6. Offers to install npm formatters (prettier, eslint, etc.) — requires Node.js
+7. Offers to install Python formatters/linters (black, isort, flake8, etc.)
+8. Offers to install Go tools (gopls, goimports, staticcheck)
+9. Offers to append vim-tmux-navigator bindings to `~/.tmux.conf`

 **Supported platforms:** macOS (Homebrew), Debian/Ubuntu (apt), Arch (pacman), Fedora (dnf).

@ -125,6 +124,10 @@ Supported languages and their servers:
 | Markdown | marksman |
 | SQL | sqls |

+**Note:** While vim-lsp itself needs no Node.js, some language servers (TypeScript,
+HTML, CSS, JSON, YAML) are npm packages that require Node.js to run. Python (pylsp),
+Go (gopls), and Rust (rust-analyzer) language servers do not need Node.js.
+
 **Markdown LSP** requires `marksman` as a standalone binary:

 ```bash
@ -150,10 +153,12 @@ Press `,?` at any time to open the built-in cheat sheet.
 | `,E` | Open netrw in vertical split |
 | `,b` | Search open buffers (FZF) |
 | `,rg` | Project-wide search (ripgrep + FZF) |
-| `,rG` | Ripgrep for word under cursor |
+| `,rG` | Ripgrep word under cursor (fixed-string) |
 | `,,` | Switch to last file |
 | `,l` / `,h` | Next / previous buffer |
 | `,bd` | Close current buffer (preserves window layout) |
+| `,wa` | Save all open buffers |
+| `,cd` | Change working directory to current file's directory |

 ### Code Intelligence (vim-lsp)

@ -179,7 +184,7 @@ Press `,?` at any time to open the built-in cheat sheet.
 | Key | Action |
 |-----|--------|
 | `,mp` | Open live preview in browser (previm) |
-| `,mt` | Table of contents |
+| `,mt` | Table of contents (side window) |
 | `zr` / `zm` | Unfold / fold all headings |

 ### Git (vim-fugitive)
@ -202,8 +207,14 @@ Press `,?` at any time to open the built-in cheat sheet.
 | `Space` | Toggle code fold |
 | `Y` | Yank to end of line |
 | `Ctrl+d` / `Ctrl+u` | Half-page scroll, cursor centred |
-| `Alt+j` / `Alt+k` | Move line down / up |
+| `Alt+j` / `Alt+k` | Move line down / up (normal and visual) |
 | `,u` | Undo tree (visual branch history) |
+| `F2` | Toggle paste mode |
+| `F3` / `F4` | Toggle line numbers / relative numbers |
+| `F5` | Toggle undo tree |
+| `F6` | Toggle invisible characters |
+| `gV` | Reselect last paste |
+| `//` | Search visual selection |

 ### Survival

@ -211,7 +222,8 @@ Press `,?` at any time to open the built-in cheat sheet.
 |-----|--------|
 | `jk` | Exit insert mode |
 | `Esc` | Exit insert / visual mode |
-| `Ctrl+s` | Save |
+| `jk` | Exit insert mode |
+| `Ctrl+s` | Save (any mode) |
 | `,w` | Save |
 | `,x` | Save and quit |
 | `,q` | Quit |
@ -226,6 +238,13 @@ Press `,?` at any time to open the built-in cheat sheet.
 | `Esc Esc` | Exit terminal mode |
 | `,tn` / `,tc` | New tab / close tab |
 | `,tl` | Toggle to last tab |
+| `,ev` / `,sv` | Edit / reload `~/.vimrc` |
+| `,cp` / `,cf` | Copy file path / filename to clipboard |
+| `,*` | Search and replace word under cursor |
+| `,F` | Re-indent entire file |
+| `,W` | Strip trailing whitespace |
+| `,ms` | Open scratch markdown buffer |
+| `,ss` | Toggle spell checking |

 ---

@ -253,7 +272,7 @@ No Node.js required. Uses `open` (macOS) or `xdg-open` (Linux).
 ### Table of contents

 ```vim
-,mt    " open TOC in a quickfix window — press Enter to jump to heading
+,mt    " open TOC in a side window — press Enter to jump to heading
 ```

 ---
@ -307,7 +326,7 @@ bind-key -n 'C-l' if-shell "$is_vim" 'send-keys C-l' 'select-pane -R'

 ### TTY / SSH Support

-Detected automatically when `$TERM` is `linux` or `screen`. In TTY mode:
+Detected automatically when `$TERM` is unset, `dumb`, `linux`, `screen`, or contains `builtin`. In TTY mode:

 - True colour and cursorline disabled
 - FZF preview windows disabled
--- a/coc-settings.json
+++ b/coc-settings.json
@ -6,8 +6,5 @@
      "filetypes": ["markdown"],
      "rootPatterns": [".git", ".marksman.toml"]
    }
-  },
-  "coc.preferences.formatOnSaveFiletypes": [
-    "markdown"
-  ]
+  }
 }
--- a/get.sh
+++ b/get.sh
@ -10,7 +10,11 @@ set -eo pipefail
 REPO="https://github.com/m1ngsama/chopsticks.git"
 DEST="$HOME/.vim"

-GREEN='\033[0;32m'; YELLOW='\033[1;33m'; RED='\033[0;31m'; BOLD='\033[1m'; NC='\033[0m'
+if [[ -t 1 ]] && [[ -z "${NO_COLOR:-}" ]]; then
+    GREEN='\033[0;32m'; YELLOW='\033[1;33m'; RED='\033[0;31m'; BOLD='\033[1m'; NC='\033[0m'
+else
+    GREEN=''; YELLOW=''; RED=''; BOLD=''; NC=''
+fi
 ok()   { echo -e "${GREEN}[OK]${NC}  $1"; }
 warn() { echo -e "${YELLOW}[!]${NC}  $1"; }
 die()  { echo -e "${RED}[FATAL]${NC} $1" >&2; exit 1; }
@ -42,7 +46,7 @@ if [[ -d "$DEST/.git" ]]; then
    warn "$DEST already exists — pulling latest changes"
    git -C "$DEST" pull --ff-only origin main 2>/dev/null || \
        warn "Could not pull latest — using existing version (run: git -C ~/.vim pull)"
-    ok "Repository updated"
+    ok "Repository updated ($(git -C "$DEST" describe --tags 2>/dev/null || git -C "$DEST" rev-parse --short HEAD))"
 elif [[ -d "$DEST" ]]; then
    die "$HOME/.vim exists but is not a chopsticks git repo.
  Back it up first:  mv ~/.vim ~/.vim.bak
@ -50,7 +54,7 @@ elif [[ -d "$DEST" ]]; then
 else
    git clone --depth=1 "$REPO" "$DEST" || \
        die "Clone failed — check your network connection"
-    ok "Cloned to $DEST"
+    ok "Cloned to $DEST ($(git -C "$DEST" describe --tags 2>/dev/null || git -C "$DEST" rev-parse --short HEAD))"
 fi

 # ── Run installer ─────────────────────────────────────────────────────────────
--- a/install.sh
+++ b/install.sh
@ -1,23 +1,41 @@
 #!/usr/bin/env bash
 # install.sh - chopsticks vim configuration installer
-# Usage: cd /path/to/chopsticks && ./install.sh [--yes]
+# Usage: cd /path/to/chopsticks && ./install.sh [--yes] [--help]
 #
-# --yes  non-interactive: install all optional components automatically
+# --yes   non-interactive: install all optional components automatically
+# --help  show this help and exit

 set -eo pipefail

 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 AUTO_YES=0
-[[ "${1:-}" == "--yes" ]] && AUTO_YES=1
+for arg in "$@"; do
+    case "$arg" in
+        --yes)  AUTO_YES=1 ;;
+        --help|-h)
+            echo "Usage: ./install.sh [OPTIONS]"
+            echo ""
+            echo "Options:"
+            echo "  --yes    Non-interactive mode: select all defaults automatically"
+            echo "  --help   Show this help and exit"
+            echo ""
+            echo "Supported platforms: macOS (brew), Debian/Ubuntu (apt), Arch (pacman), Fedora (dnf)"
+            exit 0 ;;
+    esac
+done

-# ── Colours ───────────────────────────────────────────────────────────────────
-GREEN='\033[0;32m'
-YELLOW='\033[1;33m'
-RED='\033[0;31m'
-BOLD='\033[1m'
-CYAN='\033[0;36m'
-DIM='\033[2m'
-NC='\033[0m'
+# ── Colours (respect NO_COLOR and non-TTY) ───────────────────────────────────
+if [[ -t 1 ]] && [[ -z "${NO_COLOR:-}" ]]; then
+    GREEN='\033[0;32m'
+    YELLOW='\033[1;33m'
+    RED='\033[0;31m'
+    BOLD='\033[1m'
+    CYAN='\033[0;36m'
+    DIM='\033[2m'
+    NC='\033[0m'
+else
+    GREEN='' YELLOW='' RED='' BOLD='' CYAN='' DIM='' NC=''
+fi

 ok()   { echo -e "${GREEN}[OK]${NC}  $1"; }
 warn() { echo -e "${YELLOW}[!]${NC}  $1"; }
@ -50,13 +68,14 @@ ask() {

 # ── Error trap ────────────────────────────────────────────────────────────────
 on_error() {
-    echo -e "\n${RED}[FATAL]${NC} Unexpected error at line ${BASH_LINENO[0]}." >&2
+    echo -e "\n${RED}[FATAL]${NC} Command '${BASH_COMMAND}' failed at line ${BASH_LINENO[0]}." >&2
    echo "  To get a full debug log:" >&2
    echo "    ./install.sh 2>&1 | tee /tmp/chopsticks-install.log" >&2
    echo "  Report issues: https://github.com/m1ngsama/chopsticks/issues" >&2
 }
 trap on_error ERR
-trap 'rm -f /tmp/chopsticks-hadolint /tmp/chopsticks-marksman 2>/dev/null' EXIT
+_TMPDIR=$(mktemp -d "${TMPDIR:-/tmp}/chopsticks-XXXXXX")
+trap 'rm -rf "$_TMPDIR" 2>/dev/null' EXIT

 # ── Safe download helper ──────────────────────────────────────────────────────
 safe_download() {
@ -72,10 +91,11 @@ safe_download() {
 # ── Cross-platform package install helper ─────────────────────────────────────
 pkg_install() {
    local brew_pkg="${1:-}" apt_pkg="${2:-}" pac_pkg="${3:-}" dnf_pkg="${4:-}"
-    if   [[ $HAS_BREW   -eq 1 && -n "$brew_pkg" ]]; then brew install "$brew_pkg" >/dev/null 2>&1
+    if   [[ $OS == "macos" && $HAS_BREW -eq 1 && -n "$brew_pkg" ]]; then brew install "$brew_pkg" >/dev/null 2>&1
    elif [[ $HAS_APT    -eq 1 && -n "$apt_pkg"  && $HAS_SUDO -eq 1 ]]; then sudo apt-get install -y "$apt_pkg" >/dev/null 2>&1
    elif [[ $HAS_PACMAN -eq 1 && -n "$pac_pkg"  && $HAS_SUDO -eq 1 ]]; then sudo pacman -S --noconfirm "$pac_pkg" >/dev/null 2>&1
    elif [[ $HAS_DNF    -eq 1 && -n "$dnf_pkg"  && $HAS_SUDO -eq 1 ]]; then sudo dnf install -y "$dnf_pkg" >/dev/null 2>&1
+    elif [[ $HAS_BREW   -eq 1 && -n "$brew_pkg" ]]; then brew install "$brew_pkg" >/dev/null 2>&1
    else return 1
    fi
 }
@ -164,11 +184,14 @@ _menu_checkbox() {
    local _key _esc _i

    tput civis 2>/dev/null   # hide cursor
-    _menu_draw
+    local _first=1

    while true; do
-        tput cuu "$_lines" 2>/dev/null   # move back to top of menu
+        if [[ $_first -eq 0 ]]; then
+            tput cuu "$_lines" 2>/dev/null   # move back to top of menu
+        fi
        _menu_draw
+        _first=0

        IFS= read -r -s -n1 _key </dev/tty
        if [[ $_key == $'\x1b' ]]; then
@ -412,6 +435,9 @@ _vim_run() {
        vim --not-a-term "$@" 2>/dev/null
    fi
 }
+if [[ -d "$HOME/.vim/plugged" ]] && [[ -n "$(ls -A "$HOME/.vim/plugged" 2>/dev/null)" ]]; then
+    warn "PlugClean: removing plugins not listed in .vimrc from ~/.vim/plugged"
+fi
 _vim_run +'PlugClean!' +qall || true  # remove plugins no longer in vimrc; ignore exit code (none expected)
 _vim_run +'PlugInstall --sync' +qall || true  # fzf post-install hook may exit non-zero; harmless

@ -558,6 +584,10 @@ _do_binary_apt() {
    if command -v "$check" >/dev/null 2>&1; then
        ok "$name (already installed)"; return
    fi
+    if [[ $HAS_SUDO -ne 1 ]]; then
+        fail "$name — sudo not available, cannot install to /usr/local/bin"
+        FAILED+=("$name"); return
+    fi
    if safe_download "$url" "$tmp"; then
        chmod +x "$tmp" && sudo mv "$tmp" /usr/local/bin/"$check"
        ok "$name"; INSTALLED+=("$name")
@ -583,20 +613,38 @@ elif [[ $HAS_APT -eq 1 ]]; then
    _do_sys "shellcheck"      shellcheck "$_I_SHELLCHECK" "" shellcheck      "" ""

    # hadolint: no apt package — binary from GitHub releases
-    HARCH=$(arch_github)
-    HVER=$(curl -fsSL https://api.github.com/repos/hadolint/hadolint/releases/latest \
-           | grep '"tag_name"' | cut -d'"' -f4 2>/dev/null) || HVER=""
-    _do_binary_apt "hadolint" hadolint "$_I_HADOLINT" \
-        "https://github.com/hadolint/hadolint/releases/download/${HVER}/hadolint-Linux-${HARCH}" \
-        /tmp/chopsticks-hadolint
+    if [[ $_I_HADOLINT -ge 0 ]] && _selected "$_I_HADOLINT"; then
+        HARCH=$(arch_github)
+        HVER=$(curl -fsSL https://api.github.com/repos/hadolint/hadolint/releases/latest \
+               | grep '"tag_name"' | cut -d'"' -f4 2>/dev/null) || HVER=""
+        if [[ -z "$HVER" ]]; then
+            fail "hadolint — could not determine latest release version"
+            FAILED+=("hadolint")
+        else
+            _do_binary_apt "hadolint" hadolint "$_I_HADOLINT" \
+                "https://github.com/hadolint/hadolint/releases/download/${HVER}/hadolint-Linux-${HARCH}" \
+                "$_TMPDIR/hadolint"
+        fi
+    else
+        skip "hadolint"; SKIPPED+=("hadolint")
+    fi

    # marksman: no apt package — binary from GitHub releases
-    MARCH=$(arch_linux_x64)
-    MVER=$(curl -fsSL https://api.github.com/repos/artempyanykh/marksman/releases/latest \
-           | grep '"tag_name"' | cut -d'"' -f4 2>/dev/null) || MVER=""
-    _do_binary_apt "marksman" marksman "$_I_MARKSMAN" \
-        "https://github.com/artempyanykh/marksman/releases/download/${MVER}/marksman-linux-${MARCH}" \
-        /tmp/chopsticks-marksman
+    if [[ $_I_MARKSMAN -ge 0 ]] && _selected "$_I_MARKSMAN"; then
+        MARCH=$(arch_linux_x64)
+        MVER=$(curl -fsSL https://api.github.com/repos/artempyanykh/marksman/releases/latest \
+               | grep '"tag_name"' | cut -d'"' -f4 2>/dev/null) || MVER=""
+        if [[ -z "$MVER" ]]; then
+            fail "marksman — could not determine latest release version"
+            FAILED+=("marksman")
+        else
+            _do_binary_apt "marksman" marksman "$_I_MARKSMAN" \
+                "https://github.com/artempyanykh/marksman/releases/download/${MVER}/marksman-linux-${MARCH}" \
+                "$_TMPDIR/marksman"
+        fi
+    else
+        skip "marksman"; SKIPPED+=("marksman")
+    fi

 elif [[ $HAS_PACMAN -eq 1 ]]; then
    _do_sys "ripgrep"         rg         "$_I_RIPGREP"    "" "" ripgrep    ""
@ -610,16 +658,22 @@ elif [[ $HAS_DNF -eq 1 ]]; then
    _do_sys "ripgrep"         rg         "$_I_RIPGREP"    "" "" "" ripgrep
    _do_sys "fzf"             fzf        "$_I_FZF"        "" "" "" fzf
    _do_sys "shellcheck"      shellcheck "$_I_SHELLCHECK" "" "" "" ShellCheck
-    if [[ $_I_CTAGS -ge 0 ]] && _selected "$_I_CTAGS"; then
-        skip "universal-ctags — Fedora: install manually: sudo dnf install ctags"
+    if [[ $_I_CTAGS -ge 0 ]]; then
+        if _selected "$_I_CTAGS"; then
+            skip "universal-ctags — Fedora: install manually: sudo dnf install ctags"
+        fi
        SKIPPED+=("universal-ctags")
    fi
-    if [[ $_I_HADOLINT -ge 0 ]] && _selected "$_I_HADOLINT"; then
-        skip "hadolint — Fedora: install manually: https://github.com/hadolint/hadolint/releases"
+    if [[ $_I_HADOLINT -ge 0 ]]; then
+        if _selected "$_I_HADOLINT"; then
+            skip "hadolint — Fedora: install manually: https://github.com/hadolint/hadolint/releases"
+        fi
        SKIPPED+=("hadolint")
    fi
-    if [[ $_I_MARKSMAN -ge 0 ]] && _selected "$_I_MARKSMAN"; then
-        skip "marksman — Fedora: install manually: https://github.com/artempyanykh/marksman/releases"
+    if [[ $_I_MARKSMAN -ge 0 ]]; then
+        if _selected "$_I_MARKSMAN"; then
+            skip "marksman — Fedora: install manually: https://github.com/artempyanykh/marksman/releases"
+        fi
        SKIPPED+=("marksman")
    fi
 else
@ -679,8 +733,10 @@ else
        if command -v "$check" >/dev/null 2>&1; then
            ok "$pkg (already installed)"; return
        fi
-        if pip3 install --quiet "$pkg" 2>/dev/null || \
-           pip3 install --quiet --break-system-packages "$pkg" 2>/dev/null; then
+        if pip3 install --quiet "$pkg" 2>/dev/null; then
+            ok "$pkg"; INSTALLED+=("$pkg")
+        elif pip3 install --quiet --break-system-packages "$pkg" 2>/dev/null; then
+            warn "$pkg installed with --break-system-packages (consider using a virtualenv)"
            ok "$pkg"; INSTALLED+=("$pkg")
        else
            fail "$pkg"; FAILED+=("$pkg")