feat(hexai-action): add --infile/--outfile flags; docs and tests\n\n- Add flags to read from file and write to file\n- Refactor IO open into helper for testability\n- Add CLI integration-style test for IO\n- Update README and docs/usage.md with examples\n- Update docs/testing.md with instructions

2 files changed, 36 insertions, 0 deletions

diff --git a/docs/testing.md b/docs/testing.md
index eff6f2e..17dd4b3 100644
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -14,3 +14,17 @@ Suggested additions:
 - Expand table‑driven coverage for completion edit computations and label/filter selection.
 - Add more negative tests (malformed SSE/JSON payloads) to assert robust error handling.
 
+## Running Tests
+
+- Full suite with coverage:
+  - `HEXAI_TEST_SKIP_NET=1 go test ./... -cover`
+  - The `HEXAI_TEST_SKIP_NET=1` env var disables any tests that require network access, keeping runs deterministic in CI/sandboxes.
+
+- Package-specific runs:
+  - `HEXAI_TEST_SKIP_NET=1 go test ./cmd/internal/hexai-action -cover`
+  - `HEXAI_TEST_SKIP_NET=1 go test ./internal/hexaiaction -cover`
+
+Notes
+
+- Some environments restrict writes to the Go build cache; if you see cache permission errors, re-run in a less-restricted shell or allow the command to write to the cache.
+- Always format Go code before committing: `gofumpt -w .`
diff --git a/docs/usage.md b/docs/usage.md
index c74ee7d..a5c5dca 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -102,3 +102,25 @@ hexai 'install ripgrep on macOS'
 # Verbose explanation
 hexai 'install ripgrep on macOS and explain'
 ```
+
+## Hexai Action (TUI)
+
+`hexai-action` runs code actions over a selection or diagnostics+selection piped from stdin, or read from a file.
+
+- Choose an action with arrow keys, `j/k`, `g/G`, Enter, or hotkeys `[s] [r] [c] [t]`.
+- Output is written to stdout by default, or to a file via `--outfile`.
+
+Input formats are the same as described in the README (inline instruction markers for rewrite; optional `Diagnostics:` header block).
+
+Examples
+
+```sh
+# From stdin
+cat input.go | hexai-action
+
+# From file to file
+hexai-action --infile input.go --outfile output.go
+
+# Using shell redirection
+hexai-action < input.go > output.go
+```