Add native Vim help entrypoint

.gitignore

@@ -5,5 +5,6 @@ __pycache__/
 Session.vim
 autoload/
 plugged/
+doc/tags
 .swap/
 .undo/

.vimrc

@@ -1,6 +1,9 @@
 set nocompatible
 
 let g:chopsticks_dir = fnamemodify(resolve(expand('<sfile>')), ':h')
+if index(split(&runtimepath, ','), g:chopsticks_dir) < 0
+    let &runtimepath = g:chopsticks_dir . ',' . &runtimepath
+endif
 let s:xdg_config_home = !empty($XDG_CONFIG_HOME) && $XDG_CONFIG_HOME =~# '^/'
     \ ? $XDG_CONFIG_HOME
     \ : '~/.config'
@@ -38,4 +41,5 @@ call s:load('status')
 call s:load('cheatsheet')
 call s:load('tutor')
 call s:load('beta')
+call s:load('help')
 call s:load('tools')

BETA.md

@@ -5,7 +5,8 @@ until the checklist below is closed.
 
 Inside Vim, run `:ChopsticksBeta` for the compact checklist,
 `:ChopsticksBetaLog` for editable local notes, and `:ChopsticksBetaSession`
-to append a new session block.
+to append a new session block. Run `:ChopsticksHelp` or `:help chopsticks`
+for the native Vim reference.
 
 ## Install the beta
 
@@ -67,7 +68,8 @@ file, edit Markdown, and use a machine with missing optional tools.
 - `s` as the default visible jump still feels worth the native override after
   real editing.
 - No high-frequency action requires remembering an undocumented key.
-- README, QUICKSTART, `SPC ?`, and `:ChopsticksTutor` teach the same layout.
+- README, QUICKSTART, `:help chopsticks`, `SPC ?`, and `:ChopsticksTutor`
+  teach the same layout.
 - `scripts/test.sh quick` and `scripts/test.sh vim` pass locally.
 - The README GIF has been regenerated from `.github/demo.tape` after any public
   key change.

CHANGELOG.md

@@ -23,8 +23,12 @@
   `[d`, and `]d`
 - `:ChopsticksTutor` guided practice buffer for learning the final keymap
 - `:ChopsticksCheatSheet` command, with `SPC ?` as the discoverable default
+- `:ChopsticksHelp` and native `:help chopsticks` documentation for in-editor
+  support without a separate wiki
+- `:ChopsticksBeta`, `:ChopsticksBetaLog`, and `:ChopsticksBetaSession` for
+  guided beta testing and local session notes
 - Dedicated modules for buffers, utilities, files, runner, quickfix, status,
-  cheat sheet, and tutor
+  cheat sheet, tutor, beta testing, and help
 - Split test runner: `scripts/test.sh` now dispatches to
   `scripts/test-quick.sh` and `scripts/test-vim.sh`
 

QUICKSTART.md

@@ -51,6 +51,7 @@ SPC w           save
 SPC qx          save + quit
 :q!             force quit
 SPC ?           cheat sheet (toggle sidebar)
+:ChopsticksHelp  full native help
 ```
 
 Classic layout equivalents:
@@ -61,6 +62,7 @@ Esc             back to Normal
 ,x              save + quit
 :q!             force quit
 ,?              cheat sheet (toggle sidebar)
+:ChopsticksHelp  full native help
 ```
 
 ## Find things
@@ -137,6 +139,7 @@ syntax. Enable the heavier Markdown tools only when you want them.
 ## Health check
 
 ```
+:ChopsticksHelp        full native Vim help
 :ChopsticksTutor       guided practice for the final keymap
 :ChopsticksStatus       see what's installed and what's missing
 ```
@@ -144,5 +147,6 @@ syntax. Enable the heavier Markdown tools only when you want them.
 The `SPC ?` cheat sheet follows your active profile, so `minimal` users only see
 keys for features that are actually loaded.
 
