Add comprehensive documentation: COMMANDS.md, USAGE.md, and enhanced README.md

Co-authored-by: squassina <8495707+squassina@users.noreply.github.com>
2026-05-02 06:46:29 -04:00 · 2026-02-18 09:01:16 +00:00 · 2026-02-18 09:01:16 +00:00 · df6b10f331
commit df6b10f331
parent 7df8631fa3
3 changed files with 2191 additions and 17 deletions
--- a/USAGE.md
+++ b/USAGE.md
@ -0,0 +1,739 @@
+# MangoWC Usage Guide
+
+A practical guide to using MangoWC in your daily workflow.
+
+## Table of Contents
+
+- [Getting Started](#getting-started)
+- [Understanding Tags](#understanding-tags)
+- [Working with Layouts](#working-with-layouts)
+- [Window Management Patterns](#window-management-patterns)
+- [Using the Scratchpad](#using-the-scratchpad)
+- [Overview Mode](#overview-mode)
+- [Multi-Monitor Workflows](#multi-monitor-workflows)
+- [Customization Tips](#customization-tips)
+- [Common Workflows](#common-workflows)
+
+---
+
+## Getting Started
+
+### Your First Session
+
+1. **Launch MangoWC** from your display manager or run `mango` from TTY
+2. **Open a terminal:** Press `Alt + Return`
+3. **Open an application:** Press `Alt + Space` for the launcher
+4. **Navigate windows:** Use `Alt + Arrow Keys`
+5. **Close a window:** Press `Alt + Q`
+
+### Essential First-Day Shortcuts
+
+These are the absolute minimum you need to be productive:
+
+```
+Alt + Return         → Terminal
+Alt + Space          → App launcher
+Alt + Q              → Close window
+Alt + Arrow Keys     → Focus different window
+Ctrl + 1-9           → Switch tags (workspaces)
+Alt + \              → Toggle floating
+Super + R            → Reload config
+Super + M            → Exit MangoWC
+```
+
+---
+
+## Understanding Tags
+
+### What Are Tags?
+
+Tags are like workspaces, but more flexible. Think of them as labels you can apply to windows.
+
+**Key differences from workspaces:**
+- A window can have multiple tags
+- You can view multiple tags at once
+- Each tag can have its own layout
+
+### Basic Tag Usage
+
+**Switch to a tag:**
+```
+Ctrl + 1    → View tag 1
+Ctrl + 2    → View tag 2
+... and so on
+```
+
+**Move window to a tag:**
+```
+Alt + 1     → Move current window to tag 1 (and switch to it)
+Alt + 2     → Move current window to tag 2 (and switch to it)
+```
+
+**Navigate through tags:**
+```
+Super + Left/Right         → Previous/next tag
+Ctrl + Left/Right          → Previous/next tag that has windows
+```
+
+### Advanced Tag Techniques
+
+**View multiple tags simultaneously:**
+1. Switch to tag 1: `Ctrl + 1`
+2. Toggle tag 2 visibility: `Super + 2` (if configured)
+3. Now you see windows from both tags
+
+**Silent tag movement** (move window without following):
+```conf
+# In config.conf
+bind=Alt+Shift,1,tagsilent,1
+```
+
+### Organizing Your Workflow with Tags
+
+**Example organization:**
+```
+Tag 1: Browsers          (monocle layout)
+Tag 2: Code editors      (tile or center_tile layout)
+Tag 3: Terminals         (scroller layout)
+Tag 4: Communication     (grid layout)
+Tag 5: Media             (monocle layout)
+Tag 6-9: Project-specific
+```
+
+**Setting layouts per tag in config.conf:**
+```conf
+tagrule=id:1,layout_name:monocle
+tagrule=id:2,layout_name:center_tile
+tagrule=id:3,layout_name:scroller
+tagrule=id:4,layout_name:grid
+tagrule=id:5,layout_name:monocle
+```
+
+---
+
+## Working with Layouts
+
+### Available Layouts
+
+MangoWC includes 9 built-in layouts:
+
+#### 1. Tile (Master-Stack)
+```
+┌────────┬────┐
+│        │ 1  │
+│ Master ├────┤
+│        │ 2  │
+└────────┴────┘
+```
+**Best for:** General multitasking, coding with docs
+**Switch to:** `Super + T` or cycle with `Super + N`
+
+#### 2. Scroller (Horizontal)
+```
+┌───┬────┬───┬───┐
+│ 1 │  2 │ 3 │ 4 │...
+└───┴────┴───┴───┘
+```
+**Best for:** Terminals, wide content, many windows
+**Switch to:** `Super + S` or cycle with `Super + N`
+
+**Scroller-specific controls:**
+- `Alt + E` - Set current window to full width
+- `Alt + X` - Cycle through width presets (0.5, 0.8, 1.0)
+
+#### 3. Monocle (Fullscreen Stack)
+```
+┌──────────────┐
+│              │
+│   Window 1   │
+│   (fullscrn) │
+└──────────────┘
+```
+**Best for:** Focus work, browsing, media
+**Switch to:** `Super + M` or cycle with `Super + N`
+**Navigate:** Use `Super + Tab` to cycle through windows
+
+#### 4. Grid
+```
+┌─────┬─────┐
+│  1  │  2  │
+├─────┼─────┤
+│  3  │  4  │
+└─────┴─────┘
+```
+**Best for:** Viewing many windows simultaneously
+**Switch to:** Cycle with `Super + N`
+
+#### 5. Deck (Card Stack)
+```
+┌──────────────┐
+│  Window 1    │  ← Visible
+│ (2, 3 hidden)│
+└──────────────┘
+```
+**Best for:** Cycling through options
+**Switch to:** Cycle with `Super + N`
+
+#### 6. Center Tile
+```
+┌──┬──────┬──┐
+│1 │      │2 │
+│  │Master│  │
+│3 │      │4 │
+└──┴──────┴──┘
+```
+**Best for:** Symmetrical workflow, coding
+**Switch to:** Cycle with `Super + N`
+
+#### 7. Vertical Tile
+```
+┌──────────────┐
+│    Master    │
+├──┬───┬───┬───┤
+│1 │ 2 │ 3 │ 4 │
+└──┴───┴───┴───┘
+```
+**Best for:** Ultra-wide monitors
+**Switch to:** Cycle with `Super + N`
+
+### Layout Controls
+
+**Cycle through all layouts:**
+```
+Super + N    → Next layout
+```
+
+**Adjust layout parameters:**
+
+For **tile/center_tile** layouts:
+```
+Super + H    → Decrease master size  (add to config)
+Super + L    → Increase master size  (add to config)
+Super + I    → More windows in master (add to config)
+Super + D    → Fewer windows in master (add to config)
+```
+
+Add to config.conf:
+```conf
+bind=Super,h,setmfact,-0.05
+bind=Super,l,setmfact,+0.05
+bind=Super,i,incnmaster,+1
+bind=Super,d,incnmaster,-1
+```
+
+For **scroller** layout:
+```
+Alt + E      → Set window to full width
+Alt + X      → Cycle width presets
+```
+
+---
+
+## Window Management Patterns
+
+### Focus Management
+
+**Directional focus:**
+```
+Alt + ←→↑↓   → Focus window in direction
+```
+
+**Stack focus:**
+```
+Super + Tab          → Next window in stack
+Super + Shift + Tab  → Previous window in stack
+```
+
+**Focus last window:**
+```
+Super + `    → Focus previously focused window (add to config)
+```
+
+### Moving Windows
+
+**Swap with neighbors:**
+```
+Super + Shift + ←→↑↓   → Swap positions
+```
+
+**Move to master:**
+```
+Super + Return   → Move focused window to master position (add to config)
+```
+
+Add to config:
+```conf
+bind=Super,Return,zoom,
+```
+
+**Move between tags:**
+```
+Alt + 1-9              → Move to tag (and follow)
+Ctrl + Super + ←→      → Move to prev/next tag
+```
+
+### Floating Windows
+
+**Toggle floating:**
+```
+Alt + \    → Toggle floating/tiling
+```
+
+**Move floating windows:**
+```
+Ctrl + Shift + ←→↑↓   → Move by pixels
+Super + Left-drag      → Move with mouse
+```
+
+**Resize floating windows:**
+```
+Ctrl + Alt + ←→↑↓     → Resize by pixels
+Super + Right-drag     → Resize with mouse
+```
+
+**Center floating window:**
+```
+Super + C    → Center window (add to config)
+```
+
+Add to config:
+```conf
+bind=Super,c,centerwin,
+```
+
+### Window States
+
+**Common states:**
+```
+Alt + \              → Floating
+Alt + F              → Fullscreen
+Alt + Shift + F      → Fake fullscreen
+Alt + A              → Maximized
+Super + G            → Global (visible all tags)
+Super + O            → Overlay (always on top)
+```
+
+**Minimize/Restore:**
+```
+Super + I            → Minimize window
+Super + Shift + I    → Restore minimized
+```
+
+---
+
+## Using the Scratchpad
+
+### What is the Scratchpad?
+
+The scratchpad is a hidden workspace for temporary windows. It's perfect for:
+- Calculator
+- Music player
+- Notes/Todo list
+- System monitor
+- Password manager
+
+### Basic Scratchpad Usage
+
+1. **Open an application** (e.g., terminal with calculator)
+   ```bash
+   Alt + Return
+   # Then run: qalc (or any calculator)
+   ```
+
+2. **Move to scratchpad**
+   ```
+   Alt + Z
+   ```
+
+3. **Window disappears** - it's now in the scratchpad
+
+4. **Toggle scratchpad** to show/hide
+   ```
+   Alt + Z    → Shows scratchpad over current work
+   Alt + Z    → Hides it again
+   ```
+
+### Named Scratchpads
+
+You can have multiple named scratchpads:
+
+**Setup in config.conf:**
+```conf
+bind=Super,p,toggle_named_scratchpad,music
+bind=Super,n,toggle_named_scratchpad,notes
+bind=Super,c,toggle_named_scratchpad,calc
+```
+
+**Usage:**
+1. Open application (e.g., spotify)
+2. Press `Super + P` - assigns it to "music" scratchpad
+3. Press `Super + P` again - shows/hides music scratchpad
+4. Other scratchpads are independent
+
+### Scratchpad Tips
+
+**Automatic scratchpad applications:**
+
+Create a script to launch apps directly into scratchpad:
+
+```bash
+#!/bin/bash
+# ~/.config/mango/scripts/scratchpad-calc.sh
+
+# Open calculator in scratchpad
+foot -e qalc &
+sleep 0.5
+mmsg -d toggle_scratchpad
+```
+
+Bind it:
+```conf
+bind=Super,equal,spawn_shell,~/.config/mango/scripts/scratchpad-calc.sh
+```
+
+**Customize scratchpad appearance:**
+
+In config.conf:
+```conf
+scratchpad_width_ratio=0.8    # 80% of screen width
+scratchpad_height_ratio=0.9   # 90% of screen height
+scratchpadcolor=0x516c93ff    # Border color for scratchpad windows
+```
+
+---
+
+## Overview Mode
+
+### What is Overview?
+
+Overview mode shows all windows at once, similar to GNOME's Activities or macOS Mission Control.
+
+### Using Overview
+
+**Toggle overview:**
+```
+Alt + Tab    → Toggle overview mode
+```
+
+**In overview mode:**
+- Click any window to focus it
+- Drag windows to rearrange
+- Windows are organized visually
+- All tags are shown
+
+**Hotarea trigger:**
+Move your mouse cursor to the top edge of the screen to automatically trigger overview.
+
+**Configure hotarea:**
+```conf
+# In config.conf
+hotarea_size=10        # Pixels from edge to trigger
+enable_hotarea=1       # 1=enabled, 0=disabled
+```
+
+### Overview Settings
+
+```conf
+# In config.conf
+ov_tab_mode=0          # Show windows as tabs (0=off, 1=on)
+overviewgappi=5        # Gap between windows in overview
+overviewgappo=30       # Gap from screen edges
+```
+
+---
+
+## Multi-Monitor Workflows
+
+### Basic Multi-Monitor Commands
+
+**Focus different monitor:**
+```
+Alt + Shift + ←→    → Focus adjacent monitor
+```
+
+**Move window to other monitor:**
+```
+Super + Alt + ←→    → Move window to adjacent monitor
+```
+
+### Multi-Monitor Strategies
+
+**Strategy 1: Dedicated monitors per task**
+- Monitor 1: Development (Tag 1-3)
+- Monitor 2: Communication (Tag 4-6)
+- Monitor 3: Media/Reference (Tag 7-9)
+
+**Strategy 2: Mirror similar tags**
+- Both monitors show same tags
+- Each monitor has different layouts
+- Use global windows to span both
+
+**Strategy 3: Independent workspaces**
+- Each monitor is independent
+- Use monitor focus shortcuts frequently
+- Keep related work on same monitor
+
+### Monitor Configuration
+
+MangoWC auto-detects monitors. For custom setup:
+
+**Disable a monitor:**
+```bash
+mmsg -d disable_monitor HDMI-A-1
+```
+
+**Enable a monitor:**
+```bash
+mmsg -d enable_monitor HDMI-A-1
+```
+
+**Find monitor names:**
+```bash
+mmsg -o
+```
+
+---
+
+## Customization Tips
+
+### Modify Keybindings
+
+Edit `~/.config/mango/config.conf`:
+
+```conf
+# Change default terminal
+bind=Alt,Return,spawn,alacritty        # Instead of foot
+
+# Add custom application shortcuts
+bind=Super,f,spawn,firefox
+bind=Super,c,spawn,chromium
+bind=Super,e,spawn,thunar
+
+# Add focus last window
+bind=Super,grave,focuslast,
+
+# Add center window
+bind=Super,c,centerwin,
+```
+
+After editing, press `Super + R` to reload.
+
+### Customize Animations
+
+```conf
+# In config.conf
+
+# Speed up animations
+animation_duration_open=200     # Faster (default: 400)
+animation_duration_close=400    # Faster (default: 800)
+
+# Disable animations
+animations=0
+
+# Change animation type
+animation_type_open=zoom        # Or "slide"
+animation_type_close=zoom
+```
+
+### Customize Appearance
+
+```conf
+# In config.conf
+
+# Colors (RGBA hex: 0xRRGGBBAA)
+focuscolor=0x89b4faff          # Blue focused border
+bordercolor=0x313244ff         # Dark unfocused border
+
+# Borders and gaps
+borderpx=3                     # Border width
+gappih=10                      # Inner horizontal gap
+gappiv=10                      # Inner vertical gap
+gappoh=15                      # Outer horizontal gap
+gappov=15                      # Outer vertical gap
+
+# Rounded corners
+border_radius=10               # Corner radius
+
+# Window effects
+blur=1                         # Enable blur
+shadows=1                      # Enable shadows
+focused_opacity=1.0            # Focused window opacity
+unfocused_opacity=0.95         # Unfocused window opacity
+```
+
+### Custom Scripts
+
+Create `~/.config/mango/scripts/` directory:
+
+**Example: Screenshot script**
+```bash
+#!/bin/bash
+# ~/.config/mango/scripts/screenshot.sh
+
+grim -g "$(slurp)" - | satty --filename - --fullscreen
+```
+
+**Bind it:**
+```conf
+bind=Print,none,spawn_shell,~/.config/mango/scripts/screenshot.sh
+```
+
+**Example: Volume control**
+```bash
+#!/bin/bash
+# ~/.config/mango/scripts/volume.sh
+
+case $1 in
+    up) pamixer -i 5 ;;
+    down) pamixer -d 5 ;;
+    mute) pamixer -t ;;
+esac
+```
+
+**Bind it:**
+```conf
+bind=NONE,XF86AudioRaiseVolume,spawn_shell,~/.config/mango/scripts/volume.sh up
+bind=NONE,XF86AudioLowerVolume,spawn_shell,~/.config/mango/scripts/volume.sh down
+bind=NONE,XF86AudioMute,spawn_shell,~/.config/mango/scripts/volume.sh mute
+```
+
+---
+
+## Common Workflows
+
+### Workflow 1: Web Development
+
+**Setup:**
+```
+Tag 1: Browser (monocle)        → Testing
+Tag 2: Code editor (center_tile) → Development
+Tag 3: Terminals (scroller)      → Commands
+Scratchpad: Documentation, notes
+```
+
+**Workflow:**
+1. Start on Tag 2, write code
+2. `Ctrl + 1` → View in browser
+3. `Ctrl + 3` → Run build/dev server
+4. `Alt + Z` → Toggle docs when needed
+5. Use `Super + Left/Right` to cycle between tags
+
+### Workflow 2: Writing and Research
+
+**Setup:**
+```
+Tag 1: Writing app (monocle)
+Tag 2: Research browser (tile)
+Tag 3: Reference PDFs (grid)
+Scratchpad: Notes, citations
+```
+
+**Workflow:**
+1. Research on Tags 2-3
+2. `Ctrl + 1` → Switch to writing
+3. `Super + G` on notes window → Make it global
+4. Notes now visible on all tags
+
+### Workflow 3: Communication and Work
+
+**Setup:**
+```
+Tag 1: Email (monocle)
+Tag 2: Slack/Discord (tile)
+Tag 3: Work documents (tile)
+Tag 4: Calendar (monocle)
+Global: Music player
+```
+
+**Workflow:**
+1. Open music player → `Super + G` (make global)
+2. Start each app on its tag
+3. Use `Ctrl + Left/Right` to jump between active tags
+4. `Alt + Tab` for quick overview
+
+### Workflow 4: System Administration
+
+**Setup:**
+```
+Tag 1: Terminals (scroller)     → Multiple SSH sessions
+Tag 2: Monitoring (grid)         → htop, iotop, etc.
+Tag 3: Browser (monocle)         → Documentation
+Scratchpad: Calculator, quick commands
+```
+
+**Workflow:**
+1. Open terminals in scroller layout
+2. `Alt + X` to adjust column widths
+3. `Ctrl + 2` for monitoring overview
+4. `Alt + Z` for quick calculations
+
+### Workflow 5: Video/Audio Editing
+
+**Setup:**
+```
+Tag 1: Editor (monocle)          → Full-screen editing
+Tag 2: File browser (tile)       → Asset management
+Tag 3: Preview (monocle)         → Testing output
+```
+
+**Workflow:**
+1. Edit on Tag 1 in monocle (maximum space)
+2. `Ctrl + 2` → Grab assets
+3. `Ctrl + 3` → Preview output
+4. Use `Alt + F` for true fullscreen when needed
+
+---
+
+## Quick Reference Card
+
+### Essential Shortcuts
+```
+Alt + Return         Terminal
+Alt + Space          Launcher
+Alt + Q              Close window
+Super + R            Reload config
+Super + M            Exit
+
+Alt + ←→↑↓           Focus direction
+Super + Shift + ←→↑↓ Swap windows
+Alt + \              Toggle floating
+Alt + F              Fullscreen
+Super + N            Change layout
+
+Ctrl + 1-9           View tag
+Alt + 1-9            Move to tag
+Super + ←→           Prev/next tag
+
+Alt + Tab            Overview
+Alt + Z              Scratchpad
+Super + G            Global window
+```
+
+### When Things Go Wrong
+```
+Super + R            Reload config (fixes most issues)
+Super + M            Exit MangoWC
+Ctrl + Alt + F2      Switch to TTY (if GUI breaks)
+```
+
+---
+
+## Next Steps
+
+Now that you understand the basics:
+
+1. **Customize your config** - Edit `~/.config/mango/config.conf`
+2. **Set up autostart** - Create `~/.config/mango/autostart.sh`
+3. **Explore layouts** - Find what works for your workflow
+4. **Learn IPC** - Automate with `mmsg` (see COMMANDS.md)
+5. **Join the community** - [Discord](https://discord.gg/CPjbDxesh5)
+
+**Additional Resources:**
+- [COMMANDS.md](COMMANDS.md) - Complete command reference
+- [config.conf](config.conf) - Commented configuration file
+- [MangoWC Wiki](https://github.com/DreamMaoMao/mango/wiki/) - Comprehensive documentation
+- [Website](https://mangowc.vercel.app/docs) - Online documentation
+
+---
+
+**Happy tiling! 🥭**