Resolves #19 and #22.

README.md

@@ -11,22 +11,34 @@ RocketSmith is an end-to-end model-rocket toolchain exposed as an MCP extension.
 
 ## Install
 
-### Claude Code (plugin)
+**Prerequisites (all platforms):**
+- [uv](https://docs.astral.sh/uv/getting-started/installation/) — RocketSmith uses `uv` to manage its Python environment. Install it before proceeding.
+- A GitHub SSH key added to your account — required to clone the plugin repository. See [Generating a new SSH key](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent).
 
-**Prerequisites:** Create a GitHub SSH key and add it to your account before proceeding — see [Generating a new SSH key](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent).
+### Claude Code (plugin)
 
-Inside a Claude Code session, add the marketplace and install the plugin:
+Inside a Claude Code session, add the marketplace and install the plugin at **user scope**:
 
 ```
 /plugin marketplace add ppak10/RocketSmith
 ```
 
 ```
-/plugin install rocketsmith@rocketsmith
+/plugin install rocketsmith@rocketsmith --scope user
 ```
 
 After installing, reload plugins and verify the MCP server is connected with `/reload-plugins` and `/mcp`
 
+**Updating to a new version:** Uninstall the existing plugin first, then reinstall:
+
+```
+/plugin uninstall rocketsmith@rocketsmith
+```
+
+```
+/plugin install rocketsmith@rocketsmith --scope user
+```
+
 ### [Gemini CLI (extension)](https://geminicli.com/extensions/?name=ppak10RocketSmith)
 
 ```bash
@@ -41,6 +53,24 @@ gemini extensions install https://github.com/ppak10/RocketSmith
 
 See [Installation](https://github.com/ppak10/RocketSmith/wiki/Installation) for platform-specific setup and troubleshooting.
 
+## Troubleshooting
+
+### Windows — OpenRocket calls are very slow or appear to hang
+
+OpenRocket runs on a JVM. On Windows, the first `openrocket_*` call in a session pays a JVM cold-start cost of **67 seconds to 6 minutes**. This is normal — the tool will eventually return. Do not cancel the call or retry early; let it finish. Subsequent calls in the same session are faster once the JVM is warm.
+
+### Windows — `rocketsmith_setup` fails with `[WinError 87] The parameter is incorrect`
+
+This was a bug in path resolution on Windows where `Path.resolve()` raised `OSError` for certain path types. It is fixed in the current version. If you hit it on an older version, call `rocketsmith_setup(action="check")` first (no `project_dir`), confirm `ready: true`, then call again with `project_dir`.
+
+### Claude Code — agent continuation fails ("SendMessage not found")
+
+Claude Code requires **v2.1.77 or later** for inter-agent `SendMessage` to work. On older versions, attempting to continue a spawned subagent by `agentId` will fail because the tool doesn't exist yet. Update Claude Code to the latest release to resolve this.
+
+### MCP server disconnects mid-session
+
+Rejecting a pending rocketsmith tool call can cause the MCP server to disconnect, disabling all rocketsmith tools for the rest of the session. If this happens, restart the MCP server: in Claude Code run `/mcp`, find the rocketsmith server, and reconnect. In Gemini CLI, restart the session.
+
 ## Documentation
 
 - [Home](https://github.com/ppak10/RocketSmith/wiki/Home) — pipeline overview, domain agents, MCP tool list

src/rocketsmith/mcp/setup.py

@@ -105,10 +105,10 @@ def rocketsmith_setup(
         gui_error = None
 
         if project_dir is not None:
-            from rocketsmith.mcp.utils import set_project_dir
+            from rocketsmith.mcp.utils import safe_resolve, set_project_dir
 
             set_project_dir(project_dir)
-            gui_url, gui_pid, gui_error = _start_gui(project_dir.resolve())
+            gui_url, gui_pid, gui_error = _start_gui(safe_resolve(project_dir))
 
         if action == "check":
             status = _check()

src/rocketsmith/mcp/utils.py

@@ -19,6 +19,21 @@ def _cleanup_pid_file() -> None:
         pass
 
 
+def safe_resolve(path: Path) -> Path:
+    """Resolve a path to absolute form without raising on Windows.
+
+    ``Path.resolve()`` on Windows calls ``GetFinalPathNameByHandle``, which can
+    raise ``OSError: [WinError 87] The parameter is incorrect`` for certain path
+    types (long paths, paths with trailing characters, non-existent roots).
+    ``os.path.abspath`` performs the same ``..``-collapse and absolutisation
+    without that API call and is safe on all platforms.
+    """
+    try:
+        return path.resolve()
+    except OSError:
+        return Path(os.path.abspath(path))
+
+
 def set_project_dir(path: Path) -> None:
     """Persist the project directory for this MCP server process (PID-scoped).
 
@@ -28,7 +43,7 @@ def set_project_dir(path: Path) -> None:
     """
     global _atexit_registered
     _ROCKETSMITH_DIR.mkdir(parents=True, exist_ok=True)
-    _pid_file().write_text(str(path.resolve()))
+    _pid_file().write_text(str(safe_resolve(path)))
     if not _atexit_registered:
         atexit.register(_cleanup_pid_file)
         _atexit_registered = True