-See [README](README.md) for the full reference. For beta testing and rollback,
+Inside Vim, `:help chopsticks` opens the same reference after helptags are
-see [BETA.md](BETA.md).
+available. See [README](README.md) for the full reference. For beta testing and
+rollback, see [BETA.md](BETA.md).

README.md

@@ -48,9 +48,9 @@ That assembly work is the pain chopsticks removes:
   `gd`, `gr`, `K`, `<C-w>hjkl`, `cl`, `cc`.
 - **Remote editing is fragile.** It is built to degrade on TTY, slow SSH, and
   headless machines instead of assuming a GUI desktop.
-- **Custom configs are hard to onboard.** `SPC ?`, `:ChopsticksTutor`, and
+- **Custom configs are hard to onboard.** `:ChopsticksHelp`, `SPC ?`,
-  `:ChopsticksStatus` make the active keymap and missing tools visible inside
+  `:ChopsticksTutor`, and `:ChopsticksStatus` make the active keymap, full
-  Vim.
+  help, and missing tools visible inside Vim.
 
 You SSH into a server. You need to edit code. You want LSP, fuzzy find, git
 integration, format-on-save — not a 20-minute setup.
@@ -142,8 +142,9 @@ Git push/pull are intentionally not bound to default hotkeys. Normal-mode `s`
 is a screen-local EasyMotion jump; use `cl` for native `s` substitute and `cc`
 for native `S`.
 
-For onboarding, use `:ChopsticksTutor` for a guided practice page, `SPC ?` for
+For onboarding, use `:ChopsticksHelp` / `:help chopsticks` for full native Vim
-the active keymap, and `:ChopsticksStatus` for tool/LSP health.
+help, `:ChopsticksTutor` for a guided practice page, `SPC ?` for the active
+keymap, and `:ChopsticksStatus` for tool/LSP health.
 `QUICKSTART.md` is the 5-minute path; this README is the full reference.
 During the beta, `:ChopsticksBeta` opens the in-editor test checklist,
 `:ChopsticksBetaLog` opens editable local notes, and `:ChopsticksBetaSession`
@@ -199,7 +200,7 @@ Esc       exit insert mode         SPC ?    cheat sheet
 
 ### Survival
 
-`SPC w` save | `SPC W` save all | `SPC qq` quit | `SPC qx` save and quit | `SPC ?` cheat sheet | `:ChopsticksTutor` practice | `:ChopsticksStatus` diagnostics
+`SPC w` save | `SPC W` save all | `SPC qq` quit | `SPC qx` save and quit | `SPC ?` cheat sheet | `:ChopsticksHelp` full help | `:ChopsticksTutor` practice | `:ChopsticksStatus` diagnostics
 
 </details>
 
@@ -283,27 +284,30 @@ For Markdown LSP, install or select `marksman` first.
 ```
 ~/.vim/
 ├── .vimrc              thin loader
-├── modules/
+├── doc/
-│   ├── env.vim         TTY detection, truecolor, skip built-in plugins
+│   └── chopsticks.txt  :help chopsticks
-│   ├── plugins.vim     vim-plug + 23–25 plugins
+└── modules/
-│   ├── core.vim        settings, keymaps, performance
+    ├── env.vim         TTY detection, truecolor, skip built-in plugins
-│   ├── ui.vim          solarized, statusline, startify
+    ├── plugins.vim     vim-plug + 23–25 plugins
-│   ├── editing.vim     easymotion, yank highlight, blank lines
+    ├── core.vim        settings, keymaps, performance
-│   ├── navigation.vim  fzf, netrw sidebar, windows, terminal
+    ├── ui.vim          solarized, statusline, startify
-│   ├── lsp.vim         vim-lsp, asyncomplete
+    ├── editing.vim     easymotion, yank highlight, blank lines
-│   ├── lint.vim        ale, format-on-save
+    ├── navigation.vim  fzf, netrw sidebar, windows, terminal
-│   ├── git.vim         fugitive, gitgutter, conflict nav
+    ├── lsp.vim         vim-lsp, asyncomplete
-│   ├── languages.vim   vim-go, markdown, filetype settings
+    ├── lint.vim        ale, format-on-save
-│   ├── buffers.vim     buffer commands
+    ├── git.vim         fugitive, gitgutter, conflict nav
-│   ├── utilities.vim   reindent, trim, clipboard, vimrc helpers
+    ├── languages.vim   vim-go, markdown, filetype settings
-│   ├── files.vim       auto mkdir, large-file protection
+    ├── buffers.vim     buffer commands
-│   ├── runner.vim      run current file
+    ├── utilities.vim   reindent, trim, clipboard, vimrc helpers
-│   ├── quickfix.vim    quickfix and location-list helpers
+    ├── files.vim       auto mkdir, large-file protection
-│   ├── status.vim      :ChopsticksStatus diagnostics
+    ├── runner.vim      run current file
-│   ├── cheatsheet.vim  SPC ? and :ChopsticksCheatSheet
+    ├── quickfix.vim    quickfix and location-list helpers
-│   ├── tutor.vim       :ChopsticksTutor guided practice
+    ├── status.vim      :ChopsticksStatus diagnostics
-│   ├── beta.vim        :ChopsticksBeta test guide
+    ├── cheatsheet.vim  SPC ? and :ChopsticksCheatSheet
-│   └── tools.vim       compatibility placeholder
+    ├── tutor.vim       :ChopsticksTutor guided practice
+    ├── beta.vim        :ChopsticksBeta test guide
+    ├── help.vim        :ChopsticksHelp native Vim help
+    └── tools.vim       compatibility placeholder
 ```
 
 Each module is self-contained. Comment out one line in `.vimrc` to disable it. Add your own with `call s:load('mine')`.
@@ -329,7 +333,7 @@ Each module is self-contained. Comment out one line in `.vimrc` to disable it. A
 | What's installed?   | `:ChopsticksStatus` shows tools, LSP, linters |
 
 For deeper checks, start with `:ChopsticksStatus`, `SPC ?`,
-`:ChopsticksTutor`, and [QUICKSTART.md](QUICKSTART.md).
+`:ChopsticksTutor`, `:ChopsticksHelp`, and [QUICKSTART.md](QUICKSTART.md).
 
 ## Contributing
 

doc/chopsticks.txt

@@ -0,0 +1,162 @@
+*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
+<
+
+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 ?     cheat sheet
+<
+
+Classic comma mappings remain available:
+>
+  let g:chopsticks_keymap_style = 'classic'
+<
+
+==============================================================================
+COMMANDS                                                    *chopsticks-commands*
+
+User-facing commands:
+>
+  :ChopsticksHelp         open this help
+  :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'
+<
+
+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
+<
+
+Common fixes:
+
+  Plugins missing        :PlugInstall
+  LSP missing            Open that filetype, then :LspInstallServer
+  Need active keys       SPC ?
+  Need full docs         :help chopsticks
+  Need beta notes        :ChopsticksBetaSession
+  Slow large file        Syntax, undo, swap, and ALE are auto-reduced
+
+==============================================================================
+ vim:tw=78:ts=8:ft=help:norl:

install.sh

@@ -719,6 +719,21 @@ if [[ $_plug_count -eq 0 ]]; then
 fi
 ok "Plugins installed ($_plug_count)"
 
+step "Installing Vim help"
+if [[ -d "$SCRIPT_DIR/doc" ]]; then
+    # shellcheck disable=SC2016 # $CHOPSTICKS_HELP_DIR is expanded by Vim.
+    if CHOPSTICKS_HELP_DIR="$SCRIPT_DIR/doc" \
+        "$VIM_BIN" -Nu NONE -i NONE -n -es -N \
+            -c 'execute "silent! helptags " . fnameescape($CHOPSTICKS_HELP_DIR)' \
+            -c 'qa!' >/dev/null 2>&1; then
+        ok ":help chopsticks"
+    else
+        warn "Could not generate Vim help tags. Inside Vim, run: :ChopsticksHelp"
+    fi
+else
+    skip "Vim help docs not found"
+fi
+
 # ============================================================================
 # 4. Module Selection
 # ============================================================================

modules/cheatsheet.vim

@@ -147,6 +147,7 @@ function! s:CheatSheet() abort
             \ '  Esc       exit insert',
             \ '  SPC fv    edit vimrc',
             \ '  SPC fV    reload vimrc',
+            \ '  :ChopsticksHelp    full help',
             \ '  :ChopsticksTutor   practice',
             \ '  :ChopsticksStatus  health',
             \ '  :ChopsticksBeta    beta test guide',
@@ -260,6 +261,7 @@ function! s:CheatSheet() abort
         \ '  Esc       exit insert',
         \ '  ,ev       edit vimrc',
         \ '  ,sv       reload vimrc',
+        \ '  :ChopsticksHelp    full help',
         \ '  :ChopsticksTutor   practice',
         \ '  :ChopsticksStatus  health',
         \ '  :ChopsticksBeta    beta test guide',

modules/help.vim

@@ -0,0 +1,18 @@
+" help.vim — native Vim help entrypoint
+
+function! s:OpenHelp() abort
+    let l:doc = g:chopsticks_dir . '/doc'
+    if isdirectory(l:doc)
+        silent! execute 'helptags ' . fnameescape(l:doc)
+    endif
+
+    try
+        help chopsticks
+    catch /^Vim\%((\a\+)\)\=:E149/
+        echohl WarningMsg
+        echom 'chopsticks help tags are missing; run :helptags ' . l:doc
+        echohl None
+    endtry
+endfunction
+
+command! ChopsticksHelp call s:OpenHelp()

modules/status.vim

@@ -85,6 +85,8 @@ function! s:ChopsticksStatus() abort
     call add(l:lines, 'chopsticks status')
     call add(l:lines, repeat('─', 50))
     call add(l:lines, '')
+    call add(l:lines, '  help       :ChopsticksHelp  :ChopsticksTutor  SPC ?')
+    call add(l:lines, '')
 
     if !empty(get(g:, 'chopsticks_beta_label', ''))
         call add(l:lines, '── beta ──')

modules/tutor.vim

@@ -28,6 +28,7 @@ function! s:ChopsticksTutor() abort
             \ '     SPC ?      active cheat sheet',
             \ '     SPC w      save',
             \ '     SPC qx     save and quit',
+            \ '     :ChopsticksHelp    full help',
             \ '     :ChopsticksStatus  health check',
             \ '     :ChopsticksBeta    beta checklist',
             \ '     :ChopsticksBetaLog beta notes',
@@ -92,6 +93,7 @@ function! s:ChopsticksTutor() abort
             \ '     <C-w>hjkl     split navigation',
             \ '',
             \ '  support',
+            \ '     :ChopsticksHelp    full help',
             \ '     :ChopsticksStatus  health check',
             \ '     :ChopsticksBeta    beta checklist',
             \ '     :ChopsticksBetaLog beta notes',

scripts/test-quick.sh

