Align docs with expert Vim workflow

.github/demo.tape

@@ -1,5 +1,6 @@
-# chopsticks demo — the project loop stock Vim does not assemble for you:
+# chopsticks demo — for people who already know Vim:
-# visible jump → file finder → run file → project grep → active key help.
+# show the project workflow layer Vim does not assemble by default.
+# project loop: visible jump → files → run → grep → git → active key help.
 # Rule: NEVER use Escape to close FZF — always Enter (deterministic).
 # Pacing: hold each scene long enough for the viewer to read.
 
@@ -30,15 +31,18 @@ Type "cd $CHOPSTICKS_DEMO_PROJECT"
 Enter
 Type "git init -q && git symbolic-ref HEAD refs/heads/main && git add ."
 Enter
+Type `clear && printf "%s\n" "chopsticks: a long-term Vim efficiency kit" "" "For experienced Vim users who already know how to edit." "Keep Vim's language. Standardize the project loop:" "" "  s + 2 chars   visible jump on the current screen" "  SPC SPC       project-aware file switcher" "  SPC rr        run the current file" "  SPC /         ripgrep the project" "  SPC gs        git status, with no push/pull hotkeys" "  SPC ?         active keys explained inside Vim"`
+Enter
+Show
+Sleep 6s
 Type "clear"
 Enter
 Type `vim -Nu "$CHOPSTICKS_ROOT/.vimrc" server.py`
 Enter
 Wait+Screen /server.py/
-Show
 Sleep 1s
 
-# ── 1. Pain: moving inside a dense screen should not mean counting hjkl ────
+# ── 1. Screen-local motion: stop counting hjkl across dense code ───────────
 Type "s"
 Sleep 0.5s
 Type "di"
@@ -46,7 +50,7 @@ Sleep 2s
 Ctrl+C
 Sleep 1s
 
-# ── 2. Pain: project files should be one habit, not :find/:edit plumbing ───
+# ── 2. Project files: one habit for git-aware file switching ───────────────
 Space 2
 Sleep 1.5s
 Type "report"
@@ -54,14 +58,14 @@ Sleep 2s
 Enter
 Sleep 3s
 
-# ── 3. Pain: edit→run should be one repeatable project loop ────────────────
+# ── 3. Edit-run loop: run the current file without leaving Vim ─────────────
 Space
 Type "rr"
 Sleep 4s
 Enter
 Sleep 1s
 
-# ── 4. Pain: project search should not leave Vim or require remembering rg ─
+# ── 4. Project grep: ripgrep as part of the same muscle-memory layer ───────
 Space
 Type "/"
 Sleep 1s
@@ -70,7 +74,15 @@ Sleep 2.5s
 Enter
 Sleep 3s
 
-# ── 5. Pain: custom keymaps must explain themselves in the editor ──────────
+# ── 5. Git boundary: status is fast; push/pull stay explicit commands ──────
+Space
+Type "gs"
+Sleep 3s
+Type ":bd!"
+Enter
+Sleep 1s
+
+# ── 6. Self-documenting config: no private wiki required ───────────────────
 Space
 Type "?"
 Sleep 5.5s

BETA.md

@@ -1,6 +1,8 @@
 # Beta Testing
 
-This branch is the v3 beta candidate. Do not tag or publish it as `v3.0.0`
+This branch is the v3 beta candidate. The goal is to prove that the Space
+layout can serve as a long-term project loop for experienced Vim users, not
+just that the mappings work in isolation. Do not tag or publish it as `v3.0.0`
 until the checklist below is closed.
 
 Inside Vim, run `:ChopsticksBeta` for the compact checklist,
@@ -40,7 +42,9 @@ reloads chopsticks after saving it.
 
 ## Daily test loop
 
-Use the beta for real editing, not only demos. For each session, record:
+Use the beta for real editing, not only demos. A session should exercise the
+trained loop until it either feels automatic or exposes friction. For each
+session, record:
 
 - The task: project navigation, code edit, grep, git, LSP, Markdown, SSH.
 - The first key you tried when you got stuck.
@@ -74,6 +78,7 @@ file, edit Markdown, and use a machine with missing optional tools.
 - No high-frequency action requires remembering an undocumented key.
 - README, QUICKSTART, `:help chopsticks`, `SPC ?`, and `:ChopsticksTutor`
   teach the same layout.
