@@ -0,0 +1,53 @@
1+# AGENTS.md
2+
3+Repository notes for coding agents working on `vim-pi-complete`.
4+
5+## Project overview
6+
7+This is a minimal Neovim plugin that exposes `:Pi <prompt>` for AI-assisted edits. The user visually selects text, runs `:Pi`, and the plugin replaces the selection with stdout from the `pi` coding agent.
8+
9+The plugin intentionally invokes `pi` in a constrained way:
10+
11+- read-only tools only: `read,find,ls,grep`
12+- `--thinking minimal` for speed
13+- no edit/write tools; Neovim performs the actual replacement
14+- prompt asks for replacement text only
15+
16+## Repository layout
17+
18+- `plugin/pi_complete.lua`
19+ - Neovim runtime entrypoint.
20+ - Guards against double loading with `vim.g.loaded_pi_complete`.
21+ - Defines the public `:Pi` command.
22+ - Adds a lowercase `:pi` command-line abbreviation.
23+
24+- `lua/pi_complete/init.lua`
25+ - Main implementation module.
26+ - Builds the prompt sent to `pi`.
27+ - Captures the visual selection using register `z`.
28+ - Calls the external `pi` executable with `vim.fn.system`.
29+ - Replaces the selected text with the command output.
30+ - Restores register `z` afterward.
31+
32+- `README.md`
33+ - User-facing description, usage, and installation notes.
34+
35+- `LICENSE`
36+ - MIT license.
37+
38+## Important behavior to preserve
39+
40+- `:Pi` is selection-oriented. The current implementation relies on `gv` to restore the previous visual selection.
41+- Register `z` is temporary scratch space. Always save and restore its contents and type.
42+- Failed `pi` calls should leave the buffer unchanged.
43+- The generated text should be pasted using the original selection type: characterwise, linewise, or blockwise.
44+- Keep the implementation dependency-free and compatible with standard Neovim Lua APIs.
45+
46+## Development notes
47+
48+- There is currently no package metadata, test suite, formatter config, or CI.
49+- Keep changes small and plugin-style: simple Lua files under `plugin/` and `lua/`.
50+- Prefer clear behavior over clever abstractions; this project is intentionally tiny.
51+- If changing the `pi` invocation, update `README.md` so documented behavior stays accurate.
52+- If adding real line-range support, do not assume `opts.range` alone is enough; the current replacement path still uses `gv`.
53+- If adding async execution, preserve the current safety properties: no register clobbering, failed calls do not edit the buffer, and user feedback is visible.