chopsticks/doc/chopsticks.txt

*chopsticks.txt* *chopsticks*        A project-work Vim setup

==============================================================================
CONTENTS                                                    *chopsticks-contents*

  1. What chopsticks solves...............|chopsticks-why|
  2. First five minutes...................|chopsticks-start|
  3. Canonical Space layout...............|chopsticks-v3-space|
  4. Commands.............................|chopsticks-commands|
  5. Profiles and local config............|chopsticks-profiles|
  6. Beta testing.........................|chopsticks-beta|
  7. Troubleshooting......................|chopsticks-troubleshooting|

==============================================================================
WHAT CHOPSTICKS SOLVES                                         *chopsticks-why*

Chopsticks is a complete Vim project loop for people who edit locally and over
SSH. It connects fuzzy find, project grep, git, LSP, linting, formatting,
runners, quickfix navigation, and self-documenting keys.

It is meant to supplement stock Vim, not replace Vim muscle memory. Native
motions and well-known conventions stay where they are useful: gd, gr, K,
<C-w>hjkl, cl, cc, quickfix, and normal Vim commands.

==============================================================================
FIRST FIVE MINUTES                                             *chopsticks-start*

Inside Vim:
>
  :ChopsticksTutor     guided practice page
  SPC ?                active keymap cheat sheet
  :ChopsticksStatus    tool, plugin, and LSP diagnostics
  :ChopsticksHelp      this help page
  :ChopsticksConfig    edit local preferences
<

Daily loop:
>
  SPC SPC   find file              SPC /     grep project
  s + 2ch   jump on screen         gd / gr   definition / references
  K         hover docs             SPC rr    run current file
  SPC gs    git status             SPC cf    format
  SPC w     save                   SPC qq    quit
<

==============================================================================
CANONICAL SPACE LAYOUT                                      *chopsticks-v3-space*

Default layout: Space leader, comma localleader.

This layout assumes a QWERTY keyboard and CapsLock mapped at the system layer
to tap-Esc / hold-Ctrl. Vim keeps <C-w>hjkl for windows and standard LSP
motions for code.

Normal-mode s is a visible EasyMotion jump. This is intentionally different
from stock Vim because screen-local jumping is higher value in project editing.
Use cl for native s substitute and cc for native S substitute.

High-frequency keys:
>
  SPC SPC   files                  SPC ,     buffers
  SPC /     grep project           SPC Tab   alternate file
  SPC e/E   file sidebar           SPC rr    run file
  SPC gs    git status             SPC gl    git log graph
  SPC ca    code action            SPC cr    rename
  SPC cf    format                 SPC fc    edit local config
  SPC fV    reload config          SPC ?     cheat sheet
<

Classic comma mappings remain available:
>
  let g:chopsticks_keymap_style = 'classic'
<

==============================================================================
COMMANDS                                                    *chopsticks-commands*

User-facing commands:
>
  :ChopsticksHelp         open this help
  :ChopsticksConfig       edit local preferences
  :ChopsticksReload       reload chopsticks after config changes
  :ChopsticksTutor        guided practice
  :ChopsticksCheatSheet   active keymap reference
  :ChopsticksStatus       health diagnostics
  :ChopsticksBeta         beta checklist
  :ChopsticksBetaLog      editable beta notes
  :ChopsticksBetaSession  append a timestamped beta note block
<

LSP commands come from vim-lsp:
>
  :LspInstallServer       install a server for the current filetype
  :LspStatus              inspect attached servers
<

==============================================================================
PROFILES AND LOCAL CONFIG                                   *chopsticks-profiles*

Keep personal choices outside the managed .vimrc:
>
  " ${XDG_CONFIG_HOME:-~/.config}/chopsticks.vim
  let g:chopsticks_profile = 'engineer'
  let g:chopsticks_keymap_style = 'space'
<

Open that file from inside Vim:
>
  :ChopsticksConfig
<

Reload after saving it:
>
  :ChopsticksReload
<

Profiles:

  minimal   Core navigation, editing, git, Markdown. No LSP/ALE/completion.
  engineer  Default. LSP, ALE, completion, syntax extras.
  full      Engineer plus heavier Markdown feedback.

Optional habits:
>
  let g:chopsticks_enable_jk_escape = 1
  let g:chopsticks_enable_ctrl_s_save = 1
  let g:chopsticks_enable_auto_pairs = 1
  let g:chopsticks_enable_terminal_keymaps = 1
<

==============================================================================
BETA TESTING                                                  *chopsticks-beta*

For the v3 beta candidate, record real editing friction instead of abstract
opinions:
>
  :ChopsticksBeta         compact beta checklist
  :ChopsticksBetaLog      open editable local notes
  :ChopsticksBetaSession  append a new session block
<

Default beta log:
>
  ${XDG_CONFIG_HOME:-~/.config}/chopsticks-beta.md
<

Exit criteria before a stable release:

  - s as jump still feels worth the native override.
  - No high-frequency action needs an undocumented key.
  - README, QUICKSTART, :help chopsticks, SPC ?, and :ChopsticksTutor agree.
  - quick and Vim smoke tests pass locally and over SSH.
  - The README GIF matches the public keymap.

==============================================================================
TROUBLESHOOTING                                      *chopsticks-troubleshooting*

Start with:
>
  :ChopsticksStatus
  SPC ?
  :ChopsticksTutor
  :ChopsticksHelp
  :ChopsticksConfig
<

Common fixes:

  Plugins missing        :PlugInstall
  LSP missing            Open that filetype, then :LspInstallServer
  Need active keys       SPC ?
  Need full docs         :help chopsticks
  Need local config      :ChopsticksConfig
  Changed local config   :ChopsticksReload
  Need beta notes        :ChopsticksBetaSession
  Slow large file        Syntax, undo, swap, and ALE are auto-reduced

==============================================================================
 vim:tw=78:ts=8:ft=help:norl: