Prepare v3 beta candidate docs

BETA.md

@@ -0,0 +1,82 @@
+# Beta Testing
+
+This branch is the v3 beta candidate. Do not tag or publish it as `v3.0.0`
+until the checklist below is closed.
+
+## Install the beta
+
+Existing checkout:
+
+```bash
+cd ~/.vim
+git fetch origin
+git checkout release/v3-candidate
+git pull --ff-only
+vim -Nu ~/.vimrc -n -es +'PlugInstall --sync' +'qa!'
+```
+
+Fresh checkout:
+
+```bash
+git clone --branch release/v3-candidate https://github.com/m1ngsama/chopsticks.git ~/.vim
+ln -sf ~/.vim/.vimrc ~/.vimrc
+vim -Nu ~/.vimrc -n -es +'PlugInstall --sync' +'qa!'
+```
+
+Keep local choices in `${XDG_CONFIG_HOME:-~/.config}/chopsticks.vim`:
+
+```vim
+let g:chopsticks_profile = 'engineer'
+let g:chopsticks_keymap_style = 'space'
+```
+
+## Daily test loop
+
+Use the beta for real editing, not only demos. For each session, record:
+
+- The task: project navigation, code edit, grep, git, LSP, Markdown, SSH.
+- The first key you tried when you got stuck.
+- Whether `SPC ?`, `:ChopsticksTutor`, or `:ChopsticksStatus` answered it.
+- Any mapping that felt slow, awkward, surprising, or too easy to mistype.
+- Any documentation line that was wrong, missing, or redundant.
+
+## Workflows to exercise
+
+```text
+SPC SPC   find file              SPC /     grep project
+s + 2ch   jump on screen         gd / gr   definition / references
+SPC rr    run current file       SPC gs    git status
+SPC cf    format                 SPC ca    code action
+SPC ?     active cheat sheet     :ChopsticksStatus health
+```
+
+Also test the boring path: save, quit, reopen Vim, edit over SSH, open a large
+file, edit Markdown, and use a machine with missing optional tools.
+
+## Exit criteria
+
+- `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.
+- `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.
+- The beta has been tested on macOS and over SSH on Linux.
+
+## Roll back
+
+Return to the latest stable release:
+
+```bash
+cd ~/.vim
+git fetch origin --tags
+git checkout v2.2.0
+vim -Nu ~/.vimrc -n -es +'PlugInstall --sync' +'qa!'
+```
+
+Or keep the code but switch back to the legacy layout:
+
+```vim
+let g:chopsticks_keymap_style = 'classic'
+```

CHANGELOG.md

@@ -1,6 +1,6 @@
 # Changelog
 
-## Unreleased
+## 3.0.0-beta.1 — 2026-05-23
 
 ### Breaking
 

CONTRIBUTING.md

@@ -5,7 +5,7 @@
 1. **No Node.js in the Vim runtime.** Plugins must work with pure VimScript — no coc.nvim or other Node-backed completion engines. External CLIs (prettier, eslint, markdownlint, stylelint, tsc) installed via npm are fine; ALE shells out to them as optional system tools, not as part of the Vim runtime.
 2. **Startup matters.** Run `vim -u .vimrc -i NONE --startuptime /tmp/s.log -es -N -c qa!` before and after. If your change adds >1ms, it needs a good reason.
 3. **Works on TTY.** Test over SSH. If it breaks in a terminal without true color, fix it or gate it behind `g:is_tty`.
-4. **Native-first keymaps.** Enhance Vim's native behavior instead of replacing it. Do not override built-in motions, operators, text objects, or help-oriented keys for discoverability alone; prefer leader-prefixed or otherwise non-conflicting ergonomic mappings.
+4. **Native-first keymaps.** Enhance Vim's native behavior instead of replacing it. Do not override built-in motions, operators, text objects, or help-oriented keys for discoverability alone. Rare exceptions, such as the default Space-layout `s` jump, must have a documented native replacement, cheat-sheet coverage, and a classic-layout fallback.
 5. **One module, one concern.** Don't put git config in lsp.vim.
 
 ## Adding a plugin
@@ -14,7 +14,7 @@
 2. If it's not needed at startup, lazy-load it: `Plug 'foo/bar', { 'on': 'FooCommand' }`
 3. Put config in the appropriate module
 4. Check new mappings against native Vim behavior before adding them
-5. Update the cheat sheet in `modules/tools.vim` if you add keybindings
+5. Update the cheat sheet definitions in `modules/cheatsheet.vim` if you add keybindings
 6. Run `scripts/test.sh vim` locally after installing plugins
 7. Test on both macOS and Linux when changing terminal or package-manager behavior
 

QUICKSTART.md

@@ -141,4 +141,5 @@ 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. See the [wiki](https://github.com/m1ngsama/chopsticks/wiki) for deep dives.
+See [README](README.md) for the full reference. For beta testing and rollback,
+see [BETA.md](BETA.md).

README.md

@@ -24,6 +24,9 @@
 curl -fsSL https://raw.githubusercontent.com/m1ngsama/chopsticks/main/get.sh | bash
 ```
 
+This branch is a v3 beta candidate, not a tagged stable release. Use
+[BETA.md](BETA.md) when testing the Space keymap before promotion.
+
 ---
 
 ## Why
@@ -315,7 +318,8 @@ Each module is self-contained. Comment out one line in `.vimrc` to disable it. A
 | Everything slow     | Large file? Auto-disabled >10MB               |
 | What's installed?   | `:ChopsticksStatus` shows tools, LSP, linters |
 
-More in the [wiki](https://github.com/m1ngsama/chopsticks/wiki).
+For deeper checks, start with `:ChopsticksStatus`, `SPC ?`,
+`:ChopsticksTutor`, and [QUICKSTART.md](QUICKSTART.md).
 
 ## Contributing
 

modules/cheatsheet.vim

@@ -75,7 +75,7 @@ function! s:CheatSheet() abort
 
         call extend(l:lines, [
             \ '  SPC rr    run file',
-            \ '  SPC cW    strip trailing  (v)',
+            \ '  SPC cW    strip trailing',
             \ '  SPC c=    re-indent file  (opt-in)',
             \ '  SPC =     re-indent       (v)',
             \ ])
@@ -222,7 +222,7 @@ function! s:CheatSheet() abort
         \ '  Alt+j/k   move line      (v)',
         \ '  ,*        replace word    (v)',
         \ '  ,F        re-indent       (v)',
-        \ '  ,W        strip trailing  (v)',
+        \ '  ,W        strip trailing',
         \ '',
         \ '  ── git ───────────────────',
         \ '  ,gs       status',

scripts/test-quick.sh

@@ -26,7 +26,7 @@ check_shell() {
 check_docs() {
     step "Markdown lint"
     need markdownlint
-    markdownlint README.md QUICKSTART.md CONTRIBUTING.md CHANGELOG.md
+    markdownlint README.md QUICKSTART.md CONTRIBUTING.md CHANGELOG.md BETA.md
 
     if command -v vhs >/dev/null 2>&1; then
         vhs validate .github/demo.tape