docs(troubleshooting): clarify Hermes API forward recovery

Signed-off-by: Rebecca Sliter <571084+rsliter@users.noreply.github.com>

Author: rsliter

docs/reference/troubleshooting.mdx

@@ -4893,7 +4893,7 @@ Expected output:
 Point an OpenAI-compatible client at `http://127.0.0.1:8642/v1` for chat completions.
 For terminal use, run `nemohermes launch <name>`.
 
-### Onboarding Reports "Hermes is not ready" With an Unreachable API Port
+### Onboarding Reports Hermes Is Not Ready With an Unreachable API Port
 
 Deployment verification probes the OpenAI-compatible API inside the sandbox and through its host-side API port forward.
 When the API answers inside the sandbox but its host-side API port forward is unreachable, verification reports the API port forward as failed.
@@ -4904,7 +4904,12 @@ Onboarding then prints `Hermes is not ready` and exits with a nonzero status:
   The OpenAI-compatible API on port 8642 is not reachable from the host. Run: openshell forward start --background 8642 <name>
 ```
 
-The API remains reachable inside the sandbox.
+Use the forward recovery below only when the in-sandbox `gateway` check passed.
+The output omits passing checks, so confirm that it contains no `gateway` failure.
+If the output contains a `gateway` failure, follow that diagnostic first.
+Do not restart the host forward until the in-sandbox API responds.
+
+When the `gateway` check passed and only the `api` check failed, the API remains reachable inside the sandbox.
 Each Hermes sandbox owns an API port allocated from `8642` through `8652`, so use the port from the `api` diagnostic instead of assuming the default.
 First, list the active OpenShell port forwards:
 
@@ -4927,10 +4932,12 @@ Do not run the health probe after `openshell forward start` fails.
 After `openshell forward start` exits with status `0`, probe the health endpoint:
 
 ```bash
-curl -sf http://127.0.0.1:<port>/health
+curl -sS -o /dev/null -w '%{http_code}\n' --max-time 3 http://127.0.0.1:<port>/health
 ```
 
-If the health probe still refuses connections, rerun `$$nemoclaw onboard` to collect fresh verification diagnostics.
+An HTTP status of `200` or `401` means the host port forward is reachable.
+Any other status, `000`, or connection failure requires fresh diagnostics.
+Rerun `$$nemoclaw onboard` and follow the reported `gateway` or `api` failure.
 
 ### `docker port` shows no mapping for 8642 even though forwarding works
 

src/lib/verify-deployment.ts

@@ -319,7 +319,7 @@ function hasSeparateAgentApiPort(chain: DashboardDeliveryChain): boolean {
  * The in-sandbox gateway probe only proves the API listens inside the sandbox;
  * it says nothing about the host forward operators actually connect through.
  * Onboarding advertises that host URL on the success screen, so it has to be
- * probed from the host too — otherwise a failed API forward leaves onboarding
+ * probed from the host too. Otherwise, a failed API forward leaves onboarding
  * reporting a healthy deployment while the documented endpoint refuses every
  * connection (#9290).
  */