From 52929322d7296e80ea7a73b0b404d25fe6af114f Mon Sep 17 00:00:00 2001
From: Hayden Hargreaves <hhargreaves2006@gmail.com>
Date: Mon, 23 Feb 2026 17:18:37 -0700
Subject: [PATCH] doc: added buffers to feature doc

---
 FEATURES.md | 60 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 60 insertions(+)

diff --git a/FEATURES.md b/FEATURES.md
index b75d998..79f02ac 100644
--- a/FEATURES.md
+++ b/FEATURES.md
@@ -259,6 +259,66 @@
 
 ---
 
+## Buffers
+
+Buffers are in-memory representations of files. A buffer exists for each open file.
+
+### Buffer Model
+- [ ] Buffer struct (id, filename, lines, modified flag, cursor position)
+- [ ] Buffer list/manager
+- [ ] Current buffer tracking
+- [ ] Buffer-local settings (tabstop, filetype, etc.)
+- [ ] Modified/dirty state tracking
+- [ ] Read-only buffer support
+
+### Buffer Navigation
+- [ ] `:e {file}` - Edit file (open in new buffer or switch to existing)
+- [ ] `:bn` / `:bnext` - Next buffer
+- [ ] `:bp` / `:bprev` - Previous buffer
+- [ ] `:b {name}` - Switch to buffer by name (partial match)
+- [ ] `:b {number}` - Switch to buffer by number
+- [ ] `:bf` / `:bfirst` - First buffer
+- [ ] `:bl` / `:blast` - Last buffer
+- [ ] `:buffers` / `:ls` - List all buffers
+- [ ] `ctrl+^` / `ctrl+6` - Switch to alternate (previous) buffer
+
+### Buffer Operations
+- [ ] `:bd` / `:bdelete` - Delete buffer (close file)
+- [ ] `:bd!` - Force delete buffer (discard changes)
+- [ ] `:bw` / `:bwipeout` - Wipe buffer (remove completely)
+- [ ] `:w` - Write current buffer to file
+- [ ] `:w {file}` - Write buffer to specific file
+- [ ] `:wa` - Write all modified buffers
+- [ ] `:sav {file}` - Save as (write to new file, switch to it)
+
+### Buffer State
+- [ ] Track cursor position per buffer
+- [ ] Track undo history per buffer
+- [ ] Track marks per buffer
+- [ ] Remember scroll position when switching
+- [ ] Alternate buffer (`#`) tracking
+
+### Buffer Indicators
+- [ ] `%` - Current buffer (in buffer list)
+- [ ] `#` - Alternate buffer
+- [ ] `a` - Active (loaded and visible)
+- [ ] `h` - Hidden (loaded but not visible)
+- [ ] `+` - Modified
+- [ ] `-` - Read-only
+- [ ] `=` - Readonly (cannot be modified)
+
+### Hidden Buffers
+- [ ] `:set hidden` - Allow switching with unsaved changes
+- [ ] Prompt to save when closing modified buffer
+- [ ] `:q` behavior with modified buffers
+
+### Argument List (Advanced)
+- [ ] `:args` - Show argument list
+- [ ] `:next` / `:prev` - Navigate argument list
+- [ ] `:argadd` / `:argdelete` - Modify argument list
+
+---
+
 ## Plugins / Extensions
 
 ### Harpoon (File Navigation)