Add initial docs for command, editor, keybind, palette

content/docs/architecture/keybind.smd

@@ -0,0 +1,145 @@
+---
+.title = "Keybinding",
+.date = @date("2025-10-19T00:00:00"),
+.author = "Igor Támara",
+.layout = "tutorial.shtml",
+.draft = false,
+.custom = { .githubedit = "https://github.com/neurocyte/flow-website/tree/master/content/docs/architecture/keybind.md"},
+---
+
+If you are here, it's possible that you already have edited your
+own keybinds to suit your needs and are looking for some advanced
+topics to extend your use cases and make everything easier and
+fluid when in Flow. If you have not, take a peek to learning how
+to do it.
+
+Using the command palette `Ctrl+Shift+p` and typing **Edit key bindings**,
+takes you to the json file to extend Flow configuring
+keybindings to suit your needs.
+
+[]($section.id('tldr'))
+## ;TLDR;
+
+Once you open the corresponding json file, locate inside the imode
+(internal mode) that will accept the key or keys/combo and add an
+array, where the first element is the combination to map to the
+commands that will happen, the array accepts strings like in
+
+```js
+["ctrl+alt+shift+p", "open_command_palette"]
+```
+
+To avoid screwing up the combinations, and putting Flow in an unusable
+state derived from a wrong mapping of key combinations, read on.
+
+## Resetting keys to factory defaults
+
+User configured keybindings are stored in Flow's configuration
+directory under `keys/mode.json` where mode can be `flow`,
+`emacs`, `vim`, `helix` or customized ones. Removing the keys
+directory or the particular mode file can take you out from a
+broken state.
+
+## Keybinds for each mode
+
+Keybinds are edited per mode, and other modes inherit what is
+defined in your `flow.json` keybindings. Each mode override keybindings
+of its parent mode. For example, if you are in **emacs** mode you will
+be redirected to `emacs.json` and it will override the keybindings from
+flow.
+
+[introducing keybindings](/devlog/2024#2024-12-05T20:55:00) showcases
+how to get to edit keybindings.
+
+## Keybindings hierarchy
+
+Some terminology
+
+* **Mode**: Stored in a json file, like flow mode declared in `flow.json`.
+* **Imode**: under the json file.
+* **Major Imode**: `project` or descendant from `project`.
+* **Minimodes**: To be used momentarily and do not inherit from `project`.
+
+In general a keybinding json shows this hierarchy:
+
+```
+Mode > Imode > press > Key and commands
+map > map   > array > array(array(string,numbers),strings,numbers)
+```
+
+`Mode` is the json file that holds a map, where each
+entry has a map called `press` that is an array of
+arrays.
+
+`project` is the main imode in `flow.json` and it can be
+noticed that `normal` imode `inherit`s from `project`,
+some modes have `release`, usually one will be using
+only `press` inside `normal` imode or the specific mode
+if inside `vim`, `helix` or `emacs` modes.
+
+Looking further, it can be seen that
+[minimodes](/docs/architecture/minimode) have their
+keybinding mappings defined in a particular imode.
+
+As stated previously, there is a mode hierarchy, the main mode
+is flow and other modes inherit from it. We remind that also
+imodes have a hierarchy and it's common for major imodes to be
+descendants from `project`.
+
+## Adding a Keybinding
+
+The most basic case to map a keybind to a command was covered in
+[TLDR](#tldr) which used the combination of three keys pressed
+simultaneously `ctrl`, `shift` and `p`, all of them where combined
+with `+` to execute the command `open_command_palette`.
+
+A common use case is to add a keybinding to invoke an already
+existing command and chain it to another, making Flow more suited to your
+own needs.
+
+[]($section.id('shell'))
+## Running shell commands
+
+For example, `f5` by default is used to run `zig build test`
+outputting its results to a *scratch buffer* called `test`.
+
+```js
+["f5", ["create_scratch_buffer", "*test*"], ["shell_execute_insert", "zig", "build", "test"]],
+```
+
+Note that:
+
+The keybind is `f5`, which maps to the `f5` keycode. is invoking
+`create_scratchbuffer`, receiving the parameter `*test*` which
+results in creating a scratch buffer if didn't exist. And
+then executing the command `shell_execute_insert` that receives
+the paramaters `zig`, `build`, `test`. This latter command is
+executing a shell command called `zig` with the parameters
+`build` and `test`; if you don't have zig installed, it will
+not work, and you might want to remap f5 to a different shell
+command.
+
+```
+[
+  "f5",
+  [
+    "create_scratch_buffer",
+    "*test*"
+  ],
+  [
+    "shell_execute_insert",
+    "zig",
+    "build",
+    "test"
+  ]
+]
+```
+
+Observe [tasks running](/devlog/2025#2025-01-26T22:11:00) and maybe
+consider using more keybindings or running tasks for your projects.
+
+Probably binding commands is good, but maybe there is a feature in
+other texts editors that you miss and would love to have it at
+your fingertips. Then it's Zig time:
+[Adding commands](/docs/architecture/command) to flow.
+