docs: Starting point for minimode and helix mode

content/docs/architecture/minimode.smd

@@ -0,0 +1,110 @@
+---
+.title = "Minimodes",
+.date = @date("2025-10-15T00:00:00"),
+.author = "Igor Támara",
+.layout = "index.shtml",
+.draft = false,
+---
+
+Minimodes can be used by other modes adding functionality
+to the editor, they have their own set of keybindings and
+are used momentarily for an specific action, i.e. find
+something in the current buffer or in project files,
+open/save a file, and, in modal modes(like vim and helix).
+An example of the latter is using numeric prefixes to
+repeat an action many times.
+
+## Anatomy of minimodes
+
+To create a minimode it's needed:
+
+* A Keybinding
+* An Action mapping
+* A Minimode definition
+
+### Keybinding
+
+When a key or a keystroke(set of keys) are pressed, the
+associated minimode gets activated and will start to
+capture the key/strokes until a special keybinding
+makes it exit, or an specific action exits the minimode.
+Head to `src/keybind/builtin/flow.json`(flow keybinds)
+and look for `mini_find`, where you will know which
+specific actions are triggered by the keybindings of the
+minimode.
+
+### Action mapping
+
+Actions executed by each minimode are stored one per
+file under `src/tui/mode/mini/`. The command that
+opens opens the door to the minimode is linked from
+`src/tui/tui.zig` which calls them dynamically when needed.
+
+Look for `mini` inside `tui.zig` to find out which minimodes
+are present and where to look to learn how each minimode
+does its own task.
+
+### Minimode definition
+
+Possibly the simplest minimode that will be found that does
+not require defining a particular widget is the `replace`
+minimode, used in helix mode and vim mode.  To enter the
+minimode in Helix while in `NOR` or `INS` use the keybind
+**r**, it consumes another key and replaces the current
+character under the main cursor with the pressed key.
+If there are multiple selections, all the characters are
+replaced by the one typed after **r**.
+
+- The minimode needs to expose a `create` function with
+type
+
+```zig
+pub fn create(Allocator,command.Context) !struct { tui.Mode, tui.MiniMode }
+```
+Which is in charge of registering the minimode to be able
+to receive events and will offer the minimode name, the
+one that appears in the lower status bar while it is active,
+to let it be known that the minimode is active. This is
+where all the instatiations are made. Which leads to
+
+- The `deinit` function whose type is
+
+```zig
+pub fn deinit(*Self)
+```
+
+- A `receive` function that will route events received
+casting the type:
+
+```zig
+pub fn receive(*Self, tp.pid_ref, tp.message) error{Exit}!bool
+```
+
+- A `commands` field that will expose the minimode `Collection`
+of `Commands`.
+
+An special command `mini_mode_insert_code_point` as an element
+of the commands collection with type:
+
+```zig
+pub fn mini_mode_insert_code_point(*Self, Ctx) Result
+```
+
+acting as the default handler of the key presses that the minimode
+will receive when there is no other defined.
+
+All the keys were handled and managed by the default "invisible"
+widget that processes the keys for the minimode.  And there is
+room for custom widgets that are explained next.
+
+## A custom widget
+
+When there is a need for an specialized widget, it's possible to
+define one, for example, the `file_browser` is used to load and
+save files, and `numeric_input` is used to set the tab width for
+example(look for it in the command palette `:`).
+
+
+* Head to [architecture](/docs/architecture)
+* Learn about [commands](/docs/architecture/command)
+* Review [keybindings](/docs/architecture/keybind)

content/docs/mode/helix.smd

@@ -0,0 +1,67 @@
+---
+.title = "Helix Mode",
+.date = @date("2025-10-10T00:00:00"),
+.author = "Igor Támara",
+.layout = "index.shtml",
+.draft = false,
+---
+
+This document describes implementation of Helix Mode.
+
+## What and what not
+
+The first and biggest difference is that Flow has a mode that
+emulates Helix, or at least has equivalent of the worthiest
+actions that can be done in Helix. The conversely is not true.
+
+`:` opens up Flow's rich command palette that might have
+functionalities Helix users are used to have, if you find
+something missing, it's possible to
+[open a Feature Request](https://github.com/neurocyte/flow/issues)
+to see if there is anyone interested in porting it.  Or maybe
+someone is already creating or interested in the one you are
+missing.  [Join Discord](https://discord.gg/kzJC9fA7) to ask
+if anyone is working on something similar or there is a
+workaoround.
+
+## Enhancing hx mode
+
+This is a programmer editor, you are more than welcome to
+enhance to suit your needs that maybe coincide with others.
+
+Please take a look at [architecture](/docs/architecture) and
+[contributing](/docs/contributing) for an overview and the
+mechanics of getting your changes into Flow.
+
+hx mode is modal kind, the same as vim mode, and the file
+that has the particular work to make it real is in
+`src/tui/mode/helix.zig`, adding a `command` and the
+corresponding `meta` is what is required.
+[More on commands](/docs/architecture/command).
+
+### Pickers
+
+Flow hx mode offers most of the picker types equivalents
+with `panels` and `palettes`.  Example of panels are
+the `g` `r` (go to reference from lsp) and `space` `/`
+(a.k.a find in files). Examples of `palettes` are
+`space` `b` to pick a buffer or `space` `f` to open a
+file in your project. Panels open below the editor
+while palettes open overlapping the working area.
+
+One medium sized project is to create a widget that
+has one input widget, two panels, on the left the
+list of options and on the right the preview of
+the selected option and offer various keybindings
+to manipulate the objects inside both panels with
+filtering.
+
+Given this, it's possible to start contributing via
+pull requesting [keybinds](/docs/architecture/keybind),
+[commands](/docs/architecture/command),
+[palettes](/docs/architecture/palette), or the
+special widget mentioned previously.
+
+
+More about the [architecture](/docs/architecture) or jump to
+[contribution guidelines](/docs/contributing).