Documentation upgrade

.github/instructions/shell-operations.instructions.md

@@ -0,0 +1,46 @@
+---
+description: 'Shell-operation guardrails for shared PowerShell sessions, tool availability checks, and multiline command workarounds'
+applyTo: '**'
+---
+
+# Shell Operations
+
+Use these rules when running shell commands from this workspace.
+
+## General Rules
+
+- Prefer built-in workspace tools for file search, text search, file reads, and edits before dropping to the terminal.
+- Keep terminal commands short and single-line when possible.
+- Treat the shared PowerShell session as fragile after any prompt-continuation or escape-sequence artifact appears.
+
+## Tool Availability
+
+- Do not assume `rg` is installed.
+- Before using `rg`, check availability with `Get-Command rg -ErrorAction SilentlyContinue`.
+- If `rg` is unavailable, use workspace search tools first.
+- If shell-side fallback is still needed, use PowerShell-native alternatives:
+  - `Get-ChildItem -Recurse -File` for file discovery
+  - `Select-String` for text search
+
+## Multiline Command Safety
+
+- Do not paste multiline commands directly into the shared PowerShell terminal when a one-line command or script file will do.
+- Do not send multiline PowerShell hash tables, arrays, or loops directly to the shared terminal if the same work can be expressed as:
+  - one single-line command, or
+  - a temporary `.ps1` script file executed with `pwsh -File`, or
+  - a temporary `.py` file executed with Python for Python-side work.
+- Always write multiline Python to a temporary `.py` file and execute that file instead of pasting Python into the terminal.
+
+## Recovering From Terminal Weirdness
+
+- If the prompt shows continuation markers, partial prompt redraws, or escape-sequence artifacts, stop issuing more complex commands in that shell.
+- Try a single `Esc` first to clear unfinished input.
+- If the shell still looks unhealthy, ask the user to reset or fix the terminal with the ask-questions tool before continuing.
+- After recovery, resume with single-line commands or temporary script files instead of retrying the same multiline paste.
+
+## Command Style
+
+- Prefer explicit PowerShell cmdlets over aliases in reusable commands.
+- Avoid commands that rely on interactive input.
+- Prefer one focused command per terminal invocation so failures are easier to attribute.
+- When posting HTTP form data from PowerShell, prefer compact one-line request bodies over multiline literal blocks in the shared shell.