roles docu

2 files changed, 47 insertions, 1 deletions

diff --git a/README.md b/README.md
index 18ac762..a241551 100644
--- a/README.md
+++ b/README.md
@@ -12,6 +12,7 @@ To get an idea what is possible to do with AI commands see the [prompts](https:/
 - Generate text or code, answer questions with AI
 - Edit selected text in-place with AI
 - Interactive conversation with ChatGPT
+- Supports custom roles and more
 
 ## How it works
 
@@ -89,13 +90,15 @@ To use an AI command, type the command followed by an instruction prompt. You ca
 
 **Tip:** Setup your own [key bindings](#key-bindings) or use command shortcuts - `:AIE`, `:AIC`, `:AIR`
 
+**Tip:** A [custom role](#role) {role} can be passed to the above commands by an initial parameter /{role}, for example `:AIEdit /grammar`.
+
 **Tip:** Combine commands with a range `:help range`, for example to select the whole buffer - `:%AIE fix grammar`
 
 If you are interested in more tips or would like to level up your Vim with more commands like [`:GitCommitMessage`](https://github.com/madox2/vim-ai/wiki/Custom-commands#suggest-a-git-commit-message) - suggesting a git commit message, visit the [Community Wiki](https://github.com/madox2/vim-ai/wiki).
 
 ## Reference
 
-In the documentation below,  `<selection>` denotes a visual selection or any other range, `{instruction}` an instruction prompt and `?` symbol an optional parameter.
+In the documentation below,  `<selection>` denotes a visual selection or any other range, `{instruction}` an instruction prompt, `{role}` a [custom role](#roles) and `?` symbol an optional parameter.
 
 ### `:AI`
 
@@ -107,18 +110,24 @@ In the documentation below,  `<selection>` denotes a visual selection or any oth
 
 `<selection> :AI {instruction}` - complete the selection using the instruction
 
+`<selection>? :AI /{role} {instruction}?` - use role to complete
+
 ### `:AIEdit`
 
 `<selection>? :AIEdit` - edit the current line or the selection
 
 `<selection>? :AIEdit {instruction}` - edit the current line or the selection using the instruction
 
+`<selection>? :AIEdit /{role} {instruction}?` - use role to edit
+
 ### `:AIChat`
 
 `:AIChat` - continue or start a new conversation.
 
 `<selection>? :AIChat {instruction}?` - start a new conversation given the selection, the instruction or both
 
+`<selection>? :AIChat /{role} {instruction}?` - use role to complete
+
 When the AI finishes answering, you can continue the conversation by entering insert mode, adding your prompt, and then using the command `:AIChat` once again.
 
 #### `.aichat` files
@@ -171,6 +180,27 @@ As a parameter you put an open chat command preset shortcut - `below`, `tab` or
 Use this immediately after `AI`/`AIEdit`/`AIChat` command in order to re-try or get an alternative completion.
 Note that the randomness of responses heavily depends on the [`temperature`](https://platform.openai.com/docs/api-reference/completions/create#completions/create-temperature) parameter.
 
+## Roles
+
+In the context of this plugin, a role means a re-usable AI instruction and/or configuration. Roles are defined in the configuration `.ini` file. For example by defining a `grammar` role:
+
+```vim
+let g:vim_ai_roles_config_file = '/path/to/my/roles.ini'
+```
+
+```ini
+# /path/to/my/roles.ini
+
+[grammar]
+prompt = fix spelling and grammar
+
+[grammar.options]
+temperature = 0.4
+```
+
+Now you can select text and run it with command `:AIEdit /grammar`.
+
+See [roles-example.ini](./roles-example.ini) for more examples.
 
 ## Key bindings
 
diff --git a/doc/vim-ai.txt b/doc/vim-ai.txt
index 72535b3..5d06fc7 100644
--- a/doc/vim-ai.txt
+++ b/doc/vim-ai.txt
@@ -161,6 +161,22 @@ You can also customize the options in the chat header: >
   generate a paragraph of lorem ipsum
   ...
 
+ROLES
+
+Roles are defined in the `.ini` file: >
+
+    let g:vim_ai_roles_config_file = '/path/to/my/roles.ini'
+
+Example of a role: >
+
+    [grammar]
+    prompt = fix spelling and grammar
+
+    [grammar.options]
+    temperature = 0.4
+
+See roles-example.ini for more examples.
+
 KEY BINDINGS
 
 Examples how configure key bindings and customize commands: >