epic(navigation): configurable key bindings and shell-native worktree completion #43

Goal

Align cj's navigation UX around two separate mechanisms:

• configurable Ctrl/Alt+O behavior for general directory navigation
• shell-native cd -jw<Tab> completion for Git worktrees

This epic preserves the existing worktree selector, generated shell wrappers, configurable OS-specific chords, and the planned browser-style history stack while removing the accidental coupling between the global key binding and Git worktrees.

Agreed behavior

Configured navigation key

• key bindings are installed from per-OS TOML configuration
• each binding has an ordered behavior chain containing zoxide and/or cj
• behavior order is explicit; cj never changes behavior merely because a dependency happens to be installed
• an unavailable or empty behavior advances to the next configured behavior
• cancellation stops the chain and preserves the command buffer and current directory
• a real execution error stops the chain and remains visible to the user
• zoxide inserts a safely quoted selection into the current command buffer and waits for Enter
• cj uses the shell-local browser-history stack without requiring fzf or zoxide
• an empty behavior chain disables the binding

Worktree completion

• cd -jw<Tab> and cd --jump-worktree<Tab> are included by cj init <shell> without a key-binding option
• Tab requests worktree candidates and lets the shell's completion system present them
• Bash, Zsh, Nushell, and PowerShell work without fzf
• fzf-tab or another shell completion frontend may render the candidates through fzf; cj does not launch a nested picker from Tab
• standalone cj -jw retains its explicit fzf picker behavior
• pressing Enter with an unresolved cd -jw or cd --jump-worktree token asks the user to press Tab and leaves the current directory unchanged

Initialization

• cj init <shell> installs the configured navigation binding by default
• --no-setup-key-binding disables it for one generated integration
• dependency availability is checked when the binding runs, so no --keybinding-rehash command is needed
• changing TOML still requires regenerating the integration, following the existing snapshot model

Non-goals

• combining worktrees and zoxide entries into one database
• silently replacing an explicitly selected behavior after a runtime error
• making the completions output own the cd wrapper; wrapper-specific completion remains in init

Delivery

The planned navigation work shipped in 0.4.0. Ordered configuration, browser history, configured widgets, and default initialization were delivered through #53, #54, #56, and #57. Linux and Windows CI passed before release.

• feat(shell): complete cd -jw with native shell candidates #40 — shell-native worktree completion
  • fix(zsh): offer worktree candidates when Tab replaces a jump token #49 — offer Zsh worktree candidates on the first Tab
  • feat(shell): use Tab for cd worktree selection #51 — require Tab for cd worktree selection
• feat(config): support ordered key-binding behaviors #44 — ordered key-binding configuration
• feat(shell): insert zoxide selections through configured key bindings #45 — zoxide command-buffer behavior
• feat(v1): replace downward route with browser-style directory history #36 — browser-style directory history
• feat(shell): complete browser-history destinations through configured key bindings #46 — cj browser-history key-binding behavior
• feat(init)!: install configured key bindings by default #47 — default initialization and opt-out lifecycle

Follow-up

#58 tracks post-release worktree completion fixes: trailing whitespace before Tab, safe Nushell path quoting, and abbreviated home-directory labels in Zsh/fzf-tab. Those changes are implemented and tested locally, including user verification, but are not yet pushed, merged, or released. #58 remains open independently of this completed delivery.