3 +description: "Use when a question concerns pivi, the running Neovim instance, Neovim behaviour or configuration, or why the editor looks or behaves the way it does. Also use when answering from inside a pivi session about the editor rather than the project."
8 +pivi runs you inside Neovim instead of a terminal interface.
9 +You are a normal Pi process, started as a JSONL RPC child of a live Neovim.
10 +The user's own Pi configuration is loaded: providers, extensions, skills, prompt templates, and context files.
12 +##
Where answers come from 14 +| Question is about | Do this |
16 +| Neovim behaviour, options, functions, or a plugin's documentation | call `nvim_help` with the tag, exactly as `:help {tag}` would be typed |
17 +| What the user currently sees, has open, selected, or unsaved | the editor view is already attached to the question; call `nvim_state` only for detail beyond it |
18 +| Live editor values, buffers, windows, diagnostics, lists | call `nvim_lua` and return a value |
19 +| pivi itself | this skill |
20 +| Pi itself: models, extensions, sessions, settings, keybindings | the `pi-knowledge` skill and Pi's installed documentation |
21 +| The project and its code | ordinary file tools |
23 +Never answer a Neovim documentation question from memory when `nvim_help` can answer it.
24 +The tag resolves against this machine's runtime path, so plugin documentation and this exact Neovim version are covered.
25 +When the tag misses, the result carries candidate tags; pick one and try again rather than guessing prose.
29 +- A Pi session is an explicit task identity with persistent history and a working directory. Buffers and tabs never own it.
30 +- Loaded buffers, including unsaved ones, are authoritative. Reads see buffer content, not stale disk content.
31 +- Agent edits land in the buffer, stay undoable as one change, and are made visible to later filesystem work.
32 +- Activity is shown with pivi's own extmarks, signs, diagnostics, quickfix and location lists, never in another namespace.
33 +- Streaming edit intent may appear as ghost text; it never mutates a buffer before arguments are complete.
34 +- Follow mode is optional. It tracks located events in a dedicated window or tab and never steals the working window.
35 +- State is published through a native variable and `User` events; consumers read the cache and never trigger RPC.
37 +##
Surfaces the user has 41 +| `:Pi ask {text}` | submit to the active session, creating one when needed |
42 +| `:Pi steer {text}` / `:Pi follow-up {text}` | deliver during an active run |
43 +| `:Pi help {question}` | this ephemeral run: no persisted session, no working-session history, queue, or status touched |
44 +| `:Pi command [name]` | run a Pi slash command; `/` at the first character of a pivi input buffer opens the picker |
45 +| `:Pi prompt` | open a prompt buffer; `<c-s>` submits |
46 +| `:Pi start` / `stop` / `sessions` / `show` | session lifetime and presentation |
47 +| `:Pi abort` / `queue` / `clear` | run and queue control |
48 +| `:Pi follow [window\|tab\|current]` | toggle follow mode |
50 +`<Plug>(pivi-show)`, `<Plug>(pivi-prompt)`, `<Plug>(pivi-abort)`, and `<Plug>(pivi-follow)` exist; pivi sets no global mappings.
54 +Be short and concrete.
55 +Name the exact command, option, or help tag the user should use.
56 +Prefer one verified fact from `nvim_help` over three remembered ones.
57 +In a help run, do not modify anything: only read-only tools are available, and the question is meant to be cheap.