# Neovim + Pi cheat sheet (with an optional Copilot example)

Mappings below use `<leader>` notation. The plugin does not set `mapleader`; Vim and Neovim use backslash (`\`) by default. If your configuration sets `<leader>` to Space, for example, `<leader>ps` means `Space p s`. Pi does not require Copilot or another inline completion plugin. This example leaves automatic Insert-mode completion to Copilot while Pi handles deliberate requests.

## Which tool should I use?

| Goal | Use |
|---|---|
| Ask Pi a question about editor content | Use `<leader>pf/pl/ps/pd/pb`, then write the question in Pi |
| Attach a question or comment to a selection | Visual `<leader>pS` (Shift-S), then enter the comment |
| Explain the annotation syntax once in Pi's draft | `<leader>ph` toggles a draft-level header |
| Get a deliberate completion at one cursor position | `<leader>pc` |
| Insert something specific at the cursor | `<leader>pg`, then enter the instruction |
| Rewrite selected text according to an instruction | Visual `<leader>pr` |
| Accept a fast automatic completion while typing | Inline completion plugin (for example, Copilot): `Tab` |
| Whole-file, multi-file, or tool-using work | The normal persistent Pi chat/agent |

## Add context to the Pi chat draft

These mappings append visible, editable text to the explicitly linked standalone Pi session. They **do not submit** a turn.

| Mode | Mapping | Action |
|---|---|---|
| Normal | `<leader>pf` | Add the current file reference |
| Normal | `<leader>pl` | Add file, cursor location, and current in-memory line |
| Visual | `<leader>ps` | Add the exact selection and its file/range |
| Visual | `<leader>pS` | Prompt for a comment, then add it with the selection |
| Normal | `<leader>pd` | Add current-buffer diagnostics |
| Normal | `<leader>pb` | Add the complete in-memory buffer, including unsaved edits |
| Normal or Visual | `<leader>pp` | Explicitly link or change the target Pi session |
| Normal | `<leader>pi` | Show Neovim cwd, linked Pi cwd/PID, and bridge status |
| Normal or Visual | `<leader>ph` | Add/remove the annotation header in Pi's current draft |

Repeated additions accumulate in Pi's input. Switch to Pi, type the question after the gathered context, and press Enter normally.

For a selection with a comment: select text, press `<leader>pS` (uppercase S), type something like `What does this mean?`, and press Enter. Pi receives the captured selection followed by `[an: What does this mean?]`, all in its editable draft. Blank Enter sends only the selection; Escape sends nothing. This does not submit a Pi turn. Changing the source text, file name, working directory, or Pi link during the comment prompt cancels the send.

Press `<leader>ph` **while Neovim is focused** to toggle one syntax-explanation header at the top of Pi's current draft. It is not added by each selection send and is not a persistent setting. Neither the Neovim buffer nor Pi's conversation is changed. Only a recognised leading header is removed; all remaining draft text stays intact. This shortcut requires restarting both Pi and Neovim after updating. If confirmation fails, check Pi's draft before retrying—the toggle is never automatically resent.

The `[an: ...]` notation is shared with Pi Studio and `pi-annotated-reply`. In Studio, **Inline annotations: On** sends annotations unchanged. **Hide** is a remembered setting that also strips them on Run/Critique—not just a preview toggle. This does not affect submission from Pi's terminal draft.

A small floating success notice stays visible for two seconds without taking focus, even in Visual mode. Use `<leader>pi` for full session details, configure `success_notice_ms` for a different duration, or `notify = false` to hide these notices.

Visual `<leader>pp` opens the picker without falling through to native Visual-mode `p`, so it cannot paste over the active selection. Other enabled Pi mappings listed as Normal-only are intercepted in Visual mode with a warning rather than passing their final key to a native Visual command.

On the first operation, Neovim always asks you to confirm an exact-cwd Pi link. It never silently falls back to another directory. If no exact bridge exists, restart Pi in that directory or use `<leader>pp` for a deliberate cross-directory link. Each Neovim cwd keeps an independent remembered link; switching cwd switches links and cancels any pending suggestion.

## Direct Pi completions, insertions, and rewrites

These call the active model directly without changing Pi's chat draft or session history.

| Mode | Mapping | Action |
|---|---|---|
| Normal | `<leader>pc` | Request a completion **after** the cursor character |
| Normal | `<leader>pg` | Enter an instruction and request an insertion there |
| Visual | `<leader>pr` | Enter an instruction and request a selection rewrite |
| Normal | `Tab` | Accept while a Pi result is visible, when temporary Tab acceptance is enabled and available |
| Normal | `<leader>pa` | Explicit accept mapping; always available by default |
| Normal | `<leader>pn` | Generate a materially different result |
| Normal | `<leader>pv` | Focus the full preview; scroll normally and press `q` to return |
| Normal | `<leader>px` | Cancel an active request or dismiss its result |

### Completion recipe

1. Leave Insert mode with `Esc`.
2. Put the cursor on the last character before the desired insertion.
3. Press `<leader>pc`.
4. Review the ghost text. Its highlighted first cell is the exact insertion boundary.
5. Press Normal `Tab` to accept when available, or use `<leader>pa` / `<leader>pn` / `<leader>px`.

### Guided-insertion recipe

1. Put the cursor on the last character before the desired insertion.
2. Press `<leader>pg`.
3. Enter an instruction such as `add references to Kuhn's book`.
4. Review the result. Multiline or wide results get a wrapping full preview.
5. Press Normal `Tab` when available, or `<leader>pa`, to accept. Use `<leader>pv` first if you need to focus and scroll the preview.

This direct request cannot search for or verify references. Supply exact bibliographic details when accuracy matters, or use the normal Pi agent for research.

### Rewrite recipe

1. Select the exact text using normal Vim Visual mode.
2. Press `<leader>pr`.
3. Enter the rewrite instruction and press Enter.
4. Review the wrapping diff preview; use `<leader>pv` to focus and scroll it.
5. Press Normal `Tab` when available, or use `<leader>pa` / `<leader>pn` / `<leader>px`.

After acceptance, `u` undoes the complete Pi edit in one step and `Ctrl-R` redoes it. Nothing is saved until `:write`.

## Optional inline completion example: Copilot

These mappings illustrate one complementary Copilot setup; `pi-nvim-context` does not install or require them.

| Mode | Mapping | Action |
|---|---|---|
| Insert | `Tab` | Accept the complete visible Copilot suggestion |
| Insert | `Ctrl-L` | Accept one Copilot word |
| Insert | `Ctrl-K` | Accept one Copilot line |
| Insert | `Option-\` | Explicitly request a Copilot suggestion |
| Normal | `<leader>ct` | Toggle Copilot globally |

When `copilot.vim` is installed, starting a direct Pi request makes a best-effort attempt to dismiss its visible ghost text. Insert-mode `Tab` remains available to the inline completion plugin. When enabled and not already claimed by the source buffer, a visible Pi result temporarily gives **Normal-mode** `Tab` to Pi; the mapping disappears when the result is accepted or dismissed.

## Optional system-clipboard example

These mappings are not installed by `pi-nvim-context`. Add them separately if you want ordinary Vim yanks and deletes to keep using normal registers while `<leader>y` writes explicitly to the system clipboard:

```vim
nnoremap <leader>y "+y
xnoremap <leader>y "+y
```

| Mode | Mapping | Action |
|---|---|---|
| Normal | `<leader>y` followed by a motion | Yank that motion to the system clipboard |
| Normal | `<leader>yy` | Yank the current line to the system clipboard |
| Visual | `<leader>y` | Copy the selection to the system clipboard |

## Equivalent Neovim commands

```text
:PiContextPick
:PiContextFile
:PiContextLocation
:PiContextSelection
:PiContextSelectionComment
:PiContextDiagnostics
:PiContextBuffer
:PiContextStatus
:PiContextAnnotationHeader

:PiSuggest
:PiSuggestGuided
:PiRewrite
:PiSuggestAccept
:PiSuggestAgain
:PiSuggestDismiss
:PiSuggestPreview
```

In Pi itself:

```text
/nvim-context
```

This shows whether that Pi session's bridge is active.

## Important behavior

- Pi must be idle for a direct completion, guided insertion, or rewrite. Context gathering still only edits Pi's draft.
- Context and direct edits share the same explicit, cwd-scoped Pi link.
- Cursor completion sees up to 12,000 characters before and 6,000 after the cursor.
- A guided insertion additionally sees your instruction; a rewrite sees the selected text and your instruction.
- Direct requests do not use tools, the full Pi conversation, or other project files automatically.
- If the Neovim buffer or target changes while Pi is working, the result is cancelled or discarded.
- Leaving the source buffer dismisses its pending request or preview.
- Blockwise Visual rewrites are not supported; use characterwise or linewise selection.
- `openai-codex/...` uses subscription-backed authentication. `openai/...` uses API-billed authentication; other providers use their configured billing.

## Troubleshooting

1. Fully restart Pi with `pi --continue`; do not rely on `/reload` after updating the package.
2. Restart Neovim so it loads the latest Lua plugin.
3. In Pi, run `/nvim-context`.
4. In Neovim, run `:PiContextStatus` (default: `<leader>pi`).
5. Run `:PiContextPick` (default: `<leader>pp`) to inspect and explicitly choose among discovered Pi bridges.
6. Check `:messages` for bridge or model errors.
7. If using Copilot, check `:Copilot status` for Copilot problems.