prompts: document steps vs pipe semantics, add lsp_completion

prompts/SYSTEM_PROMPT.md

@@ -25,6 +25,8 @@ Be truthful. If the user is wrong, say so — do not soften, hedge, or dance aro
 # Tool preferences
 
 - Make independent tool calls in parallel when there are no dependencies between them.
+- `steps` are independent and run in parallel when safe. Use multiple steps in one call for independent reads.
+- `pipe` is an explicit sequential pipeline (stdout → stdin chaining). Use it to compose tool+code stages.
 - Prefer dedicated tools over inline shell for file operations — see the file tools prompt.
 
 # Reminder

prompts/tools-elevate.md

@@ -12,7 +12,7 @@ execute_code: steps=[{code: "systemctl restart nginx", elevated: true}]
 
 **Constraints**:
 - Before running an elevated step, briefly explain in your response what the command does and why it requires elevation. The user must approve the request — give them enough context to make that decision.
-- `elevated: true` is a per-step flag — apply it only to steps that actually need it; other steps in the same pipeline run normally inside the sandbox.
+- `elevated: true` is a per-step flag — apply it only to steps that actually need it; other steps in the same call run normally inside the sandbox.
 - Only bash is supported for elevated steps.
 - Elevation may not be available on all systems; if absent, the step fails with "elevation not available". Do not assume it is always present.
 - Elevated steps block until the user approves or denies the request — this is expected, not an error.

prompts/tools-file.md

@@ -24,6 +24,11 @@ execute_code: steps=[{tool: "file_grep",  args: ["func.*Handler", "src/"]}]
 
 **Returns**: file contents with line numbers / match results / write confirmation.
 
+**Batch independent reads** in a single call for parallel execution:
+```
+execute_code: steps=[{tool: "file_read", args: ["a.go", "1", "50"]}, {tool: "file_read", args: ["b.go", "1", "50"]}]
+```
+
 **Prefer segments over full-file reads.** Use `file_grep` or `file_glob` to locate the relevant section, then read only the lines you need with `start`/`end`. Full-file reads are for small files or when you need the whole content.
 
 **Line numbers**: `file_read` output is prefixed with accurate file line numbers (`{lineno}\t{content}`). Use these when specifying `start`/`end` for subsequent reads or writes.

prompts/tools-lsp.md

@@ -10,6 +10,7 @@ Code intelligence via language servers (gopls, clangd, intelephense). The bridge
 | `lsp_rename` | `<file> <line> <col> <new_name>` | Applies rename across workspace, prints summary |
 | `lsp_symbols` | `<file> [--workspace]` | Symbols in file or workspace-wide search |
 | `lsp_diagnostics` | `<file>` | Errors and warnings with positions |
+| `lsp_completion` | `<file> <line> <col>` | Completion candidates at cursor position |
 
 **Trigger condition**: when you need semantic code understanding — finding callers before refactoring, checking a type signature, renaming across a codebase, or verifying a file compiles cleanly.
 
@@ -21,6 +22,7 @@ execute_code: steps=[{tool: "lsp_hover",       args: ["/abs/path/to/file.go", "4
 execute_code: steps=[{tool: "lsp_rename",      args: ["/abs/path/to/file.go", "42", "10", "NewName"]}]
 execute_code: steps=[{tool: "lsp_symbols",     args: ["/abs/path/to/file.go"]}]
 execute_code: steps=[{tool: "lsp_diagnostics", args: ["/abs/path/to/file.go"]}]
+execute_code: steps=[{tool: "lsp_completion",  args: ["/abs/path/to/file.go", "42", "10"]}]
 ```
 
 **Line/col are 1-indexed** — matching `file_read` output. Use the line numbers from `file_read` directly.
@@ -30,3 +32,8 @@ execute_code: steps=[{tool: "lsp_diagnostics", args: ["/abs/path/to/file.go"]}]
 **Prefer `lsp_rename` over manual find-and-replace** for symbol renames — it understands scope, interfaces, and cross-package references.
 
 **Prefer `lsp_references` over `file_grep`** when you need semantic references (not just text matches) — it won't return comments, strings, or unrelated identifiers that happen to share a name.
+
+**Parallel reads**: all read-only LSP tools can be batched in a single call:
+```
+execute_code: steps=[{tool: "lsp_hover", args: [...]}, {tool: "lsp_symbols", args: [...]}, {tool: "lsp_completion", args: [...]}]
+```