1 files changed, 75 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..d452f58
--- /dev/null
+++ b/README.md
@@ -0,0 +1,75 @@
+# extregs.nvim
+
+Useful extended registers for a Neovim build with `has('extregs')`.
+
+## Install
+
+Add the repo to `vim.pack.add({...})`. The plugin automatically calls `setup()`.
+For options, instead call `require('extregs').setup({...})` from an earlier startup
+config file (before Neovim loads `plugin/` runtime files):
+
+```lua
+require('extregs').setup({
+  file = { path = '/var/run/user/' .. vim.env.USER .. '/nvim.regfile' },
+  ssh = { host = 'rahm@photon', path = '~/.local/state/nvim/regfile' },
+  tmux = { buffer = nil }, -- nil: most recent paste buffer
+  timestamp = { format = '%Y-%m-%dT%H:%M:%S%z' },
+})
+```
+
+The plugin registers `osc52`, `tmux`, `buffer`, `file.basename`, `file.stem`,
+`file.dirname`, `file.backed`, `ssh.backed`, `timestamp`, and `uuid`.
+For extreg syntax use your Neovim patch's `~name` register notation.
+
+### tmux paste buffer
+
+`~tmux` reads and writes tmux's current paste buffer. A write runs
+`tmux load-buffer -` and a read runs `tmux show-buffer`.
+Set `tmux = { buffer = 'nvim' }` to use a named tmux buffer instead.
+The content is ordinary text so it can be pasted with tmux's normal paste
+binding; no JSON cookie is written. Reading follows the same plaintext rule
+as backed-register reads: one line is characterwise, multiple lines linewise.
+Writing a linewise register appends a newline. tmux must be accessible from
+Neovim (`TMUX` or a compatible tmux environment).
+
+### Backed-register format
+
+A structured write produces:
+
+```
+NVIM_EXTREGS_JSON_V1
+{"lines":["hello"],"type":"v"}
+```
+
+A read without that first-line magic cookie treats the whole file as plain
+text: one line → characterwise (`v`); multiple lines → linewise (`V`).
+
+### Limitations
+
+- The source buffer is replaced in memory by `buffer` writes; saving it is separate.
+- OSC 52 clipboard reads are terminal-dependent and may time out or fail.
+- SSH calls are synchronous, and `ssh.backed` requires passwordless SSH.
+- Filename registers are read-only in this initial implementation (as are timestamp/uuid).
+- Register callbacks rely on a custom, unreleased Neovim API; validate against your
+  exact extregs branch before using this in production.
+- Missing `has('extregs')` yields a scheduled error notification (not a blocking
+  error prompt), and registration is skipped.
+
+### Provider architecture
+
+Every register has a dedicated module under `lua/extregs/`. Each module exposes
+`get_provider(cfg)` and returns a provider object with `read()` and `write(reg)`
+methods. The initializer alone owns registration, error notifications, and the
+`has('extregs')` guard. To add a register, create a provider module and add one
+entry to the `providers` table in `lua/extregs/init.lua`.
+
+```lua
+local provider = require('extregs.tmux').get_provider(cfg.tmux)
+-- The initializer wraps these with error handling and registers them:
+vim._extregs.register('tmux',
+  function(reg) return provider:write(reg) end,
+  function() return provider:read() end)
+```
+
+The original yank and put callback argument ordering is preserved. The
+shared `storage.lua` serializer is used by both file-backed providers.