ef", function()
- vim.cmd("EcaAddFile " .. vim.fn.expand("%"))
-end)
-```
-
-## ๐ค Development and Contribution
-
-### ๐ Support
-
-- **Issues**: [GitHub Issues](https://github.com/editor-code-assistant/eca-nvim/issues)
-- **Discussions**: [GitHub Discussions](https://github.com/editor-code-assistant/eca-nvim/discussions)
-- **Wiki**: [GitHub Wiki](https://github.com/editor-code-assistant/eca-nvim/wiki)
-
-### ๐ง Local Development
-
-1. **Clone the repository**:
- ```bash
- git clone https://github.com/editor-code-assistant/eca-nvim.git
- ```
-
-2. **Configure local path**:
- ```lua
- require("eca").setup({
- debug = true,
- -- Point to your local clone
- -- server_path = "/path/to/eca-binary",
- })
- ```
-
-3. **Test changes**:
- ```vim
- :luafile %
- :EcaServerRestart
- ```
-
-### ๐ฏ Contributing
-
-1. **Fork** the repository
-2. **Create branch** for your feature: `git checkout -b feature/new-functionality`
-3. **Commit** your changes: `git commit -m 'Add new functionality'`
-4. **Push** to branch: `git push origin feature/new-functionality`
-5. **Open Pull Request**
-
-### ๐งช Testing
-
-Run tests before submitting PR:
-
-```bash
-# Unit tests
-nvim --headless -c "lua require('eca.tests').run_all()"
-
-# Manual test
-nvim -c "lua require('eca').setup({debug=true})"
-```
+## ๐ Useful Links
+- Official ECA Website: https://eca.dev/
+- ECA Documentation: https://docs.eca.dev/
+- VS Code Plugin: https://marketplace.visualstudio.com/items?itemName=editor-code-assistant.eca-vscode
+- ECA GitHub: https://github.com/editor-code-assistant
## ๐ License
-
-**MIT License** - see [LICENSE](LICENSE) for details.
+MIT License โ see [LICENSE](LICENSE) for details.
## ๐ Acknowledgments
-
-This plugin was inspired and based on the work of:
-
-- **[avante.nvim](https://github.com/yetone/avante.nvim)** - Base structure and UI concepts
-- **[eca-vscode](https://github.com/editor-code-assistant/eca-vscode)** - ECA server integration
-- **Neovim Community** - For all the tools and inspiration
-
-## ๐ Useful Links
-
-- **[Official ECA Website](https://eca.dev/)**
-- **[ECA Documentation](https://docs.eca.dev/)**
-- **[VS Code Plugin](https://marketplace.visualstudio.com/items?itemName=editor-code-assistant.eca-vscode)**
-- **[ECA GitHub](https://github.com/editor-code-assistant)**
+Inspired by:
+- avante.nvim โ base structure and UI concepts
+- eca-vscode โ ECA server integration
+- The Neovim community
---
-**โจ Made with โค๏ธ for the Neovim community โจ**
+โจ Made with โค๏ธ for the Neovim community โจ
[โญ Give a star if this plugin was useful!](https://github.com/editor-code-assistant/eca-nvim)
diff --git a/docs/configuration.md b/docs/configuration.md
new file mode 100644
index 0000000..b9be743
--- /dev/null
+++ b/docs/configuration.md
@@ -0,0 +1,153 @@
+# Configuration
+
+ECA is highly configurable. This page lists all available options and provides common presets.
+
+## Full configuration reference
+
+```lua
+require("eca").setup({
+ -- === BASIC SETTINGS ===
+
+ -- Enable debug mode (shows detailed logs)
+ debug = false,
+
+ -- Path to ECA binary (empty = automatic download)
+ server_path = "",
+
+ -- Extra arguments for ECA server
+ server_args = "--log-level info",
+
+ -- Usage string format (tokens/cost)
+ usage_string_format = "{messageCost} / {sessionCost}",
+
+ -- === BEHAVIOR ===
+ behaviour = {
+ -- Set keymaps automatically
+ auto_set_keymaps = true,
+
+ -- Focus sidebar automatically when opening
+ auto_focus_sidebar = true,
+
+ -- Start server automatically
+ auto_start_server = true,
+
+ -- Download server automatically if not found
+ auto_download = true,
+
+ -- Show status updates in notifications
+ show_status_updates = true,
+ },
+
+ -- === KEY MAPPINGS ===
+ mappings = {
+ chat = "ec", -- Open chat
+ focus = "ef", -- Focus sidebar
+ toggle = "et", -- Toggle sidebar
+ },
+
+ -- === WINDOW SETTINGS ===
+ windows = {
+ -- Automatic line wrapping
+ wrap = true,
+
+ -- Width as percentage of screen (1-100)
+ width = 40,
+
+ -- Sidebar header configuration
+ sidebar_header = {
+ enabled = true,
+ align = "center", -- "left", "center", "right"
+ rounded = true,
+ },
+
+ -- Input area configuration
+ input = {
+ prefix = "> ", -- Input line prefix
+ height = 8, -- Input window height
+ },
+
+ -- Edit window configuration
+ edit = {
+ border = "rounded", -- "none", "single", "double", "rounded"
+ start_insert = true, -- Start in insert mode
+ },
+
+ -- Ask window configuration
+ ask = {
+ floating = false, -- Use floating window
+ start_insert = true, -- Start in insert mode
+ border = "rounded",
+ focus_on_apply = "ours", -- "ours" or "theirs"
+ },
+ },
+
+ -- === HIGHLIGHTS AND COLORS ===
+ highlights = {
+ diff = {
+ current = "DiffText", -- Highlight for current diff
+ incoming = "DiffAdd", -- Highlight for incoming diff
+ },
+ },
+})
+```
+
+---
+
+## Presets
+
+### Minimalist
+```lua
+require("eca").setup({
+ behaviour = { show_status_updates = false },
+ windows = { width = 30 },
+})
+```
+
+### Visual/UX focused
+```lua
+require("eca").setup({
+ behaviour = { auto_focus_sidebar = true },
+ windows = {
+ width = 50,
+ wrap = true,
+ sidebar_header = { enabled = true, rounded = true },
+ input = { prefix = "๐ฌ ", height = 10 },
+ },
+})
+```
+
+### Development
+```lua
+require("eca").setup({
+ debug = true,
+ server_args = "--log-level debug",
+ behaviour = {
+ auto_start_server = true,
+ show_status_updates = true,
+ },
+ mappings = {
+ chat = "",
+ toggle = "",
+ focus = "",
+ },
+})
+```
+
+### Performance-oriented
+```lua
+require("eca").setup({
+ behaviour = {
+ auto_focus_sidebar = false,
+ show_status_updates = false,
+ },
+ windows = { width = 25 },
+})
+```
+
+---
+
+## Notes
+- Set `server_path` if you prefer using a local ECA binary.
+- For noisy environments, disable `show_status_updates`.
+- Adjust `windows.width` to fit your layout.
+- Keymaps can be set manually by turning off `auto_set_keymaps`.
diff --git a/docs/development.md b/docs/development.md
new file mode 100644
index 0000000..0813acd
--- /dev/null
+++ b/docs/development.md
@@ -0,0 +1,47 @@
+# Development and Contribution
+
+## Support
+- Issues: https://github.com/editor-code-assistant/eca-nvim/issues
+- Discussions: https://github.com/editor-code-assistant/eca-nvim/discussions
+- Wiki: https://github.com/editor-code-assistant/eca-nvim/wiki
+
+## Local development
+
+1. Clone the repository
+ ```bash
+ git clone https://github.com/editor-code-assistant/eca-nvim.git
+ ```
+
+2. Configure local path (optional)
+ ```lua
+ require("eca").setup({
+ debug = true,
+ -- server_path = "/path/to/eca-binary",
+ })
+ ```
+
+3. Test changes
+ ```vim
+ :luafile %
+ :EcaServerRestart
+ ```
+
+## Contributing
+
+1. Fork the repository
+2. Create a branch: `git checkout -b feature/new-functionality`
+3. Commit your changes: `git commit -m 'Add new functionality'`
+4. Push to your branch: `git push origin feature/new-functionality`
+5. Open a Pull Request
+
+## Testing
+
+Run tests before submitting a PR:
+
+```bash
+# Unit tests
+nvim --headless -c "lua require('eca.tests').run_all()"
+
+# Manual test
+nvim -c "lua require('eca').setup({debug=true})"
+```
diff --git a/docs/installation.md b/docs/installation.md
new file mode 100644
index 0000000..c5df383
--- /dev/null
+++ b/docs/installation.md
@@ -0,0 +1,156 @@
+# Installation
+
+This guide covers system requirements and how to install the ECA Neovim plugin with popular plugin managers.
+
+## System Requirements
+
+### Required
+- Neovim >= 0.8.0 (Recommended: >= 0.9.0)
+- curl (for automatic server download)
+- unzip (for server extraction)
+- Internet connection (for initial download and ECA functionality)
+
+### Optional
+- plenary.nvim โ Utility functions used by some distributions
+
+### Tested Systems
+- macOS (Intel and Apple Silicon)
+- Linux (Ubuntu, Arch, Fedora, etc.)
+- Windows (WSL2 recommended)
+- FreeBSD
+
+---
+
+## Install with popular plugin managers
+
+### lazy.nvim (recommended)
+
+```lua
+{
+ "editor-code-assistant/eca-nvim",
+ dependencies = {
+ "MunifTanjim/nui.nvim", -- Required: UI framework
+ "nvim-lua/plenary.nvim", -- Optional: Enhanced async operations
+ },
+ opts = {}
+}
+```
+
+Advanced setup example:
+
+```lua
+{
+ "editor-code-assistant/eca-nvim",
+ dependencies = {
+ "MunifTanjim/nui.nvim", -- Required: UI framework
+ "nvim-lua/plenary.nvim", -- Optional: Enhanced async operations
+ },
+ keys = {
+ { "ec", "EcaChat", desc = "Open ECA chat" },
+ { "ef", "EcaFocus", desc = "Focus ECA sidebar" },
+ { "et", "EcaToggle", desc = "Toggle ECA sidebar" },
+ },
+ opts = {
+ debug = false,
+ server_path = "",
+ behaviour = {
+ auto_set_keymaps = true,
+ auto_focus_sidebar = true,
+ },
+ }
+}
+```
+
+### packer.nvim
+
+```lua
+use {
+ "editor-code-assistant/eca-nvim",
+ requires = {
+ "MunifTanjim/nui.nvim", -- Required: UI framework
+ "nvim-lua/plenary.nvim", -- Optional: Enhanced async operations
+ },
+ config = function()
+ require("eca").setup({
+ -- Your configurations here
+ })
+ end
+}
+```
+
+### vim-plug
+
+```vim
+" In your init.vim or init.lua
+Plug 'editor-code-assistant/eca-nvim'
+
+" Required dependencies
+Plug 'MunifTanjim/nui.nvim'
+
+" Optional dependencies (enhanced async operations)
+Plug 'nvim-lua/plenary.nvim'
+
+" After the plugins, add:
+lua << EOF
+require("eca").setup({
+ -- Your configurations here
+})
+EOF
+```
+
+### dein.vim
+
+```vim
+call dein#add('editor-code-assistant/eca-nvim')
+
+" Required dependencies
+call dein#add('MunifTanjim/nui.nvim')
+
+" Optional dependencies (enhanced async operations)
+call dein#add('nvim-lua/plenary.nvim')
+
+" Configuration
+lua << EOF
+require("eca").setup({
+ -- Your configurations here
+})
+EOF
+```
+
+### rocks.nvim
+
+```toml
+# rocks.toml
+[plugins]
+"eca-nvim" = { git = "editor-code-assistant/eca-nvim" }
+
+# Required dependencies
+"nui.nvim" = { git = "MunifTanjim/nui.nvim" }
+
+# Optional dependencies (enhanced async operations)
+"plenary.nvim" = { git = "nvim-lua/plenary.nvim" }
+```
+
+### mini.deps
+
+```lua
+local add = MiniDeps.add
+
+add({
+ source = "editor-code-assistant/eca-nvim",
+ depends = {
+ "MunifTanjim/nui.nvim", -- Required: UI framework
+ "nvim-lua/plenary.nvim", -- Optional: Enhanced async operations
+ }
+})
+
+require("eca").setup({
+ -- Your configurations here
+})
+```
+
+---
+
+## Next steps
+- See the Usage guide for getting started with chat and context: [docs/usage.md](./usage.md)
+- Explore configuration options: [docs/configuration.md](./configuration.md)
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
new file mode 100644
index 0000000..92df5c0
--- /dev/null
+++ b/docs/troubleshooting.md
@@ -0,0 +1,65 @@
+# Troubleshooting
+
+Common issues and how to fix them.
+
+## Server won't start
+
+Symptoms: Chat doesn't respond, "server not running" error
+
+Solutions:
+- Check if `curl` and `unzip` are installed
+- Try setting `server_path` manually with absolute path
+- Check logs with `debug = true` in configuration
+- Try `:EcaServerRestart`
+
+```lua
+-- Debug configuration
+require("eca").setup({
+ debug = true,
+ server_args = "--log-level debug",
+})
+```
+
+## Connectivity issues
+
+Symptoms: Download fails, timeouts, network errors
+
+Solutions:
+- Check your internet connection
+- Ensure firewalls are not blocking requests
+- Restart with `:EcaServerRestart`
+- Configure a proxy if necessary
+- Download the server manually and set `server_path`
+
+## Shortcuts not working
+
+Symptoms: `ec` doesn't open chat
+
+Solutions:
+- Ensure `behaviour.auto_set_keymaps = true`
+- Confirm your `` key (default: `\`)
+- Configure shortcuts manually:
+
+```lua
+vim.keymap.set("n", "ec", ":EcaChat", { desc = "ECA Chat" })
+vim.keymap.set("n", "et", ":EcaToggle", { desc = "ECA Toggle" })
+```
+
+## Windows-specific
+
+Symptoms: Path errors, server not found
+
+Solutions:
+- Use WSL2 for better compatibility
+- Install curl and unzip on Windows
+- Use forward slashes `/` in paths
+- Configure `server_path` with `.exe` extension
+
+## Performance issues
+
+Symptoms: Lag when typing, slow responses
+
+Solutions:
+- Reduce window width: `windows.width = 25`
+- Disable visual updates: `behaviour.show_status_updates = false`
+- Use the minimalist configuration preset
diff --git a/docs/usage.md b/docs/usage.md
new file mode 100644
index 0000000..c69c219
--- /dev/null
+++ b/docs/usage.md
@@ -0,0 +1,239 @@
+# Usage
+
+Everything you need to get productive with ECA inside Neovim.
+
+## Quick Start
+
+1. Install the plugin using any package manager
+2. Restart Neovim or reload your configuration
+3. Open a file you want to analyze
+4. Run `:EcaChat` or press `ec`
+5. On first run, the server downloads automatically
+6. Type your question and press `Ctrl+S` to send
+
+---
+
+## Available Commands
+
+| Command | Description | Example |
+|--------|-------------|---------|
+| `:EcaChat` | Opens ECA chat | `:EcaChat` |
+| `:EcaToggle` | Toggles sidebar visibility | `:EcaToggle` |
+| `:EcaFocus` | Focus on ECA sidebar | `:EcaFocus` |
+| `:EcaClose` | Closes ECA sidebar | `:EcaClose` |
+| `:EcaAddFile [file]` | Adds file as context | `:EcaAddFile src/main.lua` |
+| `:EcaAddSelection` | Adds current selection as context | `:EcaAddSelection` |
+| `:EcaServerStart` | Starts ECA server manually | `:EcaServerStart` |
+| `:EcaServerStop` | Stops ECA server | `:EcaServerStop` |
+| `:EcaServerRestart` | Restarts ECA server | `:EcaServerRestart` |
+| `:EcaSend ` | Sends message directly | `:EcaSend Explain this function` |
+
+---
+
+## Keyboard Shortcuts
+
+### Global (default)
+
+| Shortcut | Action |
+|----------|--------|
+| `ec` | Open/focus chat |
+| `ef` | Focus on sidebar |
+| `et` | Toggle sidebar |
+
+### Chat
+
+| Shortcut | Action | Context |
+|----------|--------|---------|
+| `Ctrl+S` | Send message | Insert/Normal mode |
+| `Enter` | New line | Insert mode |
+| `Esc` | Exit insert mode | Insert mode |
+
+---
+
+## Using the Chat
+
+### Sending messages
+- Type in the input line starting with `> `
+- Press `Enter` to insert a new line
+- Press `Ctrl+S` to send
+- Responses stream in real time
+
+### Examples
+
+```markdown
+Explain what this function does
+```
+
+```markdown
+Optimize this code:
+[code will be added as context]
+```
+
+```markdown
+How can I improve the performance of this function?
+Consider readability and maintainability.
+```
+
+---
+
+## Adding Context
+
+### Current file
+
+```vim
+:EcaAddFile
+```
+
+### Specific file
+
+```vim
+:EcaAddFile src/main.lua
+:EcaAddFile /full/path/to/file.js
+```
+
+### Code selection
+
+1. Select code in visual mode (`v`, `V`, or `Ctrl+v`)
+2. Run `:EcaAddSelection`
+3. Selected code will be added as context
+
+### Multiple files
+
+```vim
+:EcaAddFile src/utils.lua
+:EcaAddFile src/config.lua
+:EcaAddFile tests/test_utils.lua
+```
+
+---
+
+## Common Use Cases
+
+### Code analysis
+```markdown
+> Analyze this file and tell me if there are performance issues
+```
+
+### Debugging
+```markdown
+> This code is returning an error. Can you help me identify the problem?
+[add the file as context first]
+```
+
+### Documentation
+```markdown
+> Generate JSDoc documentation for these functions
+```
+
+### Refactoring
+```markdown
+> How can I refactor this code to use ES6+ features?
+```
+
+### Testing
+```markdown
+> Create unit tests for this function
+```
+
+### Optimization
+```markdown
+> Suggest improvements to optimize this algorithm
+```
+
+---
+
+## Recommended Workflow
+
+1. Open the file you want to analyze
+2. Add as context: `:EcaAddFile`
+3. Open chat: `ec`
+4. Ask your question:
+ ```markdown
+ > Explain what this function does and how I can improve it
+ ```
+5. Send with `Ctrl+S`
+6. Read the response and implement suggestions
+7. Continue the conversation for clarifications
+
+---
+
+## Advanced Commands
+
+### Server management
+
+```vim
+" Restart if there are issues
+:EcaServerRestart
+
+" Stop temporarily
+:EcaServerStop
+
+" Start again
+:EcaServerStart
+```
+
+### Quick commands
+
+```vim
+" Send message directly (without opening chat)
+:EcaSend Explain this line of code
+
+" Focus on chat if already open
+:EcaFocus
+
+" Toggle chat visibility
+:EcaToggle
+```
+
+---
+
+## Tips and Tricks
+
+### Productivity
+1. Use `:EcaAddFile` before asking about specific code
+2. Combine contexts: add multiple related files
+3. Be specific: detailed questions generate better responses
+4. Use Markdown: ECA understands Markdown formatting
+
+### Workflows
+
+#### Code review
+```markdown
+> Analyze this code and suggest improvements:
+- Performance
+- Readability
+- Best practices
+- Possible bugs
+```
+
+#### Test creation
+```markdown
+> Create comprehensive unit tests for this function, including:
+- Success cases
+- Error cases
+- Edge cases
+- Mocks if necessary
+```
+
+#### Documentation
+```markdown
+> Generate complete documentation for this module:
+- General description
+- Parameters and types
+- Usage examples
+- Possible exceptions
+```
+
+### Custom shortcuts
+
+```lua
+-- More convenient shortcuts
+vim.keymap.set("n", "", ":EcaChat")
+vim.keymap.set("n", "", ":EcaToggle")
+vim.keymap.set("v", "ea", ":EcaAddSelection")
+
+-- Shortcut to add current file
+vim.keymap.set("n", "ef", function()
+ vim.cmd("EcaAddFile " .. vim.fn.expand("%"))
+end)
+```