rtfm-filemanager 8.1.3 → 8.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e58685e75cad90ce6073efe92abe1fe018bf0371060e652dd86ccf6e7e41d252
-  data.tar.gz: 6fd3b54ac0729a9111aedad4c48b3e50c6b9467547d62e49c14bc22015c58d13
+  metadata.gz: ef7c28629f7646f129d96e76afd871a7ab6030e0adb9983055a247ccc3992ecc
+  data.tar.gz: b1c7f85c145f532f5e3175c5fb2f4642d134149d147fc06b4a26389f25d1f42c
 SHA512:
-  metadata.gz: 26cb3b44a3b43f90c326050c18c0809b4d689be8610a38c9c591c5bc0519cb197988fd6b63305d0620ab7dddd3f00ae848ed2f5716b166c31d2dd8eab0237719
-  data.tar.gz: 76a5d98f72158d0cad178cf5b7c0d71e5ea7bea5bc51d06d2e23c2cbe3342e81e22508681f614f80f247e26394d299bf87765539e35b31461c27131c92a587db
+  metadata.gz: 9207a4adaeed8a14f3a7a78a70fafdcba2318635605406168679aefe6f2e859cedc7c4053ebcf0d08f610415874df41f061fedad1fd41955cbcc7ae1eb2206a9
+  data.tar.gz: 1c8b70f11a2436b5beedebf1b0a510395e62e93a99ed1050192f381097693816731864f46c86a22eeebb8139ae9bb09367625c01ad9856142cffb2b271fdb53d

data/CHANGELOG.md

@@ -5,6 +5,17 @@ All notable changes to RTFM will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [8.2.0] - 2026-03-15
+
+### Added
+- **Plugin system** - Plugins in `~/.rtfm/plugins/` are auto-loaded on startup. Each plugin is a `.rb` file with metadata comments (`@name`, `@description`, `@key`). Disabled plugins use `.rb.off` extension
+- **Plugin manager** (`V` key) - Enable/disable plugins live without restarting RTFM. Press `?` on any plugin to view its built-in help text
+- **Settings plugin** (`C` key) - Interactive editor for settings without dedicated keys: trash mode, run-mailcap, interactive programs, ls flags, OpenAI config, and all pane colors with live preview
+- **Git plugin** (`Ctrl-G`) - Quick git menu: status, diff, commit+push, and log, all from within RTFM
+- **Bookmarks plugin** (`F6`) - Unlimited directory bookmarks with fuzzy filtering, complementing the built-in single-letter marks
+- **Notes plugin** (`F5`) - Attach text notes to any file or directory, stored in `~/.rtfm/notes/`
+- **Opener plugin** (`RIGHT`/`l`) - Define custom programs for specific file extensions via a simple hash
+
 ## [8.1.3] - 2026-03-13
 
 ### Fixed

data/README.md

@@ -92,10 +92,10 @@ After first run, use `r` command to launch RTFM and exit into your current direc
 - **Navi integration** - Interactive command cheatsheets
 
 ### Developer Features
-- **Plugin architecture** - Custom preview handlers and key bindings
+- **Plugin system** - Live enable/disable plugins with built-in manager (`V` key)
+- **Example plugins** - Settings editor, git, bookmarks, notes, custom openers
 - **Ruby debug mode** - Execute arbitrary Ruby in context
 - **Command history** - Preserved across sessions
-- **Extensible** - Clean plugin API
 
 ---
 
