chore(doc): auto generate docs

Author: github-actions[bot]

doc/CopilotChat.txt

@@ -41,7 +41,7 @@ CopilotChat.nvim brings GitHub Copilot Chat capabilities directly into Neovim
 with a focus on transparency and user control.
 
 - 🤖 **Multiple AI Models** - GitHub Copilot (including GPT-4o, Gemini 2.5 Pro, Claude 4 Sonnet, Claude 3.7 Sonnet, Claude 3.5 Sonnet, o3-mini, o4-mini) + custom providers (Ollama, Mistral.ai). The exact list of available models depends on your GitHub Copilot settings <https://github.com/settings/copilot/features> and the models provided by GitHub’s API.
-- 🔧 **Tool Calling** - LLM can call workspace functions (file reading, git operations, search) with your explicit approval
+- 🔧 **Tool Calling** - LLM can call workspace functions (file reading, git operations, search) with manual approval or automatic execution for trusted tools
 - 🔒 **Privacy First** - Only shares what you explicitly request - no background data collection
 - 📝 **Interactive Chat** - Interactive UI with completion, diffs, and quickfix integration
 - 🎯 **Smart Prompts** - Composable templates and sticky prompts for consistent context
@@ -126,7 +126,7 @@ VIM-PLUG                                                *CopilotChat-vim-plug*
 2. Core Concepts                                   *CopilotChat-core-concepts*
 
 - **Resources** (`#<name>`) - Add specific content (files, git diffs, URLs) to your prompt
-- **Tools** (`@<name>`) - Give LLM access to functions it can call with your approval
+- **Tools** (`@<name>`) - Give LLM access to functions it can call during the chat, with manual approval by default
 - **Sticky Prompts** (`> <text>`) - Persist context across single chat session
 - **Models** (`$<model>`) - Specify which AI model to use for the chat
 - **Prompts** (`/PromptName`) - Use predefined prompt templates for common tasks
@@ -149,10 +149,17 @@ EXAMPLES                                                *CopilotChat-examples*
     > You are a helpful coding assistant
 <
 
-When you use `@copilot`, the LLM can call functions like `bash`, `edit`,
-`file`, `glob`, `grep`, `gitdiff` etc. You’ll see the proposed function call
-and can approve/reject it before execution.
+When you use `@copilot`, the LLM can call functions from the `copilot` group
+such as `bash`, `edit`, `file`, `glob`, `grep`, and `gitdiff`.
 
+- By default, proposed tool calls wait for your approval.
+- You can configure `trusted_tools` to automatically run specific tools or groups.
+- Resources added with `#...` are resolved immediately and shared as context.
+- Tool call results are sent back to the model as plain output, while manual resources keep their `##<uri>` references in chat.
+
+
+  [!WARNING] `trusted_tools = true` allows the model to run every enabled tool
+  without asking. Only use it if you fully trust the tool set and workspace.
 
 ==============================================================================
 3. Usage                                                   *CopilotChat-usage*
@@ -177,16 +184,15 @@ COMMANDS                                                *CopilotChat-commands*
 CHAT KEY MAPPINGS                              *CopilotChat-chat-key-mappings*
 
   Insert   Normal   Action
-  -------- -------- --------------------------------------------
+  -------- -------- -------------------------------------------
   <Tab>    -        Trigger/accept completion menu for tokens
   <C-c>    q        Close the chat window
   <C-l>    <C-l>    Reset and clear the chat window
   <C-s>    <CR>     Submit the current prompt
-  -        grr      Toggle sticky prompt for line under cursor
   <C-y>    <C-y>    Accept nearest diff
   -        gj       Jump to section of nearest diff
-  -        gqa      Add all answers from chat to quickfix list
-  -        gqd      Add all diffs from chat to quickfix list
+  -        gqa      Add all answers from chat to quickfix
+  -        gqd      Add all diffs from chat to quickfix
   -        gy       Yank nearest diff to register
   -        gd       Show diff between source and nearest diff
   -        gc       Show info about current chat