@@ -29,8 +29,10 @@ check_docs() {
     markdownlint README.md QUICKSTART.md CONTRIBUTING.md CHANGELOG.md BETA.md
 
     step "Documentation consistency"
-    for command in ChopsticksBeta ChopsticksBetaLog ChopsticksBetaSession; do
+    for command in ChopsticksHelp ChopsticksBeta ChopsticksBetaLog \
-        for file in README.md BETA.md modules/beta.vim modules/cheatsheet.vim \
+        ChopsticksBetaSession
+    do
+        for file in README.md BETA.md doc/chopsticks.txt modules/cheatsheet.vim \
             modules/tutor.vim modules/status.vim
         do
             grep -Fq "$command" "$file" || {
@@ -39,6 +41,15 @@ check_docs() {
             }
         done
     done
+    grep -Fq '*chopsticks.txt*' doc/chopsticks.txt
+    grep -Fq '*chopsticks-v3-space*' doc/chopsticks.txt
+    grep -Fq 'command! ChopsticksHelp' modules/help.vim
+    for command in ChopsticksBeta ChopsticksBetaLog ChopsticksBetaSession; do
+        grep -Fq "command! $command" modules/beta.vim || {
+            echo "Missing $command definition in modules/beta.vim" >&2
+            exit 1
+        }
+    done
 
     if command -v vhs >/dev/null 2>&1; then
         vhs validate .github/demo.tape

scripts/test-vim.sh

@@ -42,11 +42,20 @@ check_vim() {
     fi
 
     mkdir -p "$TMP_ROOT/chopsticks path/modules"
+    mkdir -p "$TMP_ROOT/chopsticks path/doc"
     cp .vimrc "$TMP_ROOT/chopsticks path/.vimrc"
     cp modules/*.vim "$TMP_ROOT/chopsticks path/modules/"
+    cp doc/*.txt "$TMP_ROOT/chopsticks path/doc/"
     XDG_CONFIG_HOME="$EMPTY_XDG" vim -u "$TMP_ROOT/chopsticks path/.vimrc" \
         -i NONE -es -N -c 'qa!' 2>&1
 
+    XDG_CONFIG_HOME="$EMPTY_XDG" \
+        vim -u "$TMP_ROOT/chopsticks path/.vimrc" -i NONE -es -N \
+        -c 'ChopsticksHelp' \
+        -c 'if expand("%:t") !=# "chopsticks.txt" | cquit | endif' \
+        -c 'if search("chopsticks-v3-space", "n") == 0 | cquit | endif' \
+        -c 'qa!' 2>&1
+
     XDG_CONFIG_HOME="$EMPTY_XDG" vim -u NONE -i NONE -es -N \
         -c 'let g:chopsticks_profile = "minimal"' \
         -c 'source .vimrc' \
@@ -79,6 +88,7 @@ check_vim() {
         exit 1
     fi
     grep -Fq 'OK  vim-lsp stack  (installed)' "$TMP_ROOT/status-default.txt"
+    grep -Fq 'help       :ChopsticksHelp  :ChopsticksTutor  SPC ?' "$TMP_ROOT/status-default.txt"
     grep -Fq 'candidate  3.0.0-beta.1' "$TMP_ROOT/status-default.txt"
     grep -Fq 'keymap     space' "$TMP_ROOT/status-default.txt"
     grep -Fq 'commands   :ChopsticksBeta  :ChopsticksBetaLog' "$TMP_ROOT/status-default.txt"
@@ -258,6 +268,7 @@ check_vim() {
     grep -Fq 'SPC w     save' "$TMP_ROOT/cheat-default.txt"
     grep -Fq 's+2ch     easymotion jump' "$TMP_ROOT/cheat-default.txt"
     grep -Fq 'cl / cc   native s / S substitute' "$TMP_ROOT/cheat-default.txt"
+    grep -Fq ':ChopsticksHelp    full help' "$TMP_ROOT/cheat-default.txt"
     grep -Fq ':ChopsticksTutor   practice' "$TMP_ROOT/cheat-default.txt"
     grep -Fq ':ChopsticksBeta    beta test guide' "$TMP_ROOT/cheat-default.txt"
     grep -Fq ':ChopsticksBetaLog beta notes' "$TMP_ROOT/cheat-default.txt"
@@ -332,6 +343,7 @@ check_vim() {
         -c 'qa!' 2>&1
     grep -Fq 'chopsticks tutor' "$TMP_ROOT/tutor-default.txt"
     grep -Fq 'SPC ?      active cheat sheet' "$TMP_ROOT/tutor-default.txt"
+    grep -Fq ':ChopsticksHelp    full help' "$TMP_ROOT/tutor-default.txt"
     grep -Fq 's + 2 chars  visible jump' "$TMP_ROOT/tutor-default.txt"
     grep -Fq 'cl / cc      native s / S substitute' "$TMP_ROOT/tutor-default.txt"
     grep -Fq 'gd / gr / K  definition / refs / docs' "$TMP_ROOT/tutor-default.txt"