@@ -168,6 +168,7 @@ For complete reference: `man rtfm` or press `?` in RTFM
 | `q` | Quit (save config) |
 | `Q` | Quit (don't save) |
 | `r` | Refresh display |
+| `V` | Plugin manager |
 
 ### Navigation
 
@@ -359,10 +360,12 @@ Configuration stored in `~/.rtfm/conf`
 
 | Action | Command |
 |--------|---------|
-| View config | Press `C` |
+| View config | Press `C` (or interactive editor with Settings plugin) |
 | Save config | Press `W` |
 | Reload config | Press `R` |
 
+**Tip:** Install the Settings plugin for an interactive settings editor with live color preview. See [Plugins](#plugins).
+
 ### Common Settings
 
 ```ruby
@@ -492,50 +495,75 @@ The chat maintains context throughout your RTFM session, so follow-up questions
 
 ## Plugins
 
-RTFM supports two types of plugins in `~/.rtfm/plugins/`:
+RTFM has a plugin system with live enable/disable. Plugins live in `~/.rtfm/plugins/` as `.rb` files and are auto-loaded on startup.
 
-### 1. Preview Handlers (`preview.rb`)
+### Plugin Manager (`V` key)
 
-Add custom file type previews:
+Press `V` to open the built-in plugin manager:
+- See all available plugins with their status (ON/OFF)
+- Press `ENTER` to toggle a plugin on or off (takes effect immediately)
+- Press `?` to view the plugin's built-in help text
+- No restart required
 
-```ruby
-# ~/.rtfm/plugins/preview.rb
+### Example Plugins
 
-# Syntax: ext1, ext2 = command with @s placeholder
-# @s is replaced with shell-escaped filename
+RTFM ships with five example plugins in the `examples/` directory. Copy any of them to `~/.rtfm/plugins/` to activate:
 
-# Examples:
-txt, log = bat -n --color=always @s
-md = pandoc @s -t plain
-pdf = pdftotext -f 1 -l 4 @s -
-json = jq . @s
+```bash
+cp examples/settings.rb ~/.rtfm/plugins/
+cp examples/git.rb ~/.rtfm/plugins/
+cp examples/bookmarks.rb ~/.rtfm/plugins/
+cp examples/notes.rb ~/.rtfm/plugins/
+cp examples/opener.rb ~/.rtfm/plugins/
 ```
 
-### 2. Custom Key Bindings (`keys.rb`)
+| Plugin | Key | Description |
+|--------|-----|-------------|
+| **Settings** | `C` | Interactive editor for settings without dedicated keys (colors, trash, interactive programs, OpenAI config). Color changes apply in real-time. Overrides the default config viewer |
+| **Git** | `Ctrl-G` | Git operations menu: status, diff, commit+push, log. Output shown in right pane |
+| **Bookmarks** | `F6` | Unlimited directory bookmarks with fuzzy filtering. Add, delete, and jump to bookmarked directories. Complements the built-in single-letter marks (m/') |
+| **Notes** | `F5` | Attach text notes to any file or directory. View, edit, or delete notes. Stored in `~/.rtfm/notes/` |
+| **Opener** | `RIGHT`/`l` | Custom file openers by extension. Configure a hash of extension-to-command mappings (e.g., `.hl` files open in hyperlist) |
+
+### Writing Your Own Plugins
 
-Add or override key bindings:
+A plugin is a simple Ruby file with metadata comments and KEYMAP bindings:
 
 ```ruby
-# ~/.rtfm/plugins/keys.rb
+# @name: My Plugin
+# @description: What it does
+# @key: X
+
+KEYMAP['X'] = :my_action
+
+# Optional: register help text shown by ? in plugin manager
+PLUGIN_HELP['My Plugin'] = <<~HELP
+  This is the help text for my plugin.
+  Shown when pressing ? in the plugin manager.
+HELP
+
+def my_action
+  clear_image
+  @pR.update = true
+  @pR.say("Hello from my plugin!")
+end
+```
 
-# Add new key binding
-KEYMAP['Z'] = :my_custom_action
+Plugins can also be defined in `~/.rtfm/keys.rb` for personal bindings that don't need the enable/disable mechanism.
 
-def my_custom_action(_chr)
-  @pB.say("Custom action triggered!")
-  # Use @pL, @pR, @selected, etc.
-end
+### Preview Handlers (`preview.rb`)
 
-# Git commit shortcut example
-KEYMAP['C-G'] = :git_commit
+Custom file type previews are configured separately in `~/.rtfm/preview.rb`:
 
-def git_commit
-  message = @pCmd.ask('Commit message: ', '')
-  shellexec("git add . && git commit -m '#{message}' && git push")
-end
+```ruby
+# Syntax: ext1, ext2 = command with @s placeholder
+txt, log = bat -n --color=always @s
+md = pandoc @s -t plain
+pdf = pdftotext -f 1 -l 4 @s -
+json = jq . @s
 ```
 
-### Available Variables
+### Available Variables for Plugin Authors
 
 | Variable | Description |
 |----------|-------------|
@@ -543,22 +571,33 @@ end
 | `@pL` | Left pane (file list) |
 | `@pR` | Right pane (preview) |
 | `@pB` | Bottom pane (status) |
-| `@pCmd` | Command prompt |
+| `@pCmd` | Command prompt (use `.ask(prompt, default)` for input) |
 | `@selected` | Currently selected file/dir |
 | `@tagged` | Array of tagged items |
 | `@external_program_running` | Set true when launching TUI programs |
+| `PLUGIN_HELP` | Hash to register help text (keyed by plugin name) |
 
 ### Plugin Helper Functions
 
 ```ruby
-# Capture command output
+# Capture command output as string
 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
+# Run command interactively (full terminal)
 shellexec("grep -r pattern .")
+
+# Read a keypress
+chr = getchr
+
+# Clear any displayed image
+clear_image
+
+# Text formatting
+"text".fg(112)   # foreground color (0-255)
+"text".bg(236)   # background color
+"text".b         # bold
+"text".u         # underline
+"text".r         # reverse
 ```
 
 ---
@@ -650,6 +689,11 @@ Best image experience with: kitty, urxvt, xterm, mlterm, foot
 
 ## Latest Updates
 
+### Version 8.2 Highlights
+
+- **Plugin system with live enable/disable** - Plugins in `~/.rtfm/plugins/` are auto-loaded on startup. Toggle them on and off at runtime with the plugin manager (`V` key), no restart needed. Each plugin can register help text viewable with `?`.
+- **Five example plugins** - Settings editor, git operations, directory bookmarks, file notes, and custom file openers. Copy from `examples/` to `~/.rtfm/plugins/` to use.
+
 ### Version 8.1 Highlights
 
 - **File picker mode** - `rtfm --pick=/path/to/output.txt` launches RTFM as a file selector. Browse and tag files normally with `t`, then quit with `q`. Tagged file paths are written one per line to the output file. Enables integration with email clients, upload tools, and other applications that need a file selection dialog.

data/bin/rtfm

@@ -18,7 +18,7 @@
 #             get a great understanding of the code itself by simply sending
 #             or pasting this whole file into you favorite AI for coding with
 #             a prompt like this: "Help me understand every part of this code".
-@version    = '8.1.0' # File picker mode (--pick) for integration with other tools
+@version    = '8.2.0' # Plugin system with live enable/disable and built-in plugin manager
 
 # SAVE & STORE TERMINAL {{{1
 ORIG_STTY = `stty -g`.chomp
@@ -173,6 +173,7 @@ CONFIG_FILE   = File.join(RTFM_HOME, 'conf')
     W       = Write parameters to ~/.rtfm/conf: @marks, @hash, @history, @rubyhistory, @aihistory, @sshhistory
               @lslong, @lsall, @lsorder, @lsinvert, @width, @border, @preview, @trash
     C       = Show the current configuration in ~/.rtfm/conf
+    V       = Plugin manager (enable/disable plugins from ~/.rtfm/plugins/)
     q       = Quit (save basic configuration: @marks, @hash, @history, @rubyhistory, @aihistory, @sshhistory)
     Q       = QUIT (without writing any changes to the config file)
 
@@ -928,6 +929,7 @@ KEYMAP = { # {{{2
   'R'       => :load_config,
   'C'       => :show_config,
   'W'       => :write_config,
+  'V'       => :plugin_manager,
   'q'       => :quit_and_save,
   'Q'       => :quit_no_save,
 
@@ -1078,6 +1080,78 @@ if File.exist?(KEYS_FILE)
   end
 end
 
+# PLUGIN SYSTEM {{{2
+# Plugins live in ~/.rtfm/plugins/ as .rb files.
+# Each plugin should start with metadata comments:
+#   # @name: My Plugin
+#   # @description: What it does
+#   # @key: X (optional, documents which key it binds)
+# Disabled plugins have .rb.off extension.
+
+@plugins = {} # name => { file:, enabled:, meta:, saved_keys: }
+PLUGIN_HELP = {} # name => help string (registered by each plugin)
+
+def parse_plugin_meta(file)
+  meta = { name: File.basename(file).sub(/\.rb(\.off)?$/, ''), description: '', key: '' }
+  File.foreach(file) do |line|
+    break unless line.start_with?('#')
+    meta[:name]        = $1.strip if line =~ /^#\s*@name:\s*(.+)/
+    meta[:description] = $1.strip if line =~ /^#\s*@description:\s*(.+)/
+    meta[:key]         = $1.strip if line =~ /^#\s*@key:\s*(.+)/
+  end
+  meta
+end
+
+def load_plugin(name)
+  p = @plugins[name]
+  return unless p
+  snapshot = KEYMAP.dup
+  begin
+    load p[:file].sub(/\.off$/, '')
+    # Track which KEYMAP entries changed
+    changed = {}
+    KEYMAP.each { |k, v| changed[k] = snapshot[k] if snapshot[k] != v }
+    snapshot.each { |k, v| changed[k] = v unless KEYMAP.key?(k) }
+    p[:saved_keys] = changed
+    p[:enabled] = true
+  rescue => e
+    @plugin_errors << "Error loading plugin #{name}: #{e.class}: #{e.message}"
+  end
+end
+
+def unload_plugin(name)
+  p = @plugins[name]
+  return unless p
+  (p[:saved_keys] || {}).each do |k, original|
+    original ? KEYMAP[k] = original : KEYMAP.delete(k)
+  end
+  p[:enabled] = false
+end
+
+def toggle_plugin(name)
+  p = @plugins[name]
+  return unless p
+  base = p[:file].sub(/\.off$/, '')
+  off  = base + '.off'
+  if p[:enabled]
+    unload_plugin(name)
+    File.rename(base, off) if File.exist?(base)
+    p[:file] = off
+  else
+    File.rename(off, base) if File.exist?(off)
+    p[:file] = base
+    load_plugin(name)
+  end
+end
+
+# Scan and load enabled plugins
+Dir.glob(File.join(PLUGINS_DIR, '*.rb{,.off}')).sort.each do |f|
+  meta = parse_plugin_meta(f)
+  enabled = !f.end_with?('.off')
+  @plugins[meta[:name]] = { file: f, enabled: false, meta: meta, saved_keys: {} }
+  load_plugin(meta[:name]) if enabled
+end
+
 # MAIN GETKEY FOR USER INPUT {{{2
 def getkey # {{{3
   chr = getchr(1)
@@ -1197,6 +1271,59 @@ def show_config
   @pR.say('Configuration'.u.fg(254) + ":\n\n" + @conf.fg(249))
 end
 
+def plugin_manager # {{{3
+  clear_image
+  names = @plugins.keys.sort
+  if names.empty?
+    @pR.say("Plugins".u.fg(254) + "\n\nNo plugins found in ~/.rtfm/plugins/\n\nPlace .rb files there to make them available.")
+    return
+  end
+  sel = 0
+  loop do
+    lines = []
+    lines << "Plugins".b.fg(254)
+    lines << ""
+    names.each_with_index do |name, i|
+      p = @plugins[name]
+      status = p[:enabled] ? " ON ".bg(22).fg(255) : " OFF".bg(52).fg(255)
+      key_info = p[:meta][:key].empty? ? '' : " [#{p[:meta][:key]}]".fg(240)
+      desc = p[:meta][:description].empty? ? '' : " #{p[:meta][:description]}".fg(249)
+      line = "#{status} #{name}#{key_info}#{desc}"
+      line = i == sel ? line.u : line
+      lines << line
+    end
+    lines << ""
+    lines << "j/k:move  ENTER:toggle  ?:help  q:close".fg(240)
+    @pR.update = true
+    @pR.say(lines.join("\n"))
+
+    chr = getchr
+    case chr
+    when 'q', 'ESC'
+      break
+    when 'j', 'DOWN'
+      sel = (sel + 1) % names.size
+    when 'k', 'UP'
+      sel = (sel - 1) % names.size
+    when 'ENTER', 'RIGHT', 'LEFT'
+      toggle_plugin(names[sel])
+    when '?'
+      name = names[sel]
+      help = PLUGIN_HELP[name]
+      if help
+        @pR.update = true
+        @pR.say(name.b.fg(254) + " help\n\n" + help)
+        getchr
+      else
+        @pB.say("No help available for #{name}.")
+      end
+    end
+  end
+  @pR.update = true
+  refresh
+  render
+end
+
 def write_config # {{{3
   conf_write(all: true)
   show_config

data/examples/bookmarks.rb

@@ -0,0 +1,137 @@
+# @name: Bookmarks
+# @description: Quick directory bookmarks with fuzzy jump
+# @key: F6
+
+BOOKMARKS_FILE = File.expand_path('~/.rtfm/bookmarks.txt')
+
+KEYMAP['F6'] = :bookmark_menu
+
+PLUGIN_HELP['Bookmarks'] = <<~HELP
+  Quick directory bookmarks with fuzzy filtering.
+
+  Press F6 to open the bookmark manager.
+
+  #{"Commands:".b}
+    a       Add current directory to bookmarks
+    d       Delete selected bookmark
+    j/k     Navigate up/down
+    ENTER   Jump to selected directory
+    /       Filter bookmarks (fuzzy search)
+    q/ESC   Close
+
+  #{"Difference from marks:".b}
+    Marks (m/') are single-letter slots (a-z) that
+    save a directory path for quick recall. You get
+    26 slots max, and must remember which letter
+    maps to which directory.
+
+    Bookmarks are an unlimited named list of
+    directories with fuzzy filtering. Better for
+    large collections of frequently visited paths.
+    They persist in ~/.rtfm/bookmarks.txt.
+HELP
+
+def load_bookmarks
+  return [] unless File.exist?(BOOKMARKS_FILE)
+  File.readlines(BOOKMARKS_FILE).map(&:strip).reject(&:empty?)
+end
+
+def save_bookmarks(bookmarks)
+  File.write(BOOKMARKS_FILE, bookmarks.join("\n") + "\n")
+end
+
+def bookmark_menu
+  clear_image
+
+  sel = 0
+  filter = nil
+
+  loop do
+    bookmarks = load_bookmarks
+    visible = filter ? bookmarks.select { |b| b.downcase.include?(filter.downcase) } : bookmarks
+
+    lines = []
+    lines << "Bookmarks".b.fg(254)
+    lines << "filter: #{filter}".fg(240) if filter
+    lines << ""
+
+    if visible.empty?
+      lines << (filter ? "No matches." : "No bookmarks yet.").fg(240)
+    else
+      # Find common prefix to dim shared parts
+      common = ""
+      if visible.size > 1
+        parts = visible.map { |b| b.split('/') }
+        min_len = parts.map(&:size).min
+        min_len.times do |i|
+          break unless parts.all? { |p| p[i] == parts[0][i] }
+          common += parts[0][i] + '/'
+        end
+      end
+
+      visible.each_with_index do |path, i|
+        idx = bookmarks.index(path)
+        prefix = common.empty? ? "" : path[0, common.length].fg(240)
+        suffix = common.empty? ? path.fg(112) : path[common.length..].fg(112)
+        line = "#{idx.to_s.rjust(2).fg(240)} #{prefix}#{suffix}"
+        line = i == sel ? line.u : line
+        lines << line
+      end
+    end
+
+    lines << ""
+    lines << "a".b.fg(112) + ":add  " + "d".b.fg(112) + ":del  " +
+             "/".b.fg(112) + ":filter  " + "ENTER".b.fg(112) + ":jump  " +
+             "q".b.fg(112) + ":close"
+
+    @pR.update = true
+    @pR.say(lines.join("\n"))
+
+    chr = getchr
+    case chr
+    when 'q', 'ESC'
+      break
+    when 'j', 'DOWN'
+      sel = visible.empty? ? 0 : (sel + 1) % visible.size
+    when 'k', 'UP'
+      sel = visible.empty? ? 0 : (sel - 1) % visible.size
+    when 'a'
+      cwd = Dir.pwd
+      unless bookmarks.include?(cwd)
+        bookmarks << cwd
+        save_bookmarks(bookmarks)
+        @pB.say("Bookmarked: #{cwd}")
+      else
+        @pB.say("Already bookmarked.")
+      end
+    when 'd'
+      unless visible.empty?
+        path = visible[sel]
+        bookmarks.delete(path)
+        save_bookmarks(bookmarks)
+        sel = [sel, visible.size - 2].max
+        sel = 0 if sel < 0
+        @pB.say("Removed: #{path}")
+      end
+    when 'ENTER'
+      unless visible.empty?
+        path = visible[sel]
+        if Dir.exist?(path)
+          Dir.chdir(path)
+          @pB.say("Jumped to: #{path}")
+          break
+        else
+          @pB.say("Directory not found: #{path}")
+        end
+      end
+    when '/'
+      input = @pCmd.ask('Filter: ', filter || '')
+      filter = input.strip.empty? ? nil : input.strip
+      sel = 0
+    end
+  end
+
+  @pR.update = true
+  refresh
+  render
+end

data/examples/git.rb

@@ -0,0 +1,73 @@
+# @name: Git
+# @description: Git operations (status, commit, push, diff)
+# @key: C-G
+
+KEYMAP['C-G'] = :git_menu
+
+PLUGIN_HELP['Git'] = <<~HELP
+  Quick git operations for the current directory.
+
+  Press Ctrl-G to open the git menu.
+
+  #{"Commands:".b}
+    s   Show git status
+    d   Show git diff
+    c   Stage all, commit (prompts for message), push
+    l   Show last 20 commits (git log --oneline)
+    q   Close menu
+
+  All output displays in the right pane.
+  The commit command runs interactively so you
+  can see push progress and any errors.
+HELP
+
+def git_menu
+  clear_image
+
+  loop do
+    lines = []
+    lines << "Git".b.fg(254)
+    lines << ""
+    lines << "s".b.fg(112) + "  git status"
+    lines << "d".b.fg(112) + "  git diff"
+    lines << "c".b.fg(112) + "  git add + commit + push"
+    lines << "l".b.fg(112) + "  git log (last 20)"
+    lines << ""
+    lines << "q/ESC: close".fg(240)
+
+    @pR.update = true
+    @pR.say(lines.join("\n"))
+
+    chr = getchr
+    case chr
+    when 's'
+      output = command("git status 2>&1")
+      @pR.update = true
+      @pR.say("git status".b.fg(254) + "\n\n" + output)
+    when 'd'
+      output = command("git diff 2>&1")
+      output = "No changes." if output.strip.empty?
+      @pR.update = true
+      @pR.say("git diff".b.fg(254) + "\n\n" + output)
+    when 'c'
+      message = @pCmd.ask('Commit message: ', '')
+      if message.strip.empty?
+        @pB.say("Aborted: empty commit message.")
+        next
+      end
+      @pB.say("Committing and pushing...")
+      shellexec("git add . && git commit -m '#{message}' && git push", timeout: 20)
+      @pB.full_refresh
+    when 'l'
+      output = command("git log --oneline -20 2>&1")
+      @pR.update = true
+      @pR.say("git log".b.fg(254) + "\n\n" + output)
+    when 'q', 'ESC'
+      break
+    end
+  end
+
+  @pR.update = true
+  refresh
+  render
+end

data/examples/notes.rb

@@ -0,0 +1,92 @@
+# @name: Notes
+# @description: Attach notes to files/directories, shown in right pane
+# @key: F5
+
+require 'fileutils'
+
+NOTES_DIR = File.expand_path('~/.rtfm/notes')
+FileUtils.mkdir_p(NOTES_DIR)
+
+KEYMAP['F5'] = :toggle_note
+
+PLUGIN_HELP['Notes'] = <<~HELP
+  Attach text notes to any file or directory.
+
+  Press F5 on any selected item to view, create,
+  edit, or delete its note.
+
+  #{"How it works:".b}
+    If no note exists, you're prompted to create one.
+    If a note exists, it shows in the right pane
+    with options to edit or delete.
+
+  #{"Commands (when viewing a note):".b}
+    e   Edit the note
+    d   Delete the note
+    q   Close
+
+  #{"Difference from marks:".b}
+    Marks (m/') are single-letter bookmarks for
+    quick directory jumping. Notes are free-text
+    annotations attached to specific files or
+    directories, useful for reminders, TODO items,
+    or documentation.
+
+  Notes are stored in ~/.rtfm/notes/ as text files.
+HELP
+
+def note_path_for(file)
+  File.join(NOTES_DIR, file.gsub('/', '%') + '.txt')
+end
+
+def toggle_note
+  clear_image
+  file = @selected
+  npath = note_path_for(file)
+  has_note = File.exist?(npath)
+
+  if has_note
+    note = File.read(npath)
+    loop do
+      lines = []
+      lines << "Note for:".b.fg(254)
+      lines << File.basename(file).fg(112)
+      lines << ""
+      lines << note
+      lines << ""
+      lines << "e".b.fg(112) + "  edit note"
+      lines << "d".b.fg(112) + "  delete note"
+      lines << "q/ESC: close".fg(240)
+
+      @pR.update = true
+      @pR.say(lines.join("\n"))
+
+      chr = getchr
+      case chr
+      when 'e'
+        input = @pCmd.ask('Note: ', note)
+        unless input.strip.empty?
+          File.write(npath, input)
+          note = input
+          @pB.say('Note updated.')
+        end
+      when 'd'
+        File.delete(npath)
+        @pB.say('Note deleted.')
+        break
+      when 'q', 'ESC'
+        break
+      end
+    end
+  else
+    input = @pCmd.ask('Note: ', '')
+    unless input.strip.empty?
+      File.write(npath, input)
+      @pB.say('Note saved.')
+    end
+  end
+
+  @pR.update = true
+  refresh
+  render
+end

data/examples/opener.rb

@@ -0,0 +1,87 @@
+# @name: Opener
+# @description: Custom file openers by extension (override default open behavior)
+# @key: RIGHT/l (overrides move_right)
+
+require 'shellwords'
+
+# User-configurable openers hash:
+# Extension => command string (use %f for file path)
+PLUGIN_HELP['Opener'] = <<~HELP
+  Custom file openers by extension.
+
+  Overrides RIGHT/l to check selected files against
+  a list of custom openers before using the default
+  open behavior.
+
+  #{"Configuration:".b}
+    Edit the CUSTOM_OPENERS hash in the plugin file
+    (~/.rtfm/plugins/opener.rb):
+
+    CUSTOM_OPENERS = {
+      '.md'  => 'glow %f',
+      '.pdf' => 'zathura %f',
+      '.hl'  => 'hyperlist %f',
+    }
+
+    Use %f as placeholder for the file path.
+
+  #{"How it works:".b}
+    When you press RIGHT or l on a file, the plugin
+    checks if its extension matches any entry in
+    CUSTOM_OPENERS. If yes, it launches that program
+    interactively. If no match, the normal RTFM
+    open behavior is used.
+HELP
+
+CUSTOM_OPENERS = {
+  # '.md'  => 'glow %f',        # Example: markdown viewer
+  # '.pdf' => 'zathura %f',     # Example: PDF viewer
+  # '.csv' => 'visidata %f',    # Example: CSV explorer
+  # '.hl'  => 'hyperlist %f',   # Example: HyperList files
+}
+
+def custom_open
+  # Check if the selected file matches any registered extension
+  ext = CUSTOM_OPENERS.keys.find { |e| @selected.end_with?(e) }
+
+  unless ext
+    # No custom opener, fall back to original move_right
+    move_right
+    return
+  end
+
+  cmd = CUSTOM_OPENERS[ext].gsub('%f', Shellwords.escape(@selected))
+
+  # Launch the program interactively (same pattern as RTFM's interactive handling)
+  @external_program_running = true
+  system("stty #{ORIG_STTY} < /dev/tty")
+  system('stty sane < /dev/tty')
+  system('clear < /dev/tty > /dev/tty')
+  Cursor.show
+
+  pid = Process.spawn(cmd,
+                      in:  '/dev/tty',
+                      out: '/dev/tty',
+                      err: '/dev/tty')
+  begin
+    Process.wait(pid)
+  rescue Interrupt
+    Process.kill('TERM', pid) rescue nil
+    retry
+  ensure
+    @external_program_running = false
+  end
+
+  # Restore RTFM's terminal state
+  system('stty raw -echo isig < /dev/tty')
+  $stdin.raw!
+  $stdin.echo = false
+  Cursor.hide
+  Rcurses.clear_screen
+  refresh
+  render
+end
+
+KEYMAP['RIGHT']   = :custom_open
+KEYMAP['l']       = :custom_open
+KEYMAP['C-RIGHT'] = :custom_open

data/examples/settings.rb

@@ -0,0 +1,186 @@
+# @name: Settings
+# @description: Interactive settings editor (colors, toggles, paths)
+# @key: C
+
+KEYMAP['C'] = :show_settings
+
+PLUGIN_HELP['Settings'] = <<~HELP
+  Interactive editor for RTFM settings that don't
+  have their own dedicated keys.
+
+  Overrides the default 'C' (show config) key.
+
+  #{"Navigation:".b}
+    j/k or UP/DOWN  Navigate settings
+    LEFT/RIGHT      Toggle booleans, adjust colors +-1
+    H/L             Adjust colors +-10
+    ENTER           Edit text fields or type color number
+    q/ESC           Save and close
+
+  #{"Settings included:".b}
+    Trash mode, run-mailcap, interactive programs,
+    custom ls flags, OpenAI key/model, and all
+    pane colors (top, bottom, search, command,
+    ruby, AI, SSH bars).
+
+  Changes are saved to ~/.rtfm/conf on close.
+  Color changes apply immediately.
+HELP
+
+def show_settings
+  clear_image
+
+  # Settings definitions: [label, variable, type, options]
+  # Types: :bool, :cycle, :int_range, :text
+  settings = [
+    ['Trash (move to trash)',   :@trash,        :bool],
+    ['Use run-mailcap',         :@runmailcap,   :bool],
+    ['Interactive programs',    :@interactive,   :text],
+    ['Custom ls flags',         :@lsuser,       :text],
+    ['OpenAI API key',          :@ai,           :text_masked],
+    ['OpenAI model',            :@aimodel,      :text],
+    ['Top bar color',           :@topcolor,     :color],
+    ['Bottom bar color',        :@bottomcolor,  :color],
+    ['Search bar color',        :@searchcolor,  :color],
+    ['Command bar color',       :@cmdcolor,     :color],
+    ['Ruby bar color',          :@rubycolor,    :color],
+    ['AI bar color',            :@aicolor,      :color],
+    ['SSH bar color',           :@sshcolor,     :color],
+  ]
+
+  sel = 0
+  label_w = settings.map { |s| s[0].length }.max + 2
+
+  loop do
+    # Build display
+    lines = []
+    lines << "Settings".b.fg(254)
+    lines << ""
+
+    settings.each_with_index do |(label, var, type, _opts), i|
+      val = instance_variable_get(var)
+      display = case type
+                when :bool
+                  val ? "Yes" : "No"
+                when :color
+                  swatch = "  #{val}  ".bg(val.to_i).fg(val.to_i > 128 ? 0 : 255)
+                  "#{swatch} #{val}"
+                when :text_masked
+                  val.to_s.length > 8 ? val.to_s[0..3] + "..." + val.to_s[-4..] : val.to_s
+                else
+                  val.to_s
+                end
+
+      pad = label_w - label.length
+      line = "#{label}#{' ' * pad}#{display}"
+      line = i == sel ? line.u : line
+      lines << line
+    end
+
+    lines << ""
+    lines << "j/k:move  LEFT/RIGHT:change  ENTER:edit  q:close".fg(240)
+
+    @pR.update = true
+    @pR.say(lines.join("\n"))
+
+    chr = getchr
+    case chr
+    when 'q', 'ESC'
+      break
+    when 'j', 'DOWN'
+      sel = (sel + 1) % settings.size
+    when 'k', 'UP'
+      sel = (sel - 1) % settings.size
+    when 'RIGHT', 'LEFT', 'ENTER'
+      label, var, type, _opts = settings[sel]
+      val = instance_variable_get(var)
+
+      case type
+      when :bool
+        instance_variable_set(var, !val)
+      when :color
+        delta = chr == 'RIGHT' ? 1 : chr == 'LEFT' ? -1 : 0
+        if chr == 'ENTER'
+          input = @pCmd.ask("#{label} (0-255): ", val.to_s).strip
+          new_val = input.to_i
+          instance_variable_set(var, new_val.clamp(0, 255))
+        else
+          instance_variable_set(var, (val.to_i + delta).clamp(0, 255))
+        end
+        # Apply color changes immediately
+        apply_color(var)
+      when :text, :text_masked
+        input = @pCmd.ask("#{label}: ", val.to_s)
+        instance_variable_set(var, input)
+      end
+    when 'H'
+      # Jump -10 for color settings
+      _label, var, type, _opts = settings[sel]
+      if type == :color
+        val = instance_variable_get(var)
+        instance_variable_set(var, (val.to_i - 10).clamp(0, 255))
+        apply_color(var)
+      end
+    when 'L'
+      # Jump +10 for color settings
+      _label, var, type, _opts = settings[sel]
+      if type == :color
+        val = instance_variable_get(var)
+        instance_variable_set(var, (val.to_i + 10).clamp(0, 255))
+        apply_color(var)
+      end
+    end
+  end
+
+  # Save all settings to config
+  save_settings(settings)
+  @pR.update = true
+  refresh
+  render
+end
+
+def apply_color(var)
+  case var
+  when :@topcolor
+    @pT.bg = @topcolor
+    @pT.update = true
+  when :@bottomcolor
+    @pB.bg = @bottomcolor
+    @pB.update = true
+  when :@searchcolor
+    @pSearch.bg = @searchcolor
+  when :@cmdcolor
+    @pCmd.bg = @cmdcolor
+  when :@rubycolor
+    @pRuby.bg = @rubycolor
+  when :@aicolor
+    @pAI.bg = @aicolor
+  when :@sshcolor
+    @pSsh.bg = @sshcolor
+  end
+end
+
+def save_settings(settings)
+  @conf = @conf.dup
+  settings.each do |_label, var, type, _opts|
+    val = instance_variable_get(var)
+    name = var.to_s.sub('@', '')
+    line = case type
+           when :bool
+             "@#{name} = #{val}"
+           when :color
+             "@#{name} = #{val}"
+           when :text, :text_masked
+             "@#{name} = '#{val}'"
+           end
+    regex = /^@#{Regexp.escape(name)}\b.*$/
+    if @conf.match?(regex)
+      @conf.sub!(regex, line)
+    else
+      @conf << "\n" unless @conf.end_with?("\n")
+      @conf << line << "\n"
+    end
+  end
+  File.write(CONFIG_FILE, @conf)
+  @pB.say('Settings saved to ~/.rtfm/conf')
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rtfm-filemanager
 version: !ruby/object:Gem::Version
-  version: 8.1.3
+  version: 8.2.0
 platform: ruby
 authors:
 - Geir Isene
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-13 00:00:00.000000000 Z
+date: 2026-03-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rcurses
@@ -66,13 +66,12 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '7.4'
-description: 'RTFM v8.0: Browse and modify archives as virtual directories (extract,
-  delete, add, move), async background file operations, scrollable diff viewer with
-  side-by-side mode. A full featured terminal browser with syntax highlighted files,
+description: 'A full featured terminal file manager with syntax highlighted files,
   images shown in the terminal, videos thumbnailed, etc. Features include remote SSH/SFTP
   browsing, interactive SSH shell, comprehensive undo system, OpenAI integration,
-  bookmarks, and much more. RTFM is one of the most feature-packed terminal file managers.
-  v8.1: File picker mode (--pick) for integration with other tools.'
+  bookmarks, archive browsing, and much more. v8.2: Plugin system with live enable/disable,
+  built-in plugin manager (V key), and example plugins (settings editor, git operations,
+  bookmarks, notes, custom file openers).'
 email: g@isene.com
 executables:
 - rtfm
@@ -89,7 +88,12 @@ files:
 - docs/plugins.md
 - docs/remote-browsing.md
 - docs/troubleshooting.md
+- examples/bookmarks.rb
+- examples/git.rb
+- examples/notes.rb
+- examples/opener.rb
 - examples/rtfm.conf
+- examples/settings.rb
 - img/logo.png
 - img/rtfm-kb.png
 - man/rtfm.1