RubyGems - rtfm-filemanager - Versions diffs - 7.3.6 → 7.4.1 - Mend

rtfm-filemanager 7.3.6 → 7.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (14) hide show

data/README.md CHANGED Viewed

@@ -1,678 +1,754 @@
 # RTFM - Ruby Terminal File Manager
-![Ruby](https://img.shields.io/badge/language-Ruby-red) [![Gem Version](https://badge.fury.io/rb/rtfm-filemanager.svg)](https://badge.fury.io/rb/rtfm-filemanager) ![Unlicense](https://img.shields.io/badge/license-Unlicense-green) ![Stay Amazing](https://img.shields.io/badge/Stay-Amazing-important)
+![Ruby](https://img.shields.io/badge/language-Ruby-red) [![Gem Version](https://badge.fury.io/rb/rtfm-filemanager.svg)](https://badge.fury.io/rb/rtfm-filemanager) ![Unlicense](https://img.shields.io/badge/license-Unlicense-green) [![Documentation](https://img.shields.io/badge/docs-comprehensive-blue)](docs/) ![Stay Amazing](https://img.shields.io/badge/Stay-Amazing-important)
-## Version 7.2
+<img src="img/logo.png" align="left" width="150" height="150">
-**BREAKING CHANGE** - Batch Operation Behavior:
+A feature-rich terminal file manager written in pure Ruby. Browse directories with syntax-highlighted previews, inline images, remote SSH/SFTP access, comprehensive undo system, OpenAI integration, and much more.
-Version 7.2 introduces a **breaking change** to how batch operations work with tagged items:
+RTFM parses your LS_COLORS for consistent terminal theming and runs on any modern terminal emulator.
-- **Previous behavior**: Operations affected tagged items + selected item (always)
-- **New behavior**: Operations affect tagged items OR selected item (not both)
-  - When items ARE tagged → operate ONLY on tagged items
-  - When NO items are tagged → operate on selected item only
+<br clear="left"/>
-This provides consistent, predictable behavior across all operations including: delete, copy, move, symlink, bulk rename, change permissions, change ownership, and open.
+## Quick Start
-**Migration**: If you want the selected item included in a batch operation, explicitly tag it first with 't'.
+```bash
+# Install
+gem install rtfm-filemanager
-## Version 7.1
+# Run
+rtfm
-Version 7.1 adds comprehensive compressed archive viewing capabilities:
+# Or start in specific directory
+rtfm ~/Documents
-- **Archive preview** for .zip, .tar, .gz, .tgz, .bz2, .tbz, .tbz2, .xz, .txz, .rar, .7z files
-- **Smart fallback** for compressed archives vs standalone compressed files
-- **Seamless integration** with existing preview system
+# Press ? for help
+```
-Version 6.0 introduced comprehensive remote directory browsing capabilities and enhanced user experience improvements including remote SSH/SFTP browsing, SSH shell integration, enhanced help system, and comprehensive undo system.
+After first run, use `r` command to launch RTFM and exit into your current directory.
+---
+## Table of Contents
+- [Key Features](#key-features)
+- [Installation](#installation)
+- [Keyboard Reference](#keyboard-reference)
+- [Remote SSH/SFTP Browsing](#remote-sshsftp-browsing)
+- [Configuration](#configuration)
+- [OpenAI Integration](#openai-integration)
+- [Plugins](#plugins)
+- [Image Display](#image-display)
+- [RTFM vs Ranger](#rtfm-vs-ranger)
+- [Documentation](#documentation)
+---
+## Key Features
+### File Operations
+- **Comprehensive undo system** - Undo delete, move, rename, copy, symlink, permissions, ownership
+- **Trash bin** - Optional safe deletion with restore capability
+- **Bulk operations** - Copy, move, delete multiple tagged items
+- **Bulk rename** - Pattern-based renaming (regex, templates, case conversion)
+- **Permission management** - Change permissions with undo support (`755`, `rwxr-xr-x`, `+x`, `-w`)
+- **Ownership management** - Change user:group with undo support
+### Display & Preview
+- **Syntax highlighting** - File content with bat/batcat
+- **Inline images** - w3m and Sixel protocols via termpix gem
+- **EXIF orientation** - Correct display of rotated images
+- **Video thumbnails** - ffmpegthumbnailer integration
+- **Archive preview** - View contents of .zip, .tar, .gz, .rar, .7z files
+- **Document preview** - PDF, LibreOffice, MS Office files
+- **LS_COLORS parsing** - Consistent terminal color theming
+### Remote Operations
+- **SSH/SFTP browsing** - Navigate remote directories seamlessly
+- **Interactive SSH shell** - Drop into shell sessions on remote hosts
+- **File transfer** - Download and upload files
+- **Connection caching** - Smart caching for performance
+### Advanced Features
+- **Git integration** - Status display for repositories
+- **Cryptographic hashing** - Directory tree verification
+- **OpenAI integration** - File descriptions and interactive chat
+- **Tab management** - Multiple tabs with duplication and renaming
+- **Fuzzy search** - fzf integration
+- **Navi integration** - Interactive command cheatsheets
+### Developer Features
+- **Plugin architecture** - Custom preview handlers and key bindings
+- **Ruby debug mode** - Execute arbitrary Ruby in context
+- **Command history** - Preserved across sessions
+- **Extensible** - Clean plugin API
+---
-Version 5 was a complete rewrite using [rcurses](https://github.com/isene/rcurses) as the underlying library, providing stability, higher quality code and extensive features including optional trash bin, advanced OpenAI integrations, plugin architectures for keybindings, user defined features and file viewers.
+## Installation
-The major feature additions are marked in ***bold italic***.
+### via RubyGems (Recommended)
-## What?
-<img src="img/logo.png" align="left" width="150" height="150"> RTFM is a
-terminal file manager jam packed with features.
+```bash
+gem install rtfm-filemanager
+```
-Apart from viewing and manipulating directories, you get syntax highlighting
-of file content, image and video thumbnailing in the terminal, OpenAI
-integration, system info panel, git status, fzf and navi integration and much,
-much more.
+### Full Installation with All Features
-Note: RTFM (Ruby Terminal File Manager) works best with the (u)rxvt, xterm and
-Eterm terminal emulators.
+#### Ubuntu/Debian:
+```bash
+sudo apt update
+sudo apt install ruby-full x11-utils xdotool bat pandoc poppler-utils \
+  odt2txt docx2txt unzip gnumeric catdoc w3m imagemagick \
+  ffmpegthumbnailer tar gzip bzip2 xz-utils unrar p7zip-full
-### Features
-RTFM is one of the most feature rich terminal file managers. Some of the
-features are:
-* RTFM parses your LS_COLORS to ensure color consistency with the terminal experience
-* Images are shown inline in the terminal (can be turned off)
-* File contents is shown with proper syntax highlighting
-* Item's meta data is shown at the top
-* Easily browse file content (pdf, MS/OpenOffice, etc.)
-* Move around the file systems using arrow keys or VI keys
-* Copy, move, rename, symlink and delete files easily
-* Simply use 'r' in your terminal to launch RTFM - and exit into the directory where you ended RTFM
-* ***Toggle the use of a "trash bin" to move dirs/files there instead of deleting***
-* Easily copy an item's path to clipboard or primary selection
-* Order items the way you want, see only files of a certain type
-* Filter out all files not matching a [regex](https://www.rubyguides.com/2015/06/ruby-regex/) pattern
-* Mark files and directories and do group actions on them
-* Bookmark directories for easy jumping
-* Follow a symlink to where it points with one key stroke
-* Highlight files and directories matching a given pattern
-* Find items using `locate` and jump directly to the desired item
-* Find items and jump there using fuzzy search (with [fzf](https://github.com/junegunn/fzf))
-* Execute any shell command from inside RTFM - ***incuding other curses applications***
-* [navi](https://github.com/denisidoro/navi) integration for easier command executions
-* Easily unpack or create archives
-* Show git status for the current directory
-* Show comprehensive system info (processes running, disk space, dmesg, etc.)
-* See if a directory (with sub dirs) has changed using cryptographic hashes
-* ***Remote directory browsing via SSH/SFTP*** with seamless navigation and file operations
-* ***SSH shell integration*** for dropping into interactive shell sessions on remote hosts
-* ***Remote file operations*** including download, upload, and file info display
-* Integration with OpenAI to get an executive summary of file content
-* ***OpenAI chat integrated; Discuss files, content, commands with OpenAI***
-* ***Enhanced tab management*** with duplication, renaming, and smart navigation
-* ***Improved stability*** with simplified architecture and eliminated flickering
-* ***Automatic image redraw*** after workspace switching (i3-wm compatible)
-* Possibility to change top line background when matching a path
-* Theming of pane colors
-## Why?
-The idea came to mind as I was working on [a complete LS_COLORS
-setup](https://github.com/isene/LS_COLORS) with a corresponding
-[ranger](https://ranger.github.io/) theme. But making a separate theme for
-ranger to mimic a massive LS_COLOR setup is rather stupid. File managers
-should parse LS_COLORS as default rather than implement their own themes. This
-became an itch that I kept scratching until I could happily replace ranger two
-weeks later. But, coding RTFM based on the old curses library was clumsy,
-inefficient and painful. So I decided to create
-[rcurses](https://github.com/isene/rcurses) - a complete curses library
-written from scratch in pure Ruby - and from v5 and onwards, RTFM is based
-completely on this modern curses implementation.
-## How?
-RTFM is a modern two-pane file manager with **enhanced tab support** for multi-directory navigation. You navigate in the left pane and the content of the selected item (directory or file) is shown in the right pane. The right pane is also used to show information such as the currently tagged items, your (book)marks, output from commands, error messages, etc.
-The **tab system** is visible in the top-right corner showing your current position like `[2/5]` (tab 2 of 5 total tabs). The tab bar displays when you have multiple tabs or use tab commands, showing directory names and management shortcuts.
-**Enhanced Tab Features:**
-* **Multiple tabs** for easy multi-directory management
-* **Tab duplication** (`}`) to quickly copy current directory context
-* **Tab renaming** (`{`) for better organization
-* **Smart tab display** showing current directory and shortcuts
-* **Quick tab switching** with number keys (1-9), J/K navigation
-* **Visual tab indicator** in top-right corner `[current/total]`
-When you start RTFM, you can supply a directory path as an argument to let
-RTFM start up in that directory. When you exit it exits into the current RTFM
-directory.
-You can run any command in the bottom "command bar" and have the output
-presented in the right pane. History of commands are preserved like in your
-shell.
-## Remote Directory Browsing
-RTFM includes comprehensive **remote directory browsing** capabilities via SSH/SFTP, allowing you to seamlessly navigate and manage files on remote servers directly from your local terminal.
-**Key Remote Features:**
-* **Seamless remote navigation** - Browse remote directories as if they were local
-* **SSH shell integration** - Drop into interactive shell sessions with `s` key
-* **File operations** - Download (`d`), upload (`u`), and view file info (`→`)
-* **Connection caching** - Intelligent caching for improved performance
-* **Multiple connection formats** supported
-**Connection Examples:**
+gem install rtfm-filemanager
+```
+#### macOS:
 ```bash
-# Basic SSH connection
-user@server.com:/path/to/directory
+brew install ruby imagemagick w3m bat pandoc poppler
-# With custom SSH key
--i ~/.ssh/custom-key user@server.com:/path
+gem install rtfm-filemanager
+```
-# SSH URI format
-ssh://user@server.com/path/to/directory
+### Dependencies
-# Key at end format
-user@server.com:/path -i ~/.ssh/custom-key
+**Required:**
+- Ruby 2.7+
+- rcurses gem (~> 6.0)
+- termpix gem (~> 0.2)
-# With comments for organization
-user@server.com:/path # Production server
-admin@192.168.1.10 # Local development
-```
+**Optional (for full functionality):**
+- **ImageMagick** - Image preview (`identify`, `convert`)
+- **w3m-img** - w3m image protocol
+- **xdotool** - Image redraw on workspace switching
+- **bat/batcat** - Syntax highlighting
+- **fzf** - Fuzzy file finding
+- **pandoc** - Document conversion
+- **ffmpegthumbnailer** - Video thumbnails
+- **ruby-openai** - AI integration
-**Remote Mode Usage:**
-1. Press `Ctrl+E` to enter/exit remote mode
-2. Enter connection string when prompted
-3. Navigate with standard keys (`←`, `→`, `↑`, `↓`)
-4. Use `d` to download files, `u` to upload files
-5. Press `s` to open SSH shell in current remote directory
-6. Press `Ctrl+E` to return to local mode
+---
-The remote browsing feature includes visual indicators (red background) to clearly show when you're in remote mode, and all standard RTFM navigation and information features work seamlessly with remote directories.
+## Keyboard Reference
-## Installation
-You can install RTFM by cloning this repo and put the file `rtfm` in your
-"bin" directory. If you do, you need to install
-[rcurses](https://github.com/isene/rcurses) first.
-Or you can simply run `gem install rtfm-filemanager`.
-There are two basic prerequisites needed: `x11-utils` and `xdotool`. On
-Ubuntu these would be installed via `apt install x11-utils xdotool`.
-Content of text files are handled by `cat` - or by `bat` if you want beautiful
-highlighting. Other files are shown via external programs (Debian/Ubuntu
-family of Linux distros command in last column):
-File type                   | Requirements                     | Installation
-----------------------------|----------------------------------|-------------------------------
-Syntax highlighting of text | `bat`                            | `apt install bat`
-Markdown                    | `pandoc`                         | `apt install pandoc`
-PDFs                        | `pdftotext`                      | `apt install poppler-utils`
-LibreOffice                 | `odt2txt`                        | `apt install odt2txt`
-MS docx                     | `docx2txt`                       | `apt install docx2txt`
-MS pptx                     | `unzip`                          | `apt install unzip`
-MS xlsx                     | `ssconvert`                      | `apt install gnumeric`
-MS doc/xls/ppt              | `catdoc`, `xls2csv` and `catppt` | `apt install catdoc`
-Images                      | `w3m` and `ImageMagick`          | `apt install w3m imagemagick`
-Video (thumbnails)          | `ffmpegthumbnailer`              | `apt install ffmpegthumbnailer`
-Compressed archives         | `unzip`, `tar`, `gzip`, `bzip2`, `xz` | `apt install unzip tar gzip bzip2 xz-utils`
-RAR archives                | `unrar`                          | `apt install unrar`
-7-Zip archives              | `7z`                             | `apt install p7zip-full`
-Install rtfm from scratch with all of the above on Ubuntu:
-```
-sudo apt update
-sudo apt install ruby-full git libncurses-dev x11-utils xdotool bat pandoc poppler-utils odt2txt docx2txt unzip gnumeric catdoc w3m imagemagick ffmpegthumbnailer tar gzip bzip2 xz-utils unrar p7zip-full
-sudo gem install rcurses
-git clone https://github.com/isene/RTFM
-cd RTFM
-sudo cp rtfm /usr/bin/
-```
-Or with a simpler gem install:
-```
-sudo apt update
-sudo apt install ruby-full git libncurses-dev x11-utils xdotool bat pandoc poppler-utils odt2txt docx2txt unzip gnumeric catdoc w3m imagemagick ffmpegthumbnailer tar gzip bzip2 xz-utils unrar p7zip-full
-gem install rtfm-filemanager
-```
+For complete reference: `man rtfm` or press `?` in RTFM
+### Essential Keys
+| Key | Action |
+|-----|--------|
+| `?` | Show help |
+| `q` | Quit (save config) |
+| `Q` | Quit (don't save) |
+| `r` | Refresh display |
+### Navigation
+| Key | Action |
+|-----|--------|
+| `j` / `↓` | Move down |
+| `k` / `↑` | Move up |
+| `h` / `←` | Parent directory |
+| `l` / `→` / `ENTER` | Enter directory / open file |
+| `HOME` / `END` | First / last item |
+| `PgUp` / `PgDn` | Page up / down |
-## Screenshot
-![RTFM screenshot](img/screenshot-logo.png)
-## Image preview in the terminal
-RTFM uses w3mimgdisplay (part of the w3m package) to show images in the
-terminal. Some terminals have an issue with this - either the images don't
-show, the previous image is not cleared (new image overlaps the previous) or
-they show for only a flash or a few seconds. The table below shows how the
-most popular terminals fare with this. An "O" indicates that the terminal is
-OK, while an "X" indicates that it fails:
-Terminal      |Images | No overlap | Images stay
---------------|-------|------------|-----------
-(u)rxvt       |   O   |    O       |   O
-xterm         |   O   |    O       |   O
-Eterm         |   O   |    O       |   O
-kitty         |   O   |    O       |   O
-alacritty     |   O   |    O       |   X
-terminology   |   O   |    O       |   X
-stterm        |   O   |    O       |   X
-gnome-terminal|   O   |    X       |
-xfce4-terminal|   O   |    X       |
-mate-terminal |   O   |    X       |
-lilyterm      |   O   |    X       |
-termit        |   X   |            |
-lxterminal    |   X   |            |
-qterminal     |   X   |            |
-## Keys
-These are the set of keys to move around and do actions within RTFM:
-### Basic keys
-Key      | Description
----------|------------------------------------------------------------------
- ?       | Show this help text
- v       | Display RTFM version (and latest Gem version) in bottom window/command bar
- r       | Refresh RTFM (recreates all windows. Use on terminal resize or when there is garbage somewhere)
- R       | Reload configuration (~/.rtfm/conf)
- W       | Write parameters to ~/.rtfm/conf: @marks, @hash, @history, @rubyhistory, @aihistory, @lslong, @lsall, @lsorder, @lsinvert, @width, @border, @preview, @trash
- C       | ***Show the current configuration in ~/.rtfm/conf***
- q       | Quit (save basic configuration: @marks, @hash, @history, @rubyhistory, @aihistory)
- Q       | QUIT (without writing any changes to the config file)
-### Layout
-Key      | Description
----------|------------------------------------------------------------------
- w       | Change the width of the left/right panes (left pane ⇒ 20%, 30%, 40%, 50%, 60%)
- B       | Cycle border
- \-       | (Minus sign) Toggle preview in right pane (turn it off for faster traversing of directories)
- _       | (Underscore) Toggle preview of images in right pane
- b       | Toggle syntax highlighting (and line numbering)
-### Motion
-Key      | Description
----------|------------------------------------------------------------------
- j/DOWN  | Go one item down in left pane (rounds to top)
- k/UP    | Go one item up in left pane (rounds to bottom)
- h/LEFT  | Go up one directory level
- l/RIGHT | Enter directory or open file (using run-mailcap or xdg-open) Use the key 'x' to force open using xdg-open (or run-mailcap) - used for opening html files in a browser rather than editing the file in your text editor
- PgDown  | Go one page down in left pane
- PgUp    | Go one page up in left pane
- END     | Go to last item in left pane
- HOME    | Go to first item in left pane
-### Marks and jumping
-Key      | Description
----------|------------------------------------------------------------------
- m       | Mark current dir (persistent). Next letter is the name of the mark [a-zA-Z'] The special mark "'" jumps to the last directory (makes toggling dirs easy) Press '-' and a letter to delete that mark. Mark '0' is the dir where RTFM was started.  Marks '1' - '5' are the past five directories visited
- M       | Show marked items in right pane
- '       | Jump to mark (next letter is the name of the mark [a-zA-Z']) The 5 latest directories visited are stored in marks 1-5 (1 being the very latest)
- ~       | Jump to Home directory
- \>       | Follow symlink to the directory where the target resides
-### Directory views
-Key      | Description
----------|------------------------------------------------------------------
- a       | Show all (also hidden) items
- A       | Show long info per item (show item attributes)
- o       | Change the order/sorting of directories (circular toggle)
- i       | Invert/reverse the sorting
- O       | Show the Ordering in the bottom window (the full ls command)
+### Marks & Jumping
+| Key | Action |
+|-----|--------|
+| `m` + letter | Set bookmark |
+| `'` + letter | Jump to bookmark |
+| `~` | Jump to home |
+| `>` | Follow symlink |
+| `Ctrl-r` | Recent files/directories |
+| `Ctrl-e` | Toggle remote SSH mode |
 ### Tagging
-Key      | Description
----------|------------------------------------------------------------------
- t       | Tag item (toggles)
- Ctrl-t  | Add items matching a pattern to list of tagged items (Ctrl-t and then . will tag all items)
- T       | Show currently tagged items in right pane
- u       | Untag all tagged items
-### Tab management
-Key      | Description
----------|------------------------------------------------------------------
- ]       | Create new tab in current directory
- [       | Close current tab (keeps at least one tab open)
- J       | Previous tab (wraps around)
- K       | Next tab (wraps around)
- }       | Duplicate current tab (creates a copy with same directory)
- {       | Rename current tab
- 1-9     | Switch to tab by number (1 = first tab, 2 = second tab, etc.)
-### Manipulate items
-Key      | Description
----------|------------------------------------------------------------------
- p       | Put (copy) tagged items here
- P       | PUT (move) tagged items here
- c       | Change/rename selected (adds command to bottom window)
- s       | Create symlink to tagged items here
- d       | Delete selected item and tagged items. Confirm with 'y'. ***Moves items to trash directory (~/.rtfm/trash/) if @trash | true***
- D       | ***Empty trash directory***
- Ctrl-d  | ***Toggle use of trash directory***
- Ctrl-o  | Change ownership to user:group of selected and tagged items
- Ctrl-p  | Change permissions of selected and tagged items
-           Format | rwxr-xr-x or 755 or rwx (applies the trio to user, group and others)
-### Filter and search
-Key      | Description
----------|------------------------------------------------------------------
- f       | Show only files in the left pane matching extension(s) (e.g. "txt" or "pdf,png,jpg")
- F       | Show only files matching a pattern (Ruby Regex) (e.g. "abc" or "ab.+12(\w3)+")
- Ctrl-f  | Clear all filtering
- /       | Enter search string in bottom window to highlight matching items and jump to the first match
- \\       | Remove search pattern
- n       | Jump to the next item matched by '/'
- N       | Jump to the previous item matched by '/'
- g       | Run 'grep' to show files that contains the MATCH in current directory
- L       | Start 'locate' search for files, then use '#' to jump to desired line/directory
- Ctrl-l  | Locate files via fzf from the current directory down (fuzzy file finder must be installed https://github.com/junegunn/fzf)
-### Archives
-Key      | Description
----------|------------------------------------------------------------------
- z       | Extract tagged zipped archive to current directory
- Z       | Create zipped archive from tagged files/directories
-### Git/hash/openai
-Key      | Description
----------|------------------------------------------------------------------
- G       | Show git status for current directory
- H       | Do a cryptographic hash of the current directory with subdirs. If a previous hash was made, compare and report if there has been any change
- I       | Show OpenAI's description of the selected item and its content (if available). You must have installed the ruby-openai gem and added your openai secret key in the ~/.rtfm/conf (add `@ai | "your-secret-openai-key") for this to work.
- Ctrl-a  | ***Start an OpenAI chat (the context window is kept until you exit RTFM). The OpenAI agent is specialized in answering questions about cli, files and dirs***
-### Right pane controls
-Key      | Description
----------|------------------------------------------------------------------
- ENTER   | Refresh the right pane
- S-RIGHT | ***One line down in the preview***
- S-LEFT  | ***One line up in the preview***
- S-DOWN  | ***Next page of the preview (if doc long and ∇ in the bottom right)*** (TAB does the same)
- S-UP    | ***Previous page (if you have moved down the document first - ∆ in the top right)*** (or S-TAB)
-### Clipboard copy
-Key      | Description
----------|------------------------------------------------------------------
- y       | Copy path of selected item to primary selection (for pasting with middle mouse button)
- Y       | Copy path of selected item to clipboard
- Ctrl-y  | Copy content of right pane to clipboard (turn off batcat syntax highlighting with 'b' for a clean copy of content)
-### System shortcuts
-Key      | Description
----------|------------------------------------------------------------------
- S       | Show comprehensive System info (system, CPU, filesystem, latest dmesg messages)
- =       | Create a new directory (a shortcut for ":mkdir ")
- Ctrl-n  | Invoke navi (see https://github.com/denisidoro/navi) with any output in right window
-### Command mode
-Key      | Description
----------|------------------------------------------------------------------
- :       | Enter "command mode" in bottom window (press ENTER to execute, press ESC to escape). Prefix the command with a '§' to force the program to run in interactive mode (full screen TUI programs like htop, vim or any shell)
- ;       | Show command history in right pane
- \+       | ***Add program(s) to the list of full-UI interactive terminal programs***
-### Ruby debug mode
-Key      | Description
----------|------------------------------------------------------------------
- @       | Enter Ruby mode to execute any Ruby command (ENTER to execute, ESC to escape)
-## Keyboard cheat sheet
-![RTFM keyboard cheat sheet](img/rtfm-kb.png)
-## First run
-The first time you run RTFM, you are greeted with a welcome message. RTFM will
-add a simple function to your shell (bash, zsh, fish, maybe others) that will
-let you launch RTFM via the one key command `r`. It also lets RTFM exit in the
-directory you are currently in (inside of RTFM) rather than where you launched
-RTFM.
-With this, you can jump around in your directory structure via RTFM, exit to
-the desired directory, do work in the terminal and go back into RTFM via `r`.
-If you want to launch rtfm straight into a specified directory, do this
-instead: `rtfm ~/mydir/subdir`
-## Configuration file
-When you first exit RTFM, it will write your (book)marks and the set of tagged
-files to `.rtfm/conf`. This ensures your marks and tagged files are
-persistent. It also means you can launch rtfm tag a bunch of dirs and files,
-drop out back to the terminal to do some work, back into rtfm and resume to
-work with your previously tagged items.
-You can also set persistent variables in the config file manually:
-To have long info per item: `@lslong = true` (this is otherwise set to `false`)
-To show hidden files: `@lsall = "-a"` (this is otherwise set to `""`)
-To set a specific order for ls: `@lsorder = "-S"` (to order by size).
-To revert your ls order: `@lsinvert = "-r"`
-To set any additional 'ls' switches, set the variable `@lsuser`. To not list
-any files containg the word "test", you could do this:
-```
-@lsuser = "--ignore=test"
-```
-To suppress image viewing in the terminal: `@showimage = false`
-To suppress showing any content in the right pane: `@preview = false`
+| Key | Action |
+|-----|--------|
+| `t` | Tag/untag item |
+| `Ctrl-t` | Tag by pattern |
+| `T` | Show tagged items |
+| `u` | Untag all |
+### File Operations
+| Key | Action |
+|-----|--------|
+| `p` | Copy tagged items here |
+| `P` | Move tagged items here |
+| `s` | Create symlinks |
+| `c` | Rename item |
+| `E` | Bulk rename (patterns) |
+| `d` | Delete (→ trash if enabled) |
+| `D` | Empty trash |
+| `Ctrl-d` | Toggle trash on/off |
+| `U` | Undo last operation |
+### Permissions
+| Key | Action |
+|-----|--------|
+| `Ctrl-p` | Change permissions (with undo) |
+| `Ctrl-o` | Change ownership (with undo) |
+**Permission formats:** `755`, `rwxr-xr-x`, `rwx`, `+x`, `-w`, `+rw`
+### Search & Filter
+| Key | Action |
+|-----|--------|
+| `f` | Filter by extension |
+| `F` | Filter by regex |
+| `/` | Search and highlight |
+| `n` / `N` | Next / previous match |
+| `g` | Grep content |
+| `L` | Locate files |
+| `Ctrl-l` | Fuzzy find (fzf) |
+### Display
+| Key | Action |
+|-----|--------|
+| `-` | Toggle preview on/off |
+| `_` | Toggle image preview |
+| `b` | Toggle syntax highlighting |
+| `w` | Change pane width |
+| `B` | Cycle borders |
+| `a` | Show/hide hidden files |
+| `A` | Toggle long info (ls -l) |
+| `o` | Change sort order |
+| `i` | Invert sort |
+### Clipboard
+| Key | Action |
+|-----|--------|
+| `y` | Copy path (primary selection) |
+| `Y` | Copy path (clipboard) |
+| `Ctrl-y` | Copy image/text to clipboard |
+### Git / AI / System
+| Key | Action |
+|-----|--------|
+| `G` | Git status |
+| `H` | Directory hash |
+| `I` | OpenAI file description |
+| `Ctrl-a` | OpenAI chat |
+| `S` | System information |
+| `X` | Compare two files |
+| `e` | File properties |
+### Tabs
+| Key | Action |
+|-----|--------|
+| `]` | New tab |
+| `[` | Close tab |
+| `J` / `K` | Previous / next tab |
+| `}` | Duplicate tab |
+| `{` | Rename tab |
+| `1-9` | Switch to tab # |
+### Command Mode
+| Key | Action |
+|-----|--------|
+| `:` | Execute shell command |
+| `;` | Command history |
+| `@` | Ruby debug mode |
+| `§` | Force interactive mode (prefix) |
+| `+` | Whitelist program as interactive |
+**Interactive mode example:** `:§htop` - runs htop in full terminal
+---
+## Remote SSH/SFTP Browsing
+Access and manage files on remote servers directly from RTFM.
+### Activating Remote Mode
+1. Press `Ctrl-e`
+2. Enter connection string:
+   ```
+   user@server.com:/path/to/directory
+   ```
+### Connection Formats
-To change the default width of the left pane: `@width = 5` (experiment with numbers 2-8).
+```bash
+# Basic SSH
+user@server.com:/path
-To toggle borders in RTFM: `@border = 1` (any number 0-3)
+# Custom SSH key
+-i ~/.ssh/custom-key user@server.com:/path
-To have some commands already prepared for the command history, you can set:
-```
-@history = ["cat /home/me/MyTodo.txt", "neofetch --stdout"]
-```
-To open files with `run-mailcap` instead of `open-xdg` set:
-```
-@runmailcap = true
-```
-***To use the trash bin: `@trash = true`***
-***To change the list of "whitelisted full-UI programs", change the variable @interactive.
-This is a comma separated string listing all programs that can be run from
-within RTFM's "command mode" (via the key `:`). Programs such as `htop`, `vim`
-and all shells will take over the terminal when they run and need explicit
-permission via this variable to be able to "replace" RTFM in the terminal.
-When you exit such a whitelisted program, RTFM resumes control. If you try to
-run such a program while it is not whitelisted, it will hang the terminal. To
-add a program to the whitelist inside RTFM, press the `+` key. All ususal
-shell comands that do not take over the full terminal such as `ls`, `touch`,
-`neofetch`, etc. will run just fine in command mode without being whitelisted.
-You can also explicitly run a program as interactive by prefixing the command
-with a single `§` - e.g. `:` `§saidar`. Programs added to @interactive will
-open as interactive also when opened via xdg-open or runmailcap (when you
-press `RIGHT` on a selected item).***
-All the variables above that you manually add to the top of the config files are
-undisturbed by launching and exiting RTFM.
-You can structure the config file the way you want. Let your OCD make it pretty.
-You can use `W` inside of RTFM to write all the parameters mentioned above to
-the config file - instead of adding them manually. Example: You press `+` to
-add `emacs` to your list of whitelisted interactive programs. Then you would
-want to press `W` to update @interactive in your config file so that `emacs`
-is permanently whitelisted as an interactive program for you.
-To exit RTFM without writing any changes to you marks or list of tagged items,
-exit with `Q`. They will then remain the same as when you launched RTFM for
-that session.
-## Extra info
-The top line shows information about the currently item in the left pane. When
-you are at a file, the information is pretty self explanatory:
-`Path: /home/geir/RTFM/README.md (-rw-r--r-- geir:geir 2023-04-25 11:49  16K)`
-This shows the full path of the selected file as well as the permissions,
-ownership, timestamp and the size of the file. When you are at a directory in
-the left pane, you get two numbers in brackets. The first number is the number
-of regular dirs/files in that directory. The second shows the total number of
-entries, including the hidden directories and files:
-`Path: /home/geir/RTFM (drwxr-xr-x geir:geir 2023-04-29 01:55  4,0) [4 8]`
-Different file types may have extra self explanatory information included in
-square brackets at the end of the top info line. Image files will have the
-size of the image included while pdf files will have the number of pages. More
-file specific information will be included when I feel like adding such.
-## Top and bottom line background colors
-You can customize the background colors for the top and bottom lines/panes.
-Bottom color is by default `238`. Change it by setting @bottomcolor to your
-desired colors in your `.rtfm/conf`.
-You can also set the background color at the bottom when you enter command
-mode (via `:`) by setting @cmdcolor and the Ruby mode (via `@`) by setting
-@rubycolor.
-Background color for OpenAI chats (invoked with `Ctrl-a`) is set with @aicolor.
-You can set the variable `@topmatch` in your `.rtfm/conf` so that it will change
-the background color of the top line/pane when you are in a directory matching
-a pattern.
-Example:
-```
-@topmatch =  [["passionfruit", 165], ["kiwi", 50], ["", 238]]
-```
-With this, the background color of the top line/pane will be set to `165` if
-you are in a directory path that includes "passionfruits". The last pair is
-the default background color when no match is found. If you don't set this
-variable in your `.rtfm/conf`, rtfm will set this value to:
-```
-@topmatch =  [["", 238]]
+# SSH URI
+ssh://user@server.com/path
+# With comment
+user@server.com:/path # Production server
 ```
-Make sure to have a default value set as the last pair in `@topmatch`.
-## Plugin architecture
-***Upon first running RTFM, a few files are created in the `.rtfm/` directory.***
+### Remote Mode Keys
+| Key | Action |
+|-----|--------|
+| `←` / `h` | Parent directory |
+| `→` / `ENTER` | Enter dir / show file info |
+| `d` | Download file |
+| `u` | Upload tagged files |
+| `s` | Open SSH shell |
+| `Ctrl-e` | Exit remote mode |
+**Visual indicator:** Red background when in remote mode
+---
+## Configuration
-One is `preview.rb`, the other is `keys.rb`.
+Configuration stored in `~/.rtfm/conf`
-You can add new "previewers" to show files with extensions that is not
-previewed by default in RTFM. The `preview.rb` explains how you add thesea:
+### Quick Config
+| Action | Command |
+|--------|---------|
+| View config | Press `C` |
+| Save config | Press `W` |
+| Reload config | Press `R` |
+### Common Settings
+```ruby
+# ~/.rtfm/conf
+# Enable trash bin
+@trash = true
+# Toggle preview on/off
+@preview = true
+# Show/hide images
+@showimage = true
+# Show hidden files
+@lsall = "-a"
+# Show long file info
+@lslong = true
+# Pane width (2-7)
+@width = 5
+# Border style (0-3)
+@border = 2
+# OpenAI API key
+@ai = "your-api-key-here"
+# Directory bookmarks (persistent)
+@marks = {"h" => "/home/user", "d" => "/home/user/Documents"}
+# Command history (persistent)
+@history = ["git status", "ls -la"]
+# Interactive programs whitelist
+@interactive = "htop,vim,emacs,nano"
+# Top line background colors by path match
+@topmatch = [["projects", 165], ["", 238]]
 ```
-# ~/.rtfm/preview.rb
-#
-# Define one handler per line in the form:
-#
-#   ext1, ext2, ext3 = command with @s placeholder
-#
-# @s will be replaced by the shell-escaped filename.
-#
-# Lines beginning with # or blank are ignored.
-#
-# Examples:
-#   # plain text, Ruby, Python, shell
-#   txt, rb, py, sh = bat -n --color=always @s
-#
-#   # Alternative syntax highlighters (e.g., on macOS without bat)
-#   # txt, rb, py, sh = highlight -O ansi --force --line-numbers @s
-#
-#   # markdown via pandoc
-#   md = pandoc @s -t plain
-#
-#   # Alternative markdown viewers (e.g., lowdown, termmark)
-#   # md = lowdown -Tterm @s
-#   # md = termmark @s
-#
-#   # PDFs
-#   pdf = pdftotext -f 1 -l 4 @s -
+### Color Customization
+```ruby
+# Bottom pane
+@bottomcolor = 238
+# Command mode
+@cmdcolor = 24
+# Ruby mode
+@rubycolor = 52
+# OpenAI chat
+@aicolor = 17
 ```
-Likewise, you can add or rewrite any keys in RTFM and add new functionality to
-RTFM by following the instructions in `keys.rb`:
+---
+## OpenAI Integration
+RTFM includes built-in AI features powered by OpenAI's API for intelligent file analysis and interactive assistance.
+### Setup
+1. **Install the ruby-openai gem:**
+   ```bash
+   gem install ruby-openai
+   ```
+2. **Get an API key:**
+   - Sign up at https://platform.openai.com/
+   - Generate an API key from your account settings
+3. **Configure RTFM:**
+   Add your API key to `~/.rtfm/conf`:
+   ```ruby
+   @ai = "sk-your-actual-api-key-here"
+   @aimodel = "gpt-4o-mini"  # Optional: default model
+   @aicolor = 17             # Optional: chat pane background color
+   ```
+### Features
+#### File Description (Press `I`)
+Get an intelligent summary of any file or directory:
+- **Files:** Purpose, code review (for source files), library documentation lookup
+- **Directories:** Overview of structure and contents
+- **Git-aware:** Includes recent changes if in a git repository
+- **Smart analysis:** Automatically includes preview content for context
+Example uses:
+- Understand unfamiliar codebases quickly
+- Get code review suggestions (bugs, style, improvements)
+- Learn what libraries/APIs are being used
+- See git diff explanations in plain language
+#### Interactive Chat (Press `Ctrl-a`)
+Start a conversational AI assistant specialized in:
+- File and directory questions
+- Shell command help and suggestions
+- Terminal workflow assistance
+- Programming and scripting guidance
+The chat maintains context throughout your RTFM session, so follow-up questions work naturally.
+### Configuration Options
+```ruby
+# Model selection (in ~/.rtfm/conf)
+@aimodel = "gpt-4o-mini"      # Fast, cost-effective (default)
+@aimodel = "gpt-4o"           # More capable, higher cost
+@aimodel = "gpt-4-turbo"      # Alternative high-end model
+# Chat interface color
+@aicolor = 17                 # Dark blue background (default)
 ```
-# ~/.rtfm/keys.rb
-#
-# Override or add key bindings simply by assigning into KEYMAP
-# and defining the corresponding handler methods.
-#
-# Syntax:
-#   KEYMAP['X'] = :my_handler
-#
-#   def my_handler(chr)
-#     # anything you like - use @pB, @pR, Dir.pwd, etc.
-#     @pB.say("You pressed X!")
-#   end
-#
+### Cost & Privacy
+- API calls cost money (typically $0.001-0.01 per request with gpt-4o-mini)
+- File contents are sent to OpenAI when using `I` key
+- No data is sent unless you explicitly press `I` or `Ctrl-a`
+- Chat history persists only during your RTFM session
+---
+## Plugins
+RTFM supports two types of plugins in `~/.rtfm/plugins/`:
+### 1. Preview Handlers (`preview.rb`)
+Add custom file type previews:
+```ruby
+# ~/.rtfm/plugins/preview.rb
+# Syntax: ext1, ext2 = command with @s placeholder
+# @s is replaced with shell-escaped filename
 # Examples:
-#
-#   # remap 'C' to show config
-#   KEYMAP['C'] = :show_config
-#
-#   # add a new binding: 'Z'
-#   KEYMAP['Z'] = :zap_all
-#   def zap_all(_chr)
-#     @pB.say("ZAPPED!")
-#   end
-```
-Here is another example of what you could add as a plugin:
+txt, log = bat -n --color=always @s
+md = pandoc @s -t plain
+pdf = pdftotext -f 1 -l 4 @s -
+json = jq . @s
 ```
-KEYMAP['C-G'] = :git_update
-def git_update
-  @pR.say("Updating...")
+### 2. Custom Key Bindings (`keys.rb`)
+Add or override key bindings:
+```ruby
+# ~/.rtfm/plugins/keys.rb
+# Add new key binding
+KEYMAP['Z'] = :my_custom_action
+def my_custom_action(_chr)
+  @pB.say("Custom action triggered!")
+  # Use @pL, @pR, @selected, etc.
+end
+# Git commit shortcut example
+KEYMAP['C-G'] = :git_commit
+def git_commit
   message = @pCmd.ask('Commit message: ', '')
   shellexec("git add . && git commit -m '#{message}' && git push")
-  @pB.full_refresh
 end
 ```
-If you're launching external terminal programs (like editors or TUI applications) from your custom keys,
-make sure to set `@external_program_running = true` before launching and `false` after it returns.
-This prevents RTFM from redrawing over your program when switching terminals:
+### Available Variables
+| Variable | Description |
+|----------|-------------|
+| `@pT` | Top pane (info bar) |
+| `@pL` | Left pane (file list) |
+| `@pR` | Right pane (preview) |
+| `@pB` | Bottom pane (status) |
+| `@pCmd` | Command prompt |
+| `@selected` | Currently selected file/dir |
+| `@tagged` | Array of tagged items |
+| `@external_program_running` | Set true when launching TUI programs |
+### Plugin Helper Functions
 ```ruby
-def custom_handler
-  if @selected&.end_with?('.ext')
-    @external_program_running = true  # Prevent SIGWINCH interference
-    system('stty sane < /dev/tty')
-    system('clear < /dev/tty > /dev/tty')
-    Cursor.show
-    system("my_program #{Shellwords.escape(@selected)}")
-    @external_program_running = false  # Re-enable SIGWINCH handling
-    # Restore terminal for RTFM
-    system('stty raw -echo isig < /dev/tty')
-    $stdin.raw!
-    $stdin.echo = false
-    Cursor.hide
-    Rcurses.clear_screen
-    refresh
-    render
-  end
-end
+# Capture command output
+output = command("ls -la", timeout: 5)
+# Run command, show errors
+shell("mv file1 file2", background: false)
+# Run and show both stdout/stderr in right pane
+shellexec("grep -r pattern .")
+```
+---
+## Image Display
+RTFM uses the [termpix](https://github.com/isene/termpix) gem for modern multi-protocol image display.
+### Supported Protocols
+| Terminal | Protocol | Status |
+|----------|----------|--------|
+| urxvt | w3m | ✓ Perfect |
+| xterm | Sixel | ✓ Perfect |
+| mlterm | Sixel | ✓ Perfect |
+| kitty | w3m | ✓ Works (brief flash) |
+| foot | Sixel | ✓ Perfect |
+### Features
+- **EXIF orientation** - Phone photos display correctly
+- **Auto-detection** - Best protocol for your terminal
+- **Aspect ratio** - Images never stretched
+- **Toggle** - Press `_` to toggle image preview
+- **Copy to clipboard** - Press `Ctrl-y` on image
+### Terminal Compatibility
+Best image experience with: urxvt, xterm, mlterm, Eterm
+---
+## RTFM vs Ranger
+| Feature | RTFM | Ranger |
+|---------|------|--------|
+| **Language** | Pure Ruby | Python |
+| **Size** | ~6K lines (single file) | ~22K lines (modular) |
+| **License** | Unlicense (public domain) | GPL v3 |
+| **LS_COLORS** | Native parsing | Requires theming |
+| **Remote SSH/SFTP** | ✓ Built-in | ✗ |
+| **Undo System** | ✓ Comprehensive | Limited |
+| **Trash Bin** | ✓ With restore | ✗ |
+| **OpenAI Integration** | ✓ | ✗ |
+| **Permission/Ownership Undo** | ✓ | ✗ |
+| **Image Protocols** | Sixel + w3m | Various (ueberzug, kitty) |
+| **Tab Management** | ✓ Enhanced | ✓ Basic |
+| **Bulk Rename** | ✓ Patterns | ✓ |
+| **Plugin System** | Ruby-based | Python-based |
+| **Community** | Small | Large (16.6k stars) |
+| **Documentation** | Growing | Extensive |
+**Philosophy:**
+- **Ranger**: Minimalistic, "do one thing well"
+- **RTFM**: Feature-packed, "jam packed with features"
+**Best for:**
+- **RTFM**: Power users wanting SSH workflows, undo, AI integration, maximum features
+- **Ranger**: Users wanting clean, minimal, well-documented VIM-style navigation
+---
+## Documentation
+- **Man page**: `man rtfm`
+- **Interactive help**: Press `?` in RTFM
+- **GitHub**: https://github.com/isene/RTFM
+- **Changelog**: See [CHANGELOG.md](CHANGELOG.md)
+- **Issues/Bugs**: https://github.com/isene/RTFM/issues
+### Additional Guides
+- [Getting Started](docs/getting-started.md) - Installation, first run, basic operations
+- [Configuration Guide](docs/configuration.md) - Complete settings reference
+- [Remote Browsing](docs/remote-browsing.md) - SSH/SFTP workflows
+- [Plugin Development](docs/plugins.md) - Extend RTFM with custom handlers
+---
+## Screenshots
+![RTFM in action](img/screenshot-logo.png)
+**Keyboard Cheat Sheet:**
+![RTFM keyboard reference](img/rtfm-kb.png)
+---
+## Latest Updates
+### Version 7.3 Highlights
+- **Modern image display** with termpix gem (Sixel + w3m protocols)
+- **Performance optimizations** for large images
+- **UTF-16 file support** for opening in $EDITOR
+- **Image clipboard copy** (Ctrl-y)
+- **Persistent selection** after operations
+### Version 7.2 - BREAKING CHANGE
+**Batch operations** now use consistent "tagged OR selected" logic:
+- Tagged items exist → operate ONLY on tagged
+- No tagged items → operate on selected
+**Migration:** Explicitly tag selected item with `t` if you want it included.
+See [CHANGELOG.md](CHANGELOG.md) for complete version history.
+---
+## How It Works
+RTFM is a two-pane file manager with enhanced tab support:
+- **Left pane**: Directory/file list with navigation
+- **Right pane**: Preview, info, command output
+- **Top bar**: Current path and file metadata
+- **Bottom bar**: Status, prompts, commands
+- **Tab indicator**: `[2/5]` shows current tab position
+**Tab Features:**
+- Multiple tabs for multi-directory management
+- Duplicate tabs (`}`) to copy directory context
+- Rename tabs (`{`) for organization
+- Quick switch with number keys (1-9)
+**Enhanced UX:**
+- VIM-style navigation (hjkl)
+- Arrow key support
+- Persistent bookmarks and tagged items
+- Command history across sessions
+- Comprehensive undo for safety
+---
+## First Run
+On first launch, RTFM:
+1. Shows welcome message
+2. Adds `r` function to your shell (~/.bashrc, ~/.zshrc)
+3. Creates `~/.rtfm/` directory
+4. Generates plugin templates
+The `r` function lets you:
+- Launch RTFM with single key
+- Exit into RTFM's current directory (not launch directory)
+**Workflow:**
+```bash
+r              # Launch RTFM
+# Navigate to desired directory
+q              # Exit RTFM
+pwd            # You're in RTFM's last directory!
+r              # Back into RTFM
 ```
-***With this, you can mold RTFM to fit your needs better.***
-When writing plugins, there are a few variables you should know:
-Variable  | Description
-----------|------------------------------------------------------------------
-@pT       | Top pane (info bar)
-@pL       | Left pane
-@pR       | Right pane
-@pB       | Bottom pane (status bar)
-@pCmd     | Command pane (asking for commands to execute)
-@pSearch  | Search pane (prompting for what to search for)
-@pAI      | Pane for interacting with (Open)AI
-@pRuby    | Ruby debug/command pane
-@selected | The selected item in the Left pane
-@external_program_running | Set to true when launching terminal programs to prevent SIGWINCH from redrawing RTFM
-Here are three importan hook-ins to use with your plugins:
-### Summary of overlap & choice
-- **Use `command`** when you need to _capture_ output as a value (and optionally handle stderr yourself).
-- **Use `shell`** for fire-and-forget side-effects where you don't care about stdout but still want error reporting.
-- **Use `shellexec`** when you want both stdout and stderr printed into RTFM's Right pane automatically.
-#### `command(cmd, timeout: 5, return_both: false) → String or [stdout, stderr]`
-- **What it does:** Runs `bash -c cmd`, captures both stdout and stderr, enforces a timeout.
-- **When to use:** Programmatically grab output (and optionally errors) of a shell command (e.g. building directory listings or previews).
-- **Key points:**
-  - By default prints stderr into the Right pane and returns stdout.
-  - `return_both: true` returns `[stdout, stderr]` instead of auto-printing errors.
-  - Times out after `timeout` seconds, killing the process if necessary.
-#### `shell(cmd, background: false, err: nil) → nil`
-- **What it does:** Fires off `cmd` via `system`, redirecting stderr into a log file (default: `$TMP/rtfm_err.log`), optionally in the background.
-- **When to use:** Run side-effecting commands (e.g. `xdg-open`, `mv`) where you don't need stdout but still want error reporting.
-- **Key points:**
-  - If `background: true`, runs `cmd &`.
-  - Any stderr output is read from the log and shown via `@pR.say`.
-  - Doesn't return command output, errors only.
-#### `shellexec(cmd, timeout: 10) → nil`
-- **What it does:** A thin wrapper over `command(cmd, timeout:, return_both: true)` that _always_ prints both stdout and stderr into the Right pane.
-- **When to use:** Run a command and echo both its stdout and any errors back to the user—e.g. interactive grep, locate, or other one-off shell tools.
-- **Key points:**
-  - Internally calls `command(..., return_both: true)`.
-  - Prints stderr first, then stdout.
-  - Doesn't return anything to the caller.
-## Screencast
-Here's a screencast for an early version of RTFM, but it shows the basic stuff:
-[![RTFM screencast](/img/screenshot.png)](https://youtu.be/ANUOlDryUng)
+---
+## Why RTFM?
+Created to solve a specific problem: file managers should parse LS_COLORS natively instead of requiring separate themes.
+**The Origin Story:**
+While working on a [complete LS_COLORS setup](https://github.com/isene/LS_COLORS), I realized creating a matching ranger theme was redundant. File managers should respect terminal colors by default.
+This became RTFM - a file manager that parses LS_COLORS automatically.
+**Why Rewrite?**
+The old curses library was clumsy. So I created [rcurses](https://github.com/isene/rcurses) - a modern, pure Ruby curses implementation. From v5 onwards, RTFM runs on rcurses, providing:
+- Better stability
+- Cleaner code
+- More features
+- Active development
+---
 ## Development
-I don't expect this program to be used by others. I do this for my own
-enjoyment and because I want a file manager that fits my needs better than any
-others I have found. If you come up with a feature request I feel is cool, I
-may include it. Bug reports are always welcome.
-A note to developers: You can hit the "@" key to enter the Ruby debug mode
-where anything you enter in the bottom command bar will be sent to the Ruby
-eval() function and output to the right pane. You can for instance issue
-`puts @searched` to see the currently active search pattern.
+### For Users
+Bug reports and feature requests welcome at: https://github.com/isene/RTFM/issues
+### For Developers
+**Ruby Debug Mode:**
+Press `@` to enter Ruby REPL mode. Execute arbitrary Ruby code:
+```ruby
+# Examples:
+puts @selected        # Show current selection
+puts @tagged.inspect  # Show tagged items
+puts @marks          # Show bookmarks
+```
+**Plugin Development:**
+See `~/.rtfm/plugins/` directory for templates and examples.
+**Contributing:**
+This is a personal project built for my needs. Cool feature requests may be included. Code contributions welcome via pull requests.
+---
+## Author
+**Geir Isene**
+- Email: g@isene.com
+- Web: https://isene.com
+- GitHub: https://github.com/isene
+## License
+**Unlicense** - Public Domain
+Permission granted to use, copy, modify, distribute, and sell this software for any purpose without restriction.
+---
+## See Also
+- [rcurses](https://github.com/isene/rcurses) - Pure Ruby curses library
+- [termpix](https://github.com/isene/termpix) - Terminal image display gem
+- [ranger](https://github.com/ranger/ranger) - Python-based file manager
+- [LS_COLORS](https://github.com/isene/LS_COLORS) - Comprehensive terminal color setup
+---
+**Stay Amazing** ✓