+- No private wiki or external note is needed to remember the daily loop.
 - `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.

QUICKSTART.md

@@ -1,6 +1,11 @@
 # Quick Start
 
-Five minutes from zero to a working Vim setup.
+Five minutes to understand the chopsticks project loop.
+
+This guide assumes you already know Vim's editing language. chopsticks keeps
+that language intact and gives you one stable layer for the work around it:
+jump on the visible screen, switch project files, grep, run, inspect code,
+check git, and ask Vim which keys are active.
 
 ## Install
 
@@ -35,13 +40,20 @@ To switch later without reinstalling anything:
 cd ~/.vim && ./install.sh --configure-only --profile=full
 ```
 
-## Modes
+## Daily loop
 
-| Mode   | Enter           | Leave         |
+Train this first. It is the core reason to use chopsticks instead of assembling
-| ------ | --------------- | ------------- |
+the same pieces yourself:
-| Normal | startup default | —             |
+
-| Insert | `i` / `a` / `o` | `Esc`         |
+```
-| Visual | `v` / `V`       | `Esc`         |
+SPC SPC         open a project file
+s + 2 chars     jump to visible text
+gd / gr / K     inspect definition, references, docs
+SPC rr          run the current file
+SPC /           grep the project
+SPC gs          check git status
+SPC ?           show the active keymap
+```
 
 ## Survival
 

README.md

@@ -1,13 +1,13 @@
 <p align="center">
   <img src=".github/demo.gif" alt="chopsticks demo" width="720">
   <br>
-  <sub>One project loop: jump on screen, find a file, run it, grep the codebase, then ask Vim what keys are active.</sub>
+  <sub>For Vim users who already know how to edit: one trained project loop for jump, files, run, grep, git, and active key help.</sub>
 </p>
 
 <h1 align="center">chopsticks</h1>
 
 <p align="center">
-  <strong>A project-work Vim setup: find, jump, run, grep, git, LSP, and self-documenting keys over SSH.</strong>
+  <strong>A long-term Vim efficiency kit: find, jump, run, grep, git, LSP, and self-documenting keys over SSH.</strong>
 </p>
 
 <p align="center">
@@ -34,7 +34,11 @@ keymap before promotion.
 
 ## Why
 
-Stock Vim is a great editor core, but it does not ship a complete project
+chopsticks is for experienced Vim users who want one stable, ergonomic working
+set they can train once and keep for years. It does not replace Vim's editing
+language; it standardizes the project loop around it.
+
+Stock Vim is a great editor core, but it does not ship that complete project
 workflow. You still have to assemble fuzzy finding, project grep, git, LSP,
 diagnostics, formatters, runners, terminal behavior, and a keymap that will not
 collapse over SSH.
