docs: improve terminal focus documentation and clarify behavior

- Update build_opts() documentation to explain focus parameter behavior
- Add comprehensive comments explaining window restoration logic in native provider
- Clarify that focus=false preserves user context in all terminal scenarios:
  - Existing terminal: stays in current window
  - Recovered terminal: stays in current window
  - New terminal: returns to original window
- Improve maintainer understanding of focus control architecture

Addresses Copilot feedback about documentation and behavior clarity.

Change-Id: I06e785d5e2378b68fce41eb64018067d2754225d
Signed-off-by: Thomas Kosiewski <[email protected]>

Author: ThomasK33

lua/claudecode/terminal/native.lua

@@ -51,9 +51,11 @@ local function open_terminal(cmd_string, env_table, effective_config, focus)
 
   if is_valid() then -- Should not happen if called correctly, but as a safeguard
     if focus then
+      -- Focus existing terminal: switch to terminal window and enter insert mode
       vim.api.nvim_set_current_win(winid)
       vim.cmd("startinsert")
     end
+    -- If focus=false, preserve user context by staying in current window
     return true
   end
 
@@ -127,10 +129,11 @@ local function open_terminal(cmd_string, env_table, effective_config, focus)
   -- buftype=terminal is set by termopen
 
   if focus then
+    -- Focus the terminal: switch to terminal window and enter insert mode
     vim.api.nvim_set_current_win(winid)
     vim.cmd("startinsert")
   else
-    -- Return to original window if not focusing
+    -- Preserve user context: return to the window they were in before terminal creation
     vim.api.nvim_set_current_win(original_win)
   end
 
@@ -279,8 +282,9 @@ function M.open(cmd_string, env_table, effective_config, focus)
       -- Note: We can't recover the job ID easily, but it's less critical
       logger.debug("terminal", "Recovered existing Claude terminal")
       if focus then
-        focus_terminal()
+        focus_terminal() -- Focus recovered terminal
       end
+      -- If focus=false, preserve user context by staying in current window
     else
       if not open_terminal(cmd_string, env_table, effective_config, focus) then
         vim.notify("Failed to open Claude terminal using native fallback.", vim.log.levels.ERROR)

lua/claudecode/terminal/snacks.lua

@@ -42,10 +42,11 @@ local function setup_terminal_events(term_instance, config)
   end, { buf = true })
 end
 
---- @param config table
---- @param env_table table
---- @param focus boolean|nil
---- @return table
+--- Builds Snacks terminal options with focus control
+--- @param config table Terminal configuration (split_side, split_width_percentage, etc.)
+--- @param env_table table Environment variables to set for the terminal process
+--- @param focus boolean|nil Whether to focus the terminal when opened (defaults to true)
+--- @return table Snacks terminal options with start_insert/auto_insert controlled by focus parameter
 local function build_opts(config, env_table, focus)
   focus = utils.normalize_focus(focus)
   return {