@@ -205,39 +211,44 @@ PREDEFINED FUNCTIONS                        *CopilotChat-predefined-functions*
 
 All predefined functions belong to the `copilot` group.
 
-  -------------------------------------------------------------------------------------
-  Function    Type       Description                               Example Usage
-  ----------- ---------- ----------------------------------------- --------------------
-  bash        Tool       Executes a bash command and returns       @copilot only
-                         output                                    
+  ----------------------------------------------------------------------------------
+  Function    Manual    Description                             Example Usage
+              #...                                              
+  ----------- --------- --------------------------------------- --------------------
+  bash        No        Executes a bash command and returns     @copilot
+                        output                                  
 
-  buffer      Resource   Retrieves content from buffer(s) with     #buffer:active
-                         diagnostics                               
+  buffer      Yes       Retrieves content from buffer(s) with   #buffer:active
+                        diagnostics                             
 
-  clipboard   Resource   Provides access to system clipboard       #clipboard
-                         content                                   
+  clipboard   Yes       Provides access to system clipboard     #clipboard
+                        content                                 
 
-  edit        Tool       Applies a unified diff to a file          @copilot only
+  edit        No        Applies a unified diff to a file        @copilot
 
-  file        Resource   Reads content from a specified file path  #file:path/to/file
+  file        Yes       Reads content from a specified file     #file:path/to/file
+                        path                                    
 
-  gitdiff     Resource   Retrieves git diff information            #gitdiff:staged
+  gitdiff     Yes       Retrieves git diff information          #gitdiff:staged
 
-  glob        Resource   Lists filenames matching a pattern in     #glob:**/*.lua
-                         workspace                                 
+  glob        Yes       Lists filenames matching a pattern in   #glob:**/*.lua
+                        workspace                               
 
-  grep        Resource   Searches for a pattern across files in    #grep:TODO
-                         workspace                                 
+  grep        Yes       Searches for a pattern across files in  #grep:TODO
+                        workspace                               
 
-  selection   Resource   Includes the current visual selection     #selection
-                         with diagnostics                          
+  selection   Yes       Includes the current visual selection   #selection
+                        with diagnostics                        
 
-  url         Resource   Fetches content from a specified URL      #url:https://...
-  -------------------------------------------------------------------------------------
-**Type Legend:**
+  url         Yes       Fetches content from a specified URL    #url:https://...
+  ----------------------------------------------------------------------------------
+`#...` resolves a function immediately and adds its output as chat context.
 
-- **Resource**: Can be used manually via `#function` syntax
-- **Tool**: Can only be called by LLM via `@copilot` (for safety/complexity reasons)
+`@copilot` shares the enabled functions with the model so it can choose when to
+call them.
+
+Only `bash` and `edit` are tool-only. The rest can be used both as manual
+resources and as callable tools.
 
 
 PREDEFINED PROMPTS                            *CopilotChat-predefined-prompts*
