From 93bea01c9ed3fcbebc64c9cef382a51d24c925ed Mon Sep 17 00:00:00 2001
From: Maze Winther <mazewinther@gmail.com>
Date: Mon, 2 Mar 2026 10:37:44 +0100
Subject: [PATCH] docs: update actions

---
 docs/actions.md | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/docs/actions.md b/docs/actions.md
index f9586a86..44c2153f 100644
--- a/docs/actions.md
+++ b/docs/actions.md
@@ -17,6 +17,29 @@ Add an entry to the `ACTIONS` object:
 },
 ```
 
+**If your shortcut uses a special key** (not a letter/digit), check `getPressedKey` in `src/stores/keybindings-store.ts` and add a case if it's missing:
+
+```typescript
+if (key === "escape") return "escape";
+```
+
+**If your action has a `defaultShortcuts`**, also add a keybindings migration so existing users get it (keybindings are persisted in localStorage — new defaults only apply to fresh installs):
+
+1. Create `src/stores/keybindings/migrations/vN-to-vN+1.ts`:
+
+```typescript
+export function vNToVN1({ state }: { state: unknown }): unknown {
+    const s = state as { keybindings: Record<string, string>; isCustomized: boolean };
+    const keybindings = { ...s.keybindings };
+    if (!keybindings["my-key"]) {
+        keybindings["my-key"] = "my-action";
+    }
+    return { ...s, keybindings };
+}
+```
+
+2. Register it in `src/stores/keybindings/migrations/index.ts` and bump `CURRENT_VERSION`.
+
 ### 2. Register the handler — `src/hooks/actions/use-editor-actions.ts`
 
 ```typescript