feat(lsp): configurable inline/chat triggers; switch inline markers to >text>/>>text>; update docs and example config; tests updated to new triggers and raise LSP coverage to >=85%; chore: remove semicolon legacy; chore(mage): auto-refresh coverage daily if docs/coverage.out is older than 24h

1 files changed, 104 insertions, 0 deletions

diff --git a/docs/usage.md b/docs/usage.md
new file mode 100644
index 0000000..c74ee7d
--- /dev/null
+++ b/docs/usage.md
@@ -0,0 +1,104 @@
+# Hexai usage and examples
+
+This document describes how to run the LSP server, configure Helix, use in-editor chat,
+inline triggers, code actions, and the CLI — with examples.
+
+## LSP server
+
+- Run over stdio: `hexai-lsp`
+- Flags:
+  - `-version`: print Hexai version and exit.
+  - `-log`: path to log file (default `/tmp/hexai-lsp.log`).
+
+### Configure in Helix
+
+In `~/.config/helix/languages.toml`:
+
+```toml
+[[language]]
+name = "go"
+auto-format = true
+diagnostic-severity = "hint"
+formatter = { command = "goimports" }
+language-servers = [ "gopls", "golangci-lint-lsp", "hexai" ]
+
+[language-server.hexai]
+command = "hexai-lsp"
+```
+
+Note: additional LSPs (`gopls`, `golangci-lint-lsp`) are optional; Hexai works without them.
+
+## In-editor chat
+
+Ask a question at the end of a line and receive the answer inline.
+
+- End your question line with a trigger: `?>`, `!>`, or `:>`.
+- Hexai removes only the trailing `>` from the question line (and keeps your trailing punctuation). Inline code-completion triggers now use `>text>` (inline) or `>>text>` (line-replace).
+- It inserts a blank line, then a reply line prefixed with `> `, then one extra newline so most
+  editors place the cursor on a fresh blank line after the answer.
+- If a `>` reply already exists below the question, Hexai won’t answer again.
+
+Example:
+
+```text
+What is a slice in Go?>
+
+> A slice is a dynamically-sized, flexible view into the elements of an array. It references
+> an underlying array and tracks length/capacity; most Go code uses slices instead of arrays.
+
+```
+
+Context: Hexai includes up to the three most recent Q/A pairs above the question when asking the LLM, so follow-ups remain on topic (e.g., “Are there many tourists?” after a location answer).
+
+## Inline triggers
+
+Hexai supports inline prompt tags you can type in code to request an action from the LLM and then auto-clean the tag. The new `>`-based forms are:
+
+- `>do something>` — uses the text between `>` markers as the instruction and removes only the prompt. Strict form requires no space after the first `>` and no space before the closing `>`.
+- `>>do something>` — same as above, but replaces the entire current line with the completion.
+
+Spaced variants (e.g., `> spaced >`) are ignored.
+
+## Code actions
+
+Operate on the current selection in Helix:
+
+- Rewrite selection: finds the first instruction inside the selection and rewrites accordingly.
+- Resolve diagnostics: gathers only diagnostics overlapping the selection and fixes them by editing the selected code; diagnostics outside the selection are not changed.
+- Implement unit test (Go): when editing a `.go` file, adds a code action to generate a unit test for the function under the cursor. If `<file>_test.go` exists, appends a new `Test*`; otherwise creates the test file with `package` and `import "testing"`.
+- Document code: adds idiomatic documentation comments to the selected code, preserving behavior and returning only the documented code.
+
+Instruction sources (first match wins):
+
+- Strict marker: `;text;` (no space after first `;`).
+- Line comments: `// text`, `# text`, `-- text`.
+- Single-line block comments: `/* text */`, `<!-- text -->`.
+
+## CLI usage
+
+Process text via the configured LLM:
+
+- `cat SOMEFILE.txt | hexai`
+- `hexai 'some prompt text here'`
+- `cat SOMEFILE.txt | hexai 'some prompt text here'` (stdin and arg are concatenated)
+
+Defaults: concise answers. If the prompt asks for commands, Hexai outputs only commands. Add the word `explain` to request a verbose explanation. Exit codes: `0` success, `1` provider/config error, `2` no input.
+
+### Examples
+
+```sh
+# From stdin only
+cat SOMEFILE.txt | hexai
+
+# From arg only
+hexai 'summarize: list 3 bullets'
+
+# From both (stdin first, then arg)
+cat SOMEFILE.txt | hexai 'explain the tradeoffs'
+
+# Commands-only output (no explanation)
+hexai 'install ripgrep on macOS'
+
+# Verbose explanation
+hexai 'install ripgrep on macOS and explain'
+```