docs: clarify get_current_dir nil return and add telescope recipe

Problem: get_current_dir returns nil in several cases that were not
documented, causing confusion when used in keymaps that open pickers
like Telescope (#682). Also, posix_to_os_path could crash on Windows
when no drive letter is found.

Solution: expand get_current_dir docs to explain nil return cases, add
a Telescope recipe with nil guards, and add a defensive nil check in
posix_to_os_path.

Cherry-picked from: stevearc/oil.nvim#727

doc/oil.txt

@@ -301,7 +301,36 @@ toggle_hidden()                                                *oil.toggle_hidde
 
 
 get_current_dir({bufnr}): nil|string                         *oil.get_current_dir*
-    Get the current directory
+    Get the current directory for the given oil buffer. Returns the directory
+    path as a string, or nil in the following cases:
+    - The buffer is not an oil buffer
+    - The buffer uses a non-files adapter (ssh, s3, trash)
+    - The current buffer changed (e.g. after opening a Telescope picker)
+
+    When calling this function inside a keymap that also opens another
+    plugin's window (e.g. Telescope), capture the directory BEFORE the
+    call that changes the buffer context:
+>lua
+        ["<leader>ff"] = {
+            function()
+                local dir = require("oil").get_current_dir()
+                if dir then
+                    require("telescope.builtin").find_files({ cwd = dir })
+                end
+            end,
+            mode = "n",
+            nowait = true,
+            desc = "Find files in the current directory"
+        },
+<
+
+    You can also pass a specific buffer number to avoid depending on the
+    current buffer:
+>lua
+        local bufnr = vim.api.nvim_get_current_buf()
+        -- ... operations that may change the current buffer ...
+        local dir = require("oil").get_current_dir(bufnr)
+<
 
     Parameters:
       {bufnr} `nil|integer`
@@ -519,9 +548,10 @@ The `keymaps` option in `oil.setup` allow you to create mappings using all the s
         -- a table with the mapping as the first element.
         ["<leader>ff"] = {
             function()
-                require("telescope.builtin").find_files({
-                    cwd = require("oil").get_current_dir()
-                })
+                local dir = require("oil").get_current_dir()
+                if dir then
+                    require("telescope.builtin").find_files({ cwd = dir })
+                end
             end,
             mode = "n",
             nowait = true,