feat: emit OilReadPost user event after each buffer render

Problem: third-party plugins like oil-git-status.nvim had no way to
know when an oil buffer was re-rendered after a filesystem change,
causing their decorations to be cleared with no signal to refresh.

Solution: emit a User OilReadPost autocmd after every successful
render_buffer_async call. Also document all oil user events
(OilEnter, OilReadPost, OilMutationComplete) in oil.txt since none
were previously documented.

Cherry-picked from: stevearc#723

Author: barrettruth

doc/oil.txt

@@ -777,6 +777,45 @@ OilTrash                                                             *hl-OilTras
 OilTrashSourcePath                                         *hl-OilTrashSourcePath*
     Virtual text that shows the original path of file in the trash
 
+--------------------------------------------------------------------------------
+EVENTS                                                                *oil-events*
+
+Oil emits the following User autocmd events:
+
+OilEnter                                                             *OilEnter*
+    Fired once when an oil buffer finishes its initial render and is ready for
+    interaction. The autocmd `data` table contains `{ buf = <bufnr> }`.
+
+    Example: >lua
+        vim.api.nvim_create_autocmd("User", {
+            pattern = "OilEnter",
+            callback = function(args)
+                -- args.data.buf is the oil buffer number
+            end,
+        })
+<
+
+OilReadPost                                                         *OilReadPost*
+    Fired after every successful render of an oil buffer, including re-renders
+    triggered by filesystem changes or manual refresh. This fires in addition
+    to OilEnter on the initial render.
+
+    Useful for third-party plugins that need to update decorations (e.g., git
+    status columns) whenever the buffer contents change.
+
+    Example: >lua
+        vim.api.nvim_create_autocmd("User", {
+            pattern = "OilReadPost",
+            callback = function(args)
+                -- args.data.buf is the oil buffer number
+            end,
+        })
+<
+
+OilMutationComplete                                         *OilMutationComplete*
+    Fired after a mutation (file create, delete, rename, move, copy) finishes
+    executing.
+
 --------------------------------------------------------------------------------
 TRASH                                                                  *oil-trash*
 

lua/oil/view.lua

@@ -867,7 +867,19 @@ local pending_renders = {}
 ---@param opts nil|table
 ---    refetch nil|boolean Defaults to true
 ---@param callback nil|fun(err: nil|string)
-M.render_buffer_async = function(bufnr, opts, callback)
+M.render_buffer_async = function(bufnr, opts, caller_callback)
+  local function callback(err)
+    if not err then
+      vim.api.nvim_exec_autocmds(
+        "User",
+        { pattern = "OilReadPost", modeline = false, data = { buf = bufnr } }
+      )
+    end
+    if caller_callback then
+      caller_callback(err)
+    end
+  end
+
   opts = vim.tbl_deep_extend("keep", opts or {}, {
     refetch = true,
   })