From 80c4b27437122a605ffc187123a4375b300280f6 Mon Sep 17 00:00:00 2001
From: Teknium <127238744+teknium1@users.noreply.github.com>
Date: Tue, 12 May 2026 18:44:33 -0700
Subject: [PATCH] docs(lsp): document follow-up fixes from #24630 (#24709)

- Note that typescript-language-server pulls in the typescript SDK
  automatically (peer-dep relationship was previously implicit and
  caused initialize failures when the SDK was absent).
- Add a Troubleshooting entry for the new Backend warnings section
  in hermes lsp status, with the shellcheck install commands across
  apt / brew / scoop.

Reflects what shipped in PR #24630.
---
 website/docs/user-guide/features/lsp.md | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/website/docs/user-guide/features/lsp.md b/website/docs/user-guide/features/lsp.md
index ef0f403d202..bb54003b11a 100644
--- a/website/docs/user-guide/features/lsp.md
+++ b/website/docs/user-guide/features/lsp.md
@@ -92,6 +92,13 @@ manager makes sense for that language (rustup, ghcup, opam, brew,
 …). Hermes auto-detects the binary on PATH or in
 `<HERMES_HOME>/lsp/bin/`.
 
+A few servers are installed alongside a peer dependency that npm
+won't auto-pull. The current case is `typescript-language-server`,
+which requires the `typescript` SDK importable from the same
+`node_modules` tree — Hermes installs both packages together when you
+run `hermes lsp install typescript` or auto-install fires on first
+use.
+
 ## CLI
 
 ```
@@ -207,6 +214,24 @@ The binary isn't on PATH and isn't in `<HERMES_HOME>/lsp/bin/`. Run
 `hermes lsp install <server_id>` to attempt an auto-install, or
 install the binary manually through the language's normal toolchain.
 
+**`Backend warnings` section in `hermes lsp status`**
+
+Some servers ship as thin wrappers around an external CLI for actual
+diagnostics — they spawn cleanly and accept requests but never emit
+errors when the sidecar binary is missing. The most common case is
+`bash-language-server`, which delegates diagnostics to `shellcheck`.
+When `hermes lsp status` shows a `Backend warnings` section, install
+the named tool through your OS package manager:
+
+```
+apt install shellcheck      # Debian / Ubuntu
+brew install shellcheck     # macOS
+scoop install shellcheck    # Windows
+```
+
+The same warning is logged once at server spawn time in
+`~/.hermes/logs/agent.log`.
+
 **Server starts but never returns diagnostics**
 
 Check `~/.hermes/logs/agent.log` for `[agent.lsp.client]` entries —