@@ -276,6 +287,7 @@ Most users only need to configure a few options:
     {
       model = 'gpt-4.1',           -- AI model to use
       temperature = 0.1,           -- Lower = focused, higher = creative
+      trusted_tools = nil,         -- Require approval for all tool calls
       window = {
         layout = 'vertical',       -- 'vertical', 'horizontal', 'float'
         width = 0.5,              -- 50% of screen width
@@ -309,13 +321,15 @@ WINDOW & APPEARANCE                          *CopilotChat-window-&-appearance*
     }
 <
 
+`window.layout` also supports `'replace'` to reuse the current window.
+
 
 BUFFER BEHAVIOR                                  *CopilotChat-buffer-behavior*
 
 >lua
     -- Auto-command to customize chat buffer behavior
     vim.api.nvim_create_autocmd('BufEnter', {
-      pattern = 'copilot-*',
+      pattern = 'copilot-chat',
       callback = function()
         vim.opt_local.relativenumber = false
         vim.opt_local.number = false
@@ -348,6 +362,7 @@ Types of copilot highlights:
 - `CopilotChatModel` - Model highlight in chat buffer (e.g. `$gpt-4.1`)
 - `CopilotChatUri` - URI highlight in chat buffer (e.g. `##https://...`)
 - `CopilotChatAnnotation` - Annotation highlight in chat buffer (file headers, tool call headers, tool call body)
+- `CopilotChatAnnotationHeader` - Annotation header highlight in chat buffer
 
 
 PROMPTS                                                  *CopilotChat-prompts*
@@ -376,14 +391,45 @@ Define your own prompts in the configuration:
 
 FUNCTIONS                                              *CopilotChat-functions*
 
+Use `trusted_tools` to control which tool calls are executed automatically:
+
+>lua
+    {
+      trusted_tools = nil, -- default: require approval for all tool calls
+    
+      -- trust all functions in a group
+      -- trusted_tools = 'copilot',
+    
+      -- trust specific functions by name or groups by name
+      -- trusted_tools = { 'file', 'glob', 'grep' },
+    
+      -- trust every enabled tool call
+      -- trusted_tools = true,
+    }
+<
+
+A tool is trusted when any of these match:
+
+- Its function definition sets `trusted = true`
+- Its function name appears in `trusted_tools`
+- Its function group appears in `trusted_tools`
+- `trusted_tools = true`
+
+For most setups, trusting a few read-only functions such as `file`, `glob`, or
+`grep` is safer than trusting everything.
+
+
+  [!WARNING] Trusted tools run without asking for confirmation. Be especially
+  careful with tools like `bash` and `edit`, which can change your workspace.
 Define your own functions in the configuration with input handling and schema:
 
 >lua
     {
       functions = {
         birthday = {
-          description = "Retrieves birthday information for a person",
-          uri = "birthday://{name}",
+          description = 'Retrieves birthday information for a person',
+          uri = 'birthday://{name}',
+          trusted = false,
           schema = {
             type = 'object',
             required = { 'name' },
@@ -401,14 +447,17 @@ Define your own functions in the configuration with input handling and schema:
                 uri = 'birthday://' .. input.name,
                 mimetype = 'text/plain',
                 data = input.name .. ' birthday info',
-              }
+              },
             }
-          end
-        }
+          end,
+        },
       }
     }
 <
 
+If a function has a `uri`, it can be used manually with `#birthday:Alice`.
+Functions without a `uri` are tool-only and can only be called by the model.
+
 
 PROVIDERS                                              *CopilotChat-providers*
 
