docs: add comprehensive README

Replace the placeholder README with a full reference covering features,
requirements, installation (lazy/packer/vim-plug), configuration tables
with defaults, commands, keymaps, highlight groups, API, and a quick
start guide.

README.md

@@ -1,3 +1,203 @@
 # watchexec.nvim
 
-This plugin allows you to start and stop a task using watchexec and display the output of the task within Neovim.
+Integrate the [watchexec](https://github.com/watchexec/watchexec) CLI into
+Neovim — run file-watching commands and view their output in a floating or
+split window.
+
+## Features
+
+- **Floating or split** output window, configurable per-user.
+- **Status indicator** — a small non-focusable float that shows success or
+  failure when the main window is hidden.
+- **ANSI escape sequence stripping** so output is clean.
+- **Keyword highlighting** via `DiagnosticError`, `DiagnosticWarn`, and
+  `DiagnosticOk` for error/warning/success keywords in output.
+- **Auto-scroll** to the latest output, with configurable buffer size limits.
+- **Auto-resize** on `VimResized`, and automatic cleanup on `VimLeavePre`.
+- **Binary auto-discovery** — searches PATH, `~/.cargo/bin`, Homebrew, and
+  WSL locations.
+
+## Requirements
+
+- Neovim >= 0.10
+- [watchexec CLI](https://github.com/watchexec/watchexec)
+
+Install the CLI:
+
+```
+cargo install watchexec
+```
+
+Or download a prebuilt binary from the [releases page](https://github.com/watchexec/watchexec/releases).
+
+## Installation
+
+**lazy.nvim**
+```lua
+{
+  "stevanfreeborn/watchexec.nvim",
+  opts = {},
+}
+```
+
+**packer.nvim**
+```lua
+use {
+  "stevanfreeborn/watchexec.nvim",
+  config = function()
+    require("watchexec").setup({})
+  end,
+}
+```
+
+**vim-plug**
+```vim
+Plug 'stevanfreeborn/watchexec.nvim'
+lua require("watchexec").setup({})
+```
+
+## Quick Start
+
+After installing, restart Neovim and run:
+
+```
+:WatchexecRun echo hello
+```
+
+Or press `<Leader>wxr`, type a command at the prompt, and press Enter.
+
+The output window opens automatically. Press `q` or `<Esc>` inside the window
+to close it. Press `<Leader>wxt` to toggle it back.
+
+## Configuration
+
+`setup()` accepts an optional table with the following fields:
+
+### `watchexec` — binary options
+
+| Field   | Type     | Default          | Description |
+|---------|----------|------------------|-------------|
+| `bin`   | `string` | `"watchexec"`    | Path to the watchexec executable. Auto-detected from PATH and common locations. |
+| `args`  | `table`  | `{}`             | Extra arguments passed to watchexec before the user command. |
+
+### `window` — output window options
+
+| Field    | Type                 | Default      | Description |
+|----------|----------------------|--------------|-------------|
+| `type`   | `"float"` / `"split"` | `"float"`    | Window type. |
+| `split`  | `"below"` / `"above"` / `"left"` / `"right"` | `"below"` | Split direction (only used when `type` is `"split"`). |
+| `size`   | `integer`           | `12`         | Split window size in rows/columns. |
+| `border` | `string` / `table`  | `"single"`   | Border style for floats (see `:help nvim_open_win()`). |
+| `float`  | `table`             | *(see below)* | Float geometry. |
+
+#### `window.float` — float geometry
+
+| Field      | Type     | Default      | Description |
+|------------|----------|--------------|-------------|
+| `relative` | `string` | `"editor"`   | Positioning anchor. |
+| `width`    | `number` | `0.8`        | Width in columns (values <= 1 are fractions of editor width). |
+| `height`   | `number` | `0.6`        | Height in rows (values <= 1 are fractions of editor height). |
+| `row`      | `number` | `0.5`        | Row position (values <= 1 are fractions). |
+| `col`      | `number` | `0.5`        | Column position (values <= 1 are fractions). |
+
+### `indicator` — status indicator options
+
+| Field        | Type                                          | Default             | Description |
+|--------------|-----------------------------------------------|---------------------|-------------|
+| `enabled`    | `boolean`                                     | `true`              | Enable/disable the indicator. |
+| `position`   | `"bottom-left"` / `"bottom-right"` / `"top-left"` / `"top-right"` | `"bottom-right"` | Screen corner. |
+| `success_hl` | `string`                                      | `"WatchexecSuccess"` | Highlight for success state. |
+| `failure_hl` | `string`                                      | `"WatchexecFailure"` | Highlight for failure state. |
+| `width`      | `integer`                                     | `2`                 | Indicator width in cells. |
+| `height`     | `integer`                                     | `1`                 | Indicator height in cells. |
+| `patterns`   | `table`                                       | *(see below)*       | Lua patterns for parsing output. |
+
+#### `indicator.patterns`
+
+| Field     | Type     | Default                     | Description |
+|-----------|----------|-----------------------------|-------------|
+| `success` | `string` | `"%[Command was successful%]"` | Pattern matching successful command output. |
+| `running` | `string` | `"%[Running"`               | Pattern matching command start. |
+
+### General options
+
+| Field         | Type      | Default | Description |
+|---------------|-----------|---------|-------------|
+| `auto_scroll` | `boolean` | `true`  | Scroll to bottom on new output. |
+| `max_lines`   | `integer` | `5000`  | Maximum lines in the output buffer (oldest trimmed). |
+
+### Full config example
+
+```lua
+require("watchexec").setup({
+  auto_scroll = false,
+  max_lines = 1000,
+  watchexec = {
+    bin = "watchexec",
+    args = { "--shell", "bash" },
+  },
+  window = {
+    type = "split",
+    split = "below",
+    size = 15,
+  },
+  indicator = {
+    enabled = true,
+    position = "bottom-left",
+  },
+})
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `:WatchexecRun {command}` | Start watchexec with the given shell command. Stops any previous run and opens the output window. |
+| `:WatchexecStop` | Stop the currently running watchexec process and clear the output. |
+| `:WatchexecToggle` | Toggle the output window. |
+
+## Keymaps
+
+| Keymap         | Action | Description |
+|----------------|--------|-------------|
+| `<Leader>wxt`  | `:WatchexecToggle` | Toggle the output window. |
+| `<Leader>wxs`  | `:WatchexecStop` | Stop the running process. |
+| `<Leader>wxr`  | `:WatchexecRun`  | Prompt for a command and run it. |
+
+## Highlight Groups
+
+| Group | Default | Description |
+|-------|---------|-------------|
+| `WatchexecSuccess` | `guibg=#00ff00` | Indicator background when the last command succeeded. |
+| `WatchexecFailure` | `guibg=#ff0000` | Indicator background when the last command failed. |
+
+Output lines are also highlighted using built-in diagnostic groups:
+- `DiagnosticError` — for error, fail, fatal keywords
+- `DiagnosticWarn`  — for warning keywords
+- `DiagnosticOk`    — for success, passed, ok keywords
+
+## API
+
+```lua
+---@param opts? watchexec.Config
+require("watchexec").setup(opts)
+
+---@param command string
+require("watchexec").run(command)
+
+require("watchexec").stop()
+
+require("watchexec").toggle()
+```
+
+## Documentation
+
+Full help is available in Neovim:
+
+```
+:help watchexec
+```
+
+## License
+
+MIT