docs(grok): raise startup_timeout_sec before the first npx run (closes #144)

[VickyXAI]

Closes #144, reported by @0xCheetah1.

The problem

Grok waits startup_timeout_sec for an MCP server to answer and defaults to 30. A cold npx -y @blockrun/mcp@latest has to download this package and its fifteen direct dependencies before the server can say anything, so a first-time user is running a race nobody told them about. Lose it and grok mcp doctor blockrun reports server timed out (no response within 30s) while the UI shows blockrun [unavailable] — an install that works, is still downloading, and is indistinguishable from broken.

What I verified before writing it down

• The config key and the default. xAI's MCP docs confirm ~/.grok/config.toml, the [mcp_servers.<name>] table, and startup_timeout_sec = 30 as the default. They document the npx-first-run timeout case themselves.
• The timing, on my own machine. Cold with an empty npm cache: 16.6s. Warm, same cache: 8.8s. The reporter measured 42-46s cold on a shared box.

That spread is the finding, so the docs give the range and the cause rather than one machine's number. Under 30s here, over it there — which is exactly why a user hits it intermittently and concludes the package is broken.

What changed

Docs only, in three places:

• README — a Grok row in the client table, and a note under it with the config.toml fix, the npm install -g alternative, and the fact that only the first run pays this cost (npx caches by exact spec).
• skills/blockrun-setup — the same guidance where someone installing actually reads, plus grok mcp add blockrun, blockrun unavailable and mcp server timed out as triggers.
• skills/blockrun-debug — a symptom row that says plainly that nothing was charged, because the server never started, and gives the one-line check that separates "still downloading" from "actually broken": run npx -y @blockrun/mcp@latest in a terminal and see if it answers an initialize line.

One thing I added beyond the report

The trap is not Grok-specific. Any client with a startup timeout can lose the same race against our dependency tree, so the note says so and names the first check. Grok is where it bites hardest because its default is the tightest we know of.

Docs only: 636 tests and typecheck unchanged.

🤖 Generated with Claude Code

https://claude.ai/code/session_01RNqnahSKcBqQemPn5TaMLg