@@ -418,9 +467,9 @@ Add custom AI providers:
     {
       providers = {
         my_provider = {
-          get_url = function(opts) return "https://api.example.com/chat" end,
-          get_headers = function() return { ["Authorization"] = "Bearer " .. api_key } end,
-          get_models = function() return { { id = "gpt-4.1", name = "GPT-4.1 model" } } end,
+          get_url = function(opts) return 'https://api.example.com/chat' end,
+          get_headers = function() return { ['Authorization'] = 'Bearer ' .. api_key } end,
+          get_models = function() return { { id = 'gpt-4.1', name = 'GPT-4.1 model' } } end,
           prepare_input = require('CopilotChat.config.providers').copilot.prepare_input,
           prepare_output = require('CopilotChat.config.providers').copilot.prepare_output,
         }
@@ -436,7 +485,7 @@ Add custom AI providers:
       disabled?: boolean,
 
       -- Optional: Extra info about the provider displayed in info panel
-      get_info?(): string[]
+      get_info?(headers: table): string[]
 
       -- Optional: Get extra request headers with optional expiration time
       get_headers?(): table<string,string>, number?,
@@ -452,13 +501,16 @@ Add custom AI providers:
 
       -- Optional: Get available models
       get_models?(headers: table): table<CopilotChat.Provider.model>,
+    
+      -- Optional: Resolve a user-facing model id to a provider model id
+      resolve_model?(headers: table, model: string): string,
     }
 <
 
 **Built-in providers:**
 
 - `copilot` - GitHub Copilot (default)
-- `github_models` - GitHub Marketplace models (disabled by default)
+- `github_models` - GitHub Models (disabled by default)
 
 
 ==============================================================================
@@ -468,7 +520,7 @@ Add custom AI providers:
 CORE                                                        *CopilotChat-core*
 
 >lua
-    local chat = require("CopilotChat")
+    local chat = require('CopilotChat')
 
     -- Basic Chat Functions
     chat.ask(prompt, config)      -- Ask a question with optional config
@@ -499,7 +551,7 @@ CHAT WINDOW                                          *CopilotChat-chat-window*
 You can also access the chat window UI methods through the `chat.chat` object:
 
 >lua
-    local window = require("CopilotChat").chat
+    local window = require('CopilotChat').chat
 
     -- Chat UI State
     window:visible()             -- Check if chat window is visible
@@ -518,8 +570,8 @@ You can also access the chat window UI methods through the `chat.chat` object:
     window:finish()              -- Finish writing to chat window
 
     -- Source Management
-    window.get_source()          -- Get the current source buffer and window
-    window.set_source(winnr)     -- Set the source window
+    window:get_source()          -- Get the current source buffer and window
+    window:set_source(winnr)     -- Set the source window
 
     -- Navigation
     window:follow()              -- Move cursor to end of chat content
@@ -533,10 +585,11 @@ You can also access the chat window UI methods through the `chat.chat` object:
 PROMPT PARSER                                      *CopilotChat-prompt-parser*
 
 >lua
-    local parser = require("CopilotChat.prompts")
+    local parser = require('CopilotChat.prompts')
 
     parser.resolve_prompt()         -- Resolve prompt references
-    parser.resolve_tools()          -- Resolve tools that are available for automatic use by LLM
+    parser.resolve_tools()          -- Resolve tools shared with the model via @...
+    parser.resolve_functions()      -- Resolve manual function/resource references via #...
     parser.resolve_model()          -- Resolve model from prompt (WARN: async, requires plenary.async.run)
 <
 
@@ -545,22 +598,26 @@ EXAMPLE USAGE                                      *CopilotChat-example-usage*
 
 >lua
     -- Open chat, ask a question and handle response
-    require("CopilotChat").open()
-    require("CopilotChat").ask("#buffer Explain this code", {
+    require('CopilotChat').open()
+    require('CopilotChat').ask('#buffer Explain this code', {
       callback = function(response)
-        vim.notify("Got response: " .. response:sub(1, 50) .. "...")
-        return response
+        vim.notify('Got response: ' .. vim.trim(response.content):sub(1, 50) .. '...')
       end,
     })
 
     -- Save and load chat history
-    require("CopilotChat").save("my_debugging_session")
-    require("CopilotChat").load("my_debugging_session")
+    require('CopilotChat').save('my_debugging_session')
+    require('CopilotChat').load('my_debugging_session')
 
     -- Use custom sticky and model
-    require("CopilotChat").ask("How can I optimize this?", {
-      model = "gpt-4.1",
-      sticky = {"#buffer", "#gitdiff:staged"}
+    require('CopilotChat').ask('How can I optimize this?', {
+      model = 'gpt-4.1',
+      sticky = { '#buffer', '#gitdiff:staged' },
+    })
+    
+    -- Automatically trust a small read-only tool set
+    require('CopilotChat').setup({
+      trusted_tools = { 'file', 'glob', 'grep' },
     })
 <
 
@@ -595,6 +652,12 @@ To run tests:
     make test
 <
 
+To run the same formatting check as CI:
+
+>bash
+    stylua --check .
+<
+
 
 CONTRIBUTING                                        *CopilotChat-contributing*