Documentation upgrade

.github/instructions/ghidra-mcp-server-updates.instructions.md

@@ -20,6 +20,7 @@ Use these instructions when making changes in the local Ghidra MCP source at K:/
 - Java plugin endpoint in src/main/java/com/lauriewired/GhidraMCPPlugin.java.
 - Python MCP bridge wrapper in bridge_mcp_ghidra.py.
 - Keep backward compatibility for endpoint naming when practical by adding aliases instead of removing old routes.
+- For POST endpoints, preserve existing form-urlencoded parameter handling and add `application/json` support when evolving request parsing; if a route still only accepts one format, return a structured unsupported-content-type error instead of a missing-parameter failure.
 - Keep xref and analysis outputs machine-friendly and evidence-rich (addresses, ref type, classification, function context).
 
 - **Terminal execution rule:** When running multi-line Python for testing or server-side scripts, do not paste multi-line code into interactive terminals. Always write the code to a temporary `.py` file and execute it with the Python interpreter. This prevents paste-related failures and preserves the intended execution environment.

.github/instructions/ghidra.instructions.md

@@ -32,6 +32,7 @@ applyTo: "**"
 - Prefer a single decompile call first.
 - If the decompiler collapses to thunk-heavy output, use one disassembly lookup to confirm the wrapper or parameter setup.
 - **When `decompile_function` output is too large** (>~50KB), the result is written to a temp JSON file that `read_file` returns as empty `{}`. Use `disassemble_function` instead — it returns inline assembly directly and is fully navigable for large functions.
+- For 16-bit NE decompiler failures such as `Low-level Error: Symbol $$undef... extends beyond the end of the address space`, do not assume the caller's frame is the only culprit. Inspect direct callees for parser-injected hidden `__return_storage_ptr__` parameters or bad pointer-return storage first, especially after prototype edits or function recreation.
 - Cross-reference new `CRUSADER.EXE` findings against the old raw notes before promoting a rename or behavioral claim. If the two differ, keep both addresses and explain the mismatch instead of silently preferring one.
 - Add a short decompiler comment when a rename is mapped from verified notes so the provenance stays visible in Ghidra.
 - Keep `crusader_decompilation_notes.md` updated after each verified batch. That file is now a short index — append new analysis to the appropriate file in `docs/` and add a row to the index table if a new file is created.
@@ -58,6 +59,7 @@ applyTo: "**"
 # PyGhidra Fallback
 
 - Use the local PyGhidra toolkit in `tools/pyghidra_crusader` when MCP is missing an operation such as function creation, deletion, or batched scripted edits.
+- If Ghidra was started with Python enabled, prefer live MCP `run_readonly_script(...)` for one-off inspection first; drop to the local PyGhidra CLI only when the work needs write access or MCP still lacks the required operation.
 - When PyGhidra is needed because MCP lacks a required operation, append a note to `ghidra_mcp_wishlist.md` in the same batch if the gap is not already documented.
 - The workspace-local Python environment for this toolkit is `.venv-pyghidra311`, created from `C:\Users\Maddo\.pyenv\pyenv-win\versions\3.11.6\python.exe` and installed from the bundled Ghidra 12.0.4 offline packages.
 - Default install dir for the toolkit is `I:\Apps\ghidra_12.0.4_PUBLIC`.

.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.

.github/skills/pyghidra-ghidra-ops/SKILL.md

@@ -30,9 +30,12 @@ Use this skill when Ghidra MCP is missing a needed operation and you need native
 
 - Stay conservative. Use the same rename and batch-size rules as the main Ghidra workflow.
 - Prefer one focused plan or 1-5 direct edits at a time.
+- If a live MCP session was started with Python enabled, use live `run_readonly_script(...)` for quick inspection before falling back to the local CLI; reserve the local PyGhidra path for write-side work or still-missing MCP capabilities.
 - Write operations require the project to be openable for modification. If `Crusader.lock` is present because the GUI owns the project, close Ghidra first or work on a copy.
 - Keep `crusader_decompilation_notes.md` updated after verified repair batches.
 
+For 16-bit NE decompiler failures after prototype edits or function recreation, inspect direct callees before assuming the caller frame is corrupt. In this repo a broken caller (`1420:1499`) was only fixed after repairing a shared callee (`1000:42e2`) whose pointer-return prototype had decompiled with a hidden `__return_storage_ptr__` and poisoned the caller stack model.
+
 Refresh the local PyGhidra environment when the bundled Ghidra version changes:
 
 ```powershell