@@ -145,10 +149,10 @@ 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 `:ChopsticksHelp` / `:help chopsticks` for full native Vim
+For learning the kit, use `:ChopsticksTutor` to train the core loop, `SPC ?`
-help, `:ChopsticksTutor` for a guided practice page, `SPC ?` for the active
+for the active keymap, `:ChopsticksHelp` / `:help chopsticks` for full native
-keymap, `:ChopsticksConfig` for local preferences, and `:ChopsticksStatus` for
+Vim help, `:ChopsticksConfig` for local preferences, and `:ChopsticksStatus`
-tool/LSP health.
+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`

doc/chopsticks.txt

@@ -1,4 +1,4 @@
-*chopsticks.txt* *chopsticks*        A project-work Vim setup
+*chopsticks.txt* *chopsticks*        A long-term Vim efficiency kit
 
 ==============================================================================
 CONTENTS                                                    *chopsticks-contents*
@@ -14,9 +14,10 @@ CONTENTS                                                    *chopsticks-contents
 ==============================================================================
 WHAT CHOPSTICKS SOLVES                                         *chopsticks-why*
 
-Chopsticks is a complete Vim project loop for people who edit locally and over
+Chopsticks is for experienced Vim users who want one stable, ergonomic working
-SSH. It connects fuzzy find, project grep, git, LSP, linting, formatting,
+set they can train once and keep for years. It connects fuzzy find, project
-runners, quickfix navigation, and self-documenting keys.
+grep, git, LSP, linting, formatting, runners, quickfix navigation, and
+self-documenting keys for people who edit locally and over SSH.
 
 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,

modules/beta.vim

@@ -19,8 +19,8 @@ function! s:OpenBetaGuide() abort
         \ '  ─────────────────────────────',
         \ '',
         \ '  goal',
-        \ '     Prove the v3 Space layout in real editing before release.',
+        \ '     Prove this can be a long-term project loop.',
-        \ '     Record friction, not opinions in the abstract.',
+        \ '     Record real editing friction, not abstract taste.',
         \ '',
         \ '  daily loop',
         \ '     SPC SPC   find file',
@@ -44,6 +44,7 @@ function! s:OpenBetaGuide() abort
         \ '     s as jump still feels worth the native override',
         \ '     no high-frequency action needs an undocumented key',
         \ '     README, QUICKSTART, SPC ?, and tutor teach the same layout',
+        \ '     no private wiki is needed to remember the daily loop',
         \ '     quick/vim tests pass locally and over SSH',
         \ '',
         \ '  files',

modules/cheatsheet.vim

@@ -29,6 +29,10 @@ function! s:CheatSheet() abort
             \ '  chopsticks         <Space>? close',
             \ '  ─────────────────────────────────',
             \ '',
+            \ '  trained loop:',
+            \ '  files → s jump → gd/K',
+            \ '  run → grep → git',
+            \ '',
             \ '  ── fast path ─────────────',
             \ '  SPC SPC   files',
             \ '  SPC ,     buffers',
@@ -166,6 +170,10 @@ function! s:CheatSheet() abort
         \ '  chopsticks         ,? close',
         \ '  ─────────────────────────────',
         \ '',
+        \ '  trained loop:',
+        \ '  files → jump → inspect',
+        \ '  run → grep → git',
+        \ '',
         \ '  ── files ──────────────────',
         \ '  ,ff       files',
         \ '  ,b        buffers',

modules/tutor.vim

@@ -23,9 +23,20 @@ function! s:ChopsticksTutor() abort
             \ '  chopsticks tutor        q close',
             \ '  ───────────────────────────────',
             \ '',
-            \ '  1. survival',
+            \ '  Goal: train one long-term project loop around Vim.',
-            \ '     Esc        Normal mode',
+            \ '  Keep Vim editing habits; standardize the surrounding work.',
+            \ '',
+            \ '  1. trained loop',
+            \ '     SPC SPC    open a project file',
+            \ '     s + 2 chars jump to visible text',
+            \ '     gd / gr / K inspect definition / refs / docs',
+            \ '     SPC rr     run current file',
+            \ '     SPC /      grep project',
+            \ '     SPC gs     check git status',
             \ '     SPC ?      active cheat sheet',
+            \ '',
+            \ '  2. survival',
+            \ '     Esc        Normal mode',
             \ '     SPC w      save',
             \ '     SPC qx     save and quit',
             \ '     SPC fc     edit local config',
@@ -38,42 +49,43 @@ function! s:ChopsticksTutor() abort
             \ '     :ChopsticksBetaLog beta notes',
             \ '     :ChopsticksBetaSession new note',
             \ '',
-            \ '  2. find and switch',
+            \ '  3. find and switch',
             \ '     SPC SPC    find files',
             \ '     SPC /      grep project',
             \ '     SPC ,      buffers',
             \ '     SPC Tab    alternate buffer',
             \ '     SPC e/E    sidebar cwd / file dir',
             \ '',
-            \ '  3. jump and edit',
+            \ '  4. jump and edit',
             \ '     s + 2 chars  visible jump',
             \ '     SPC S        same jump fallback',
             \ '     cl / cc      native s / S substitute',
             \ '     gc           comment',
             \ '     SPC U        undo tree',
             \ '',
-            \ '  4. code loop',
+            \ '  5. code loop',
             \ '     gd / gr / K  definition / refs / docs',
             \ '     gI / gy      implementation / type',
             \ '     [d ]d        LSP diagnostics',
             \ '     SPC ca/cr/cf action / rename / format',
             \ '     SPC rr       run current file',
             \ '',
-            \ '  5. git and windows',
+            \ '  6. git and windows',
             \ '     SPC gs/gd/gb status / diff / blame',
             \ '     SPC gl       log graph',
             \ '     <C-w>hjkl    split navigation',
             \ '     SPC z        maximize split',
             \ '',
             \ '  daily drill',
-            \ '     Open a project, run SPC SPC, jump with s, inspect with gd/K,',
+            \ '     Repeat: SPC SPC, s, gd/K, edit, SPC rr, SPC /, SPC gs.',
-            \ '     edit with gc/SPC cf, check SPC gs, then save with SPC w.',
             \ ]
     else
         let l:lines = [
             \ '  chopsticks tutor        q close',
             \ '  ───────────────────────────────',
             \ '',
+            \ '  Goal: train one long-term project loop around Vim.',
+            \ '',
             \ '  classic layout',
             \ '     ,?         active cheat sheet',
             \ '     ,w / ,x    save / save and quit',

scripts/test-vim.sh

@@ -268,11 +268,15 @@ check_vim() {
 
     XDG_CONFIG_HOME="$EMPTY_XDG" vim -u .vimrc -i NONE -es -N \
         -c 'call feedkeys("\<Space>?", "xt")' \
+        -c 'if max(map(getline(1, "$"), "strdisplaywidth(v:val)")) > 42 | cquit | endif' \
         -c "redir! > $TMP_ROOT/cheat-default.txt" \
         -c 'silent %print' \
         -c 'redir END' \
         -c 'qa!' 2>&1
     grep -Fq ':ChopsticksStatus   check LSP setup' "$TMP_ROOT/cheat-default.txt"
+    grep -Fq 'trained loop:' "$TMP_ROOT/cheat-default.txt"
+    grep -Fq 'files → s jump → gd/K' "$TMP_ROOT/cheat-default.txt"
+    grep -Fq 'run → grep → git' "$TMP_ROOT/cheat-default.txt"
     grep -Fq 'SPC SPC   files' "$TMP_ROOT/cheat-default.txt"
     grep -Fq 'gd        definition' "$TMP_ROOT/cheat-default.txt"
     grep -Fq 'K         hover docs' "$TMP_ROOT/cheat-default.txt"
@@ -296,6 +300,7 @@ check_vim() {
 
     XDG_CONFIG_HOME="$EMPTY_XDG" vim -u .vimrc -i NONE -es -N \
         -c 'ChopsticksCheatSheet' \
+        -c 'if max(map(getline(1, "$"), "strdisplaywidth(v:val)")) > 42 | cquit | endif' \
         -c "redir! > $TMP_ROOT/cheat-command.txt" \
         -c 'silent %print' \
         -c 'redir END' \
@@ -307,11 +312,15 @@ check_vim() {
         -c 'let g:chopsticks_keymap_style = "classic"' \
         -c 'source .vimrc' \
         -c 'normal ,?' \
+        -c 'if max(map(getline(1, "$"), "strdisplaywidth(v:val)")) > 42 | cquit | endif' \
         -c "redir! > $TMP_ROOT/cheat-classic.txt" \
         -c 'silent %print' \
         -c 'redir END' \
         -c 'qa!' 2>&1
     grep -Fq ',ff       files' "$TMP_ROOT/cheat-classic.txt"
+    grep -Fq 'trained loop:' "$TMP_ROOT/cheat-classic.txt"
+    grep -Fq 'files → jump → inspect' "$TMP_ROOT/cheat-classic.txt"
+    grep -Fq 'run → grep → git' "$TMP_ROOT/cheat-classic.txt"
     grep -Fq ',dd       definition' "$TMP_ROOT/cheat-classic.txt"
     grep -Fq ',dk       hover docs' "$TMP_ROOT/cheat-classic.txt"
     grep -Fq ',dp ,dn   LSP diagnostics' "$TMP_ROOT/cheat-classic.txt"
@@ -326,6 +335,7 @@ check_vim() {
         -c 'let g:chopsticks_profile = "minimal"' \
         -c 'source .vimrc' \
         -c 'call feedkeys("\<Space>?", "xt")' \
+        -c 'if max(map(getline(1, "$"), "strdisplaywidth(v:val)")) > 42 | cquit | endif' \
         -c "redir! > $TMP_ROOT/cheat.txt" \
         -c 'silent %print' \
         -c 'redir END' \
@@ -340,6 +350,7 @@ check_vim() {
         -c 'let g:chopsticks_keymap_style = "space"' \
         -c 'source .vimrc' \
         -c 'call feedkeys("\<Space>?", "xt")' \
+        -c 'if max(map(getline(1, "$"), "strdisplaywidth(v:val)")) > 42 | cquit | endif' \
         -c "redir! > $TMP_ROOT/cheat-space.txt" \
         -c 'silent %print' \
         -c 'redir END' \
@@ -356,11 +367,14 @@ check_vim() {
 
     XDG_CONFIG_HOME="$EMPTY_XDG" vim -u .vimrc -i NONE -es -N \
         -c 'ChopsticksTutor' \
+        -c 'if max(map(getline(1, "$"), "strdisplaywidth(v:val)")) > 78 | cquit | endif' \
         -c "redir! > $TMP_ROOT/tutor-default.txt" \
         -c 'silent %print' \
         -c 'redir END' \
         -c 'qa!' 2>&1
     grep -Fq 'chopsticks tutor' "$TMP_ROOT/tutor-default.txt"
+    grep -Fq 'Goal: train one long-term project loop around Vim.' "$TMP_ROOT/tutor-default.txt"
+    grep -Fq '1. trained loop' "$TMP_ROOT/tutor-default.txt"
     grep -Fq 'SPC ?      active cheat sheet' "$TMP_ROOT/tutor-default.txt"
     grep -Fq 'SPC fc     edit local config' "$TMP_ROOT/tutor-default.txt"
     grep -Fq ':ChopsticksHelp    full help' "$TMP_ROOT/tutor-default.txt"
@@ -373,23 +387,28 @@ check_vim() {
         -c 'let g:chopsticks_keymap_style = "classic"' \
         -c 'source .vimrc' \
         -c 'ChopsticksTutor' \
+        -c 'if max(map(getline(1, "$"), "strdisplaywidth(v:val)")) > 78 | cquit | endif' \
         -c "redir! > $TMP_ROOT/tutor-classic.txt" \
         -c 'silent %print' \
         -c 'redir END' \
         -c 'qa!' 2>&1
     grep -Fq 'classic layout' "$TMP_ROOT/tutor-classic.txt"
+    grep -Fq 'Goal: train one long-term project loop around Vim.' "$TMP_ROOT/tutor-classic.txt"
     grep -Fq ',?         active cheat sheet' "$TMP_ROOT/tutor-classic.txt"
     grep -Fq ',ec       edit local config' "$TMP_ROOT/tutor-classic.txt"
     grep -Fq ',S + 2 chars  EasyMotion jump' "$TMP_ROOT/tutor-classic.txt"
 
     XDG_CONFIG_HOME="$EMPTY_XDG" vim -u .vimrc -i NONE -es -N \
         -c 'ChopsticksBeta' \
+        -c 'if max(map(getline(1, "$"), "strdisplaywidth(v:val)")) > 78 | cquit | endif' \
         -c "redir! > $TMP_ROOT/beta-guide.txt" \
         -c 'silent %print' \
         -c 'redir END' \
         -c 'qa!' 2>&1
     grep -Fq 'chopsticks beta' "$TMP_ROOT/beta-guide.txt"
-    grep -Fq 'Prove the v3 Space layout in real editing before release.' "$TMP_ROOT/beta-guide.txt"
+    grep -Fq 'Prove this can be a long-term project loop.' "$TMP_ROOT/beta-guide.txt"
+    grep -Fq 'Record real editing friction, not abstract taste.' "$TMP_ROOT/beta-guide.txt"
+    grep -Fq 'no private wiki is needed to remember the daily loop' "$TMP_ROOT/beta-guide.txt"
     grep -Fq 'SPC ?     active cheat sheet' "$TMP_ROOT/beta-guide.txt"
     grep -Fq 'BETA.md        full beta checklist and rollback' "$TMP_ROOT/beta-guide.txt"
     grep -Fq ':ChopsticksBetaLog      editable local beta notes' "$TMP_ROOT/beta-guide.txt"