Update docs

.gitignore

@@ -2,6 +2,7 @@
 /.build
 # IDK, AppCode randomly creates this EMPTY file. I have no idea what this is
 /default.profraw
+/.DS_Store
 
 # XCode User settings
 xcuserdata/

docs/commands.md

@@ -129,8 +129,16 @@ found layout.
 mode name_of_the_target_mode
 ```
 
+Activate the specified [binding mode](./guide.md#bindings-modes)
+
 ## move-container-to-workspace
 
+```
+move-container-to-workspace target_workspace_name
+```
+
+Moves currently focused window to the specified workspace
+
 ## move-through
 
 ```
@@ -227,10 +235,53 @@ v_list
 
 ## move-workspace-to-display
 
+```
+move-workspace-to-display (next|prev)
+```
+
+Moves currently active workspace to the next or previous display
+
 ## reload-config
 
+```
+reload-config
+```
+
+Reloads currently active config. This command doesn't have any arguments.
+
 ## resize
 
+```
+resize (smart|width|height) [+|-]number
+```
+
+Resizes the currently active window
+
+The dimension to resize is chosen by the first argument
+
+- `width` changes width
+- `height` changes height
+- `smart` changes width if the parent has horizontal orientation, and it changes height if the parent has vertical orientation
+
+Second argument controls how much the size is changes
+
+- If the `number` is prefixed with `+` then the dimension is increased
+- If the `number` is prefixed with `-` then the dimension is decreased
+- If the `number` is prefixed with neither `+` nor `-` then the command changes the absolute value of the dimension
+
 ## workspace-back-and-forth
 
+```
+workspace-back-and-forth
+```
+
+Switches between currently active workspace and previously active workspace back and forth. This command doesn't have any
+arguments.
+
 ## workspace
+
+```
+workspace target_workspace_name
+```
+
+Activates the specified workspace

docs/guide.md

@@ -2,19 +2,51 @@
 
 **Table of contents**
 
+- [Configuring AeroSpace](#configuring-aerospace)
+  - [Binding modes](#bindings-modes)
+  - [Commands](#commands)
 - [Tree](#tree)
   - [Layouts](#layouts)
   - [Normalization](#normalization)
   - [Floating windows](#floating-windows)
-- [Default keybindings](#default-keybindings)
-- [Configuring AeroSpace](#configuring-aerospace)
-  - [Binding modes](#bindings-modes)
-  - [Commands](#commands)
 - [Emulation of virtual workspaces](#emulation-of-virtual-workspaces)
   - [A note on mission control](#a-note-on-mission-control)
   - [A note on 'Displays have separate Spaces'](#a-note-on-displays-have-separate-spaces)
 - [Multiple displays](#multiple-displays)
 
+## Configuring AeroSpace
+
+AeroSpace will read config file from `~/.aerospace.toml`. Please see the following config samples:
+- The default config contains all possible keys with comments: [default-config.toml](../config-examples/default-config.toml)
+- i3 like config: [i3-like-config-example.toml](../config-examples/i3-like-config-example.toml)
+
+AeroSpace uses TOML format for the config. TOML is easy to read, and it supports comments. See [TOML site for more
+info](https://toml.io/en/)
+
+### Binding modes
+
+You can create multiple sets of bindings by creating different binding modes. When you switch to a different binding mode, all
+the bindings from the current mode are deactivated, and only the bindings specified in the new mode become active. The initial
+binding mode that AeroSpace starts out with is "main".
+
+This feature is absolutely identical to the one [in i3](https://i3wm.org/docs/userguide.html#binding_modes)
+
+Working with binding modes consists of two parts: 1. defining a binding to switch to the binding mode and 2. declaring the binding
+mode itself.
+
+```toml
+[mode.main.binding] # Declare 'main' binding mode
+alt-r = 'mode resize' # 1. Define a binding to switch to 'resize' mode
+
+[mode.resize.binding] # 2. Declare 'resize' binding mode
+minus = 'resize smart -50'
+equal = 'resize smart +50'
+```
+
+### Commands
+
+AeroSpace is controlled by commands. For more info see [the list of all available commands](./commands.md).
+
 ## Tree
 
 AeroSpace stores all windows and containers in a tree. AeroSpace tree tiling model is [inspired by
@@ -123,41 +155,49 @@ enable-normalization-opposite-orientation-for-nested-containers = false
 ```
 
 ### Floating windows
-TODO DOCUMENTATION
 
-Normally, floating windows are not part of the tiling tree. But it's not the case with `focus` command. From `focus` command
-perspective, floating windows are part of the tree. 
+Normally, floating windows are not considered to be part of the [tiling tree](#tree). But it's not the case with
+[`focus`](./commands.md#focus) command.
 
-## Default keybindings
+From [`focus`](./commands.md#focus) command perspective, floating windows are part of [the tree](#tree). The floating window
+parent is determined as the smallest tiling container that contains the center of the floating window.
 
-TODO DOCUMENTATION the idea behind default keybindings
+This technique eliminates the need for an additional binding for focusing floating windows.
 
-## Configuring AeroSpace
+## Emulation of virtual workspaces
 
-AeroSpace will read config file from `~/.aerospace.toml`. Please see the following config samples:
-- The default config contains all possible keys with comments: [default-config.toml](../config-examples/default-config.toml)
-- i3 like config: [i3-like-config-example.toml](../config-examples/i3-like-config-example.toml)
+Native macOS Spaces have a lot of problems.
 
-AeroSpace uses TOML format for the config. TOML is easy to read, and it supports comments. See [TOML site for more
-info](https://toml.io/en/)
+- The animation for Spaces switching is slow
+  - You can't disable animation for Spaces switching (you can only make it slightly faster by turning on `Reduce motion` setting,
+    but it's suboptimal)
+- You have a limit of Spaces (up to 16 Spaces with one monitor)
+- You can't create, delete, reorder Spaces with hotkeys
+- Apple doesn't provide public API to create, delete, reorder and switch Spaces
 
-### Binding modes
-TODO DOCUMENTATION. For now you can refer to https://i3wm.org/docs/userguide.html#binding_modes
+Since Spaces are so hard to deal with, AeroSpace reimplements Spaces and calls them "Workspaces". The idea is that if the
+workspace isn't active then all of its windows are placed outside of the visible area of the screen. Once you switch back to the
+workspace, (by the means of [`workspace`](./commands.md#workspace) command, or by choosing the workspace in the tray icon list)
+windows are placed back to the visible area of the screen.
 
-### Commands
+When you exit the AeroSpace or when the AeroSpace is about to crash, AeroSpace will place all windows back to the visible area of
+the screen.
 
-AeroSpace is controlled by commands. For more info see [the list of all available commands](./commands.md).
+> [!NOTE]
+> For better or worse, macOS doesn't allow to place windows outside of the visible area entirely. You will still be able to see a
+> few pixels of "hidden" windows in the bottom right corner of your screen. That means, that if AeroSpace crashes badly you will
+> still be able to manually "unhide" the windows by dragging these few pixels to the center of the screen.
 
-## Emulation of virtual workspaces
+The supposed workflow of using AeroSpace workspaces is to only have one macOS Space (or as many as monitors you have, if `Displays
+have separate Spaces` is enabled) and don't interact with macOS Spaces anymore.
 
-The supposed workflow is to only have one macOS Space (or as many as monitors you have) and don't interact with macOS spaces in
-any way
+### A note on mission control
 
-When user quits AeroSpace or before crashing, AeroSpace puts windows back to the center of the screen
+For some reason, mission control doesn't like that AeroSpace puts a lot of windows in the bottom right corner of the screen.
+Mission control shows windows too small even if it has enough space to show them bigger.
 
-### A note on mission control
-TODO DOCUMENTATION
-Enable 'Group windows by application'
+To workaround it, you can enable `System Settings -> Desktop & Dock -> Group windows by application` setting. For some weird
+reason, it helps.
 
 ### A note on 'Displays have separate Spaces'
 
@@ -174,6 +214,26 @@ Overview of 'Displays have separate Spaces'
 
 
 ## Multiple displays
-TODO DOCUMENTATION
-TODO DOCUMENTATION. Add difference with i3
 
+- The pool of workspaces is shared between displays
+- Each display shows its own workspace. These workspaces are called "active" workspaces
+- Different displays can't show the same workspace at the same time
+- Each workspace (even invisible, even empty) has a display assigned to it
+- By default, all workspaces are assigned to the "main" display (You can find the "main" display in `System -> Displays`)
+
+When you switch to a workspace:
+1. AeroSpace takes the assigned display of the workspace and makes the workspace active on the display
+2. AeroSpace focuses the workspace
+
+You can move workspace to a different display with [`move-workspace-to-display`](./commands.md#move-workspace-to-display) command. 
+
+The idea of making pool of workspaces shared is based on **the observation** that most users have a limited set of workspaces on
+their secondary displays. Secondary displays are frequently dedicated to specific tasks (browser, shell), or for monitoring
+various activities such as logs and dashboards. Thus, using one workspace per each secondary displays and "the rest" on the main
+display often makes sense.
+
+> [!NOTE]
+> The only difference between AeroSpace and i3 is switching to empty workspaces. When you switch to an empty workspace, AeroSpace
+> puts the workspace on an assigned display; i3 puts the workspace on currently active display.
+> - I find that AeroSpace model works better with **the observation** listed above.
+> - AeroSpace model is more consistent (it works the same for empty workspaces and non-empty workspaces)