docs(website): add keybindings guide to the docs site

.changeset/website-keybindings-docs.md

@@ -0,0 +1,2 @@
+---
+---

website/astro.config.mjs

@@ -89,6 +89,7 @@ export default defineConfig({
             { label: "Configuration", slug: "docs/configure/configuration" },
             { label: "Themes", slug: "docs/configure/themes" },
             { label: "Layout and display", slug: "docs/configure/layout-and-display" },
+            { label: "Keybindings", slug: "docs/configure/keybindings" },
           ],
         },
         {

website/src/content/docs/docs/configure/keybindings.md

@@ -0,0 +1,36 @@
+---
+title: Keybindings
+description: Remap Hunk's named commands to your own keys with the user-config keybindings table.
+---
+
+Every keyboard shortcut is a named command. A `[keybindings]` table in your user config maps command ids to the chords you want them on:
+
+```toml
+[keybindings]
+"hunk.app.quit" = "ctrl+x"               # one chord
+"hunk.review.nextHunk" = ["]", "ctrl+n"] # several chords for one command
+"hunk.review.focusFilter" = "f"          # takes "f" away from page-down
+"hunk.view.toggleMenuBar" = false        # unbind it entirely
+"myext.toggle" = "ctrl+g"                # extension commands too
+```
+
+Every id starts with the name of whoever owns the command: Hunk's own commands live under `hunk.`, and an extension's live under its extension id. `hunk` is a reserved extension id, so an extension can never shadow a built-in command.
+
+## Rules
+
+- **User bindings replace defaults.** The chords you list are the complete set of keys that command answers to.
+- **A key you bind is yours.** Any command holding the same chord only as a default gives it up and keeps its other keys.
+- **`false` (or `[]`) unbinds a command**, leaving its keys doing nothing.
+- Two entries claiming one chord is a conflict: the first in the file wins and the session reports the other. Unknown ids and unusable chords are reported the same way, and the rest of the table still applies.
+
+## Chord grammar
+
+Chords join `ctrl`, `alt`/`option`, `cmd`/`meta`, and `shift` with `+` around a base key: a character (`"y"`, `"["`), an uppercase letter for its shifted form (`"G"`), or a named key (`"tab"`, `"pageup"`, `"left"`, `"f2"`). `shift` applies to letters and named keys only — for a shifted symbol or digit, write the character shift produces (`"!"`, not `"shift+1"`), since that is what terminals report.
+
+## Find command ids
+
+The menus and the in-app help (`?`) always show the keys each command currently holds, so a remap changes what they advertise. The full table of built-in command ids and their default keys lives in [`docs/keybindings.md`](https://github.com/modem-dev/hunk/blob/main/docs/keybindings.md) in the repository. Commands listed without a default key are menu items today; binding one gives it a shortcut like any other.
+
+Keys owned by a dialog, menu, or focused text input — `Esc`, `Enter`, `Ctrl-S` while writing a note — belong to those widgets and are not remappable.
+
+`[keybindings]` is read from your user config only, never from a repository's `.hunk/config.toml`: which keys do what is a property of your keyboard and habits, so a checkout you review cannot rearrange them.

website/src/content/docs/docs/index.mdx

@@ -54,5 +54,6 @@ Hunk is a terminal diff viewer for reviewing complete changesets and keeping age
 - [Configure Hunk as a Git pager or difftool](/docs/workflows/git-pager-and-difftool/)
 - [Review a live session with a coding agent](/docs/agents/review-with-an-agent/)
 - [Choose a theme and layout](/docs/configure/themes/)
+- [Remap a keyboard shortcut](/docs/configure/keybindings/)
 - [Look up a command](/docs/reference/cli/)
 - [Troubleshoot terminal behavior](/docs/help/troubleshooting/)

website/src/content/docs/docs/start/keyboard-and-mouse.md

@@ -54,4 +54,8 @@ Press `c` on the selected hunk or use a visible add-note affordance with the mou
 - Use the wheel or scrollbar to move through the review; hold Shift while scrolling to move horizontally through unwrapped code.
 - Select diff text for copy where the terminal supports it.
 
+## Remap the defaults
+
+Every shortcut above is a named command you can move to different keys with a `[keybindings]` table in your user config. See [Keybindings](/docs/configure/keybindings/).
+
 Terminal mouse protocols vary; see [terminal compatibility](/docs/help/compatibility/) if clicks or selection do not behave as expected.