docs: add common installation troubleshooting entries

[96528025]

Summary

Closes #364

Adds four new entries to the Installation section of docs/reference/troubleshooting.md, covering the most common failures new users encounter before nemoclaw onboard even runs:

• Node.js version too old — check version, upgrade via nvm
• Docker not running — systemctl start docker on Linux, Docker Desktop on macOS
• npm EACCES permission errors — configure npm prefix instead of using sudo
• Port already in use — identify and stop the conflicting process with lsof

Also adds a Troubleshooting link at the end of docs/get-started/quickstart.md so users who hit problems during installation can find the guide immediately.

Test plan

• Read through each new entry and verify the commands are correct
• Confirm the troubleshooting link in quickstart.md resolves to the right page

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Added a "Troubleshooting" section to the Quickstart guide linking to detailed help.
  • Expanded the troubleshooting reference with practical guidance for common setup issues: Node.js version mismatches, Docker not running, npm permission errors, and port conflicts during onboarding.

[coderabbitai]

📝 Walkthrough

Walkthrough

Added troubleshooting guidance: quickstart now links to a Troubleshooting reference and docs/reference/troubleshooting.md gained installation diagnostics for Node.js version (Node.js 20+), Docker daemon, npm permission/prefix setup, and port (18789) conflict resolution. (Documentation-only change.)

Changes

Cohort / File(s)	Summary
Quickstart Doc docs/get-started/quickstart.md	Added a "Troubleshooting" pointer linking to ../reference/troubleshooting.md.
Troubleshooting Reference docs/reference/troubleshooting.md	Inserted markdownlint-disable MD014 and expanded Installation section with subsections for: Node.js version (require Node 20+, node --version, nvm install 20 / nvm use 20), Docker not running (start daemon: sudo systemctl start docker, macOS: wait for Docker Desktop), npm permission errors (avoid sudo, set npm prefix to ~/.npm-global, update PATH and shell rc), and port in use (default gateway port 18789: lsof -i :18789, kill <PID>, kill -9 <PID>).

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Poem

🐇 I hopped through pages, pen in paw,

Tidied paths where new users saw.
Node and Docker, npm and ports,
Little fixes, tiny sorts.
A cheerful thump—onboarding's thaw.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: adding troubleshooting documentation for common installation issues.
Linked Issues check	✅ Passed	The PR comprehensively addresses issue #364 objectives: documents Node.js version mismatches with nvm remediation, Docker daemon startup, npm permission error solutions, and port conflict resolution. A troubleshooting link is added to the quickstart guide.
Out of Scope Changes check	✅ Passed	All changes are directly related to issue #364: troubleshooting documentation for installation failures and a quickstart link. The markdownlint comment is in-scope as a necessary file-level configuration.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

📝 Coding Plan

• Generate coding plan for human review comments

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

docs/reference/troubleshooting.md (1)

45-47: Normalize command-block style to satisfy markdownlint MD014.

The new command blocks use $ prompts without output, which may keep lint warnings active. Consider removing the prompt markers for consistency with strict markdownlint setups.

Also applies to: 52-55, 64-66, 75-79, 89-92

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/reference/troubleshooting.md` around lines 45 - 47, Several fenced
command blocks use a leading "$" prompt (e.g., the block containing "$ node
--version") which triggers markdownlint MD014; update those blocks by removing
the "$" prompt so they contain bare commands (e.g., "node --version") or add
corresponding command output lines, and apply the same change to the other
occurrences noted (blocks around lines 52-55, 64-66, 75-79, 89-92) to normalize
command-block style and satisfy markdownlint.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/reference/troubleshooting.md`:
- Around line 89-92: Replace the abrupt "kill <PID>" instruction in the
troubleshooting snippet with a safer, more beginner-friendly step: recommend
sending a graceful SIGTERM (kill -15 <PID>) first and add a one-line guidance to
verify the PID belongs to the conflicting process (e.g., check the process
command/owner) before terminating; update the snippet around the lsof -i :18789
line and include the confirmatory sentence immediately after the kill
instruction.

---

Nitpick comments:
In `@docs/reference/troubleshooting.md`:
- Around line 45-47: Several fenced command blocks use a leading "$" prompt
(e.g., the block containing "$ node --version") which triggers markdownlint
MD014; update those blocks by removing the "$" prompt so they contain bare
commands (e.g., "node --version") or add corresponding command output lines, and
apply the same change to the other occurrences noted (blocks around lines 52-55,
64-66, 75-79, 89-92) to normalize command-block style and satisfy markdownlint.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 827ec814-6764-48d9-9f99-0ff1a1b42ba9

📥 Commits

Reviewing files that changed from the base of the PR and between 9513eca and b93b9fc.

📒 Files selected for processing (2)

• docs/get-started/quickstart.md
• docs/reference/troubleshooting.md

[coderabbitai]

Actionable comments posted: 1

♻️ Duplicate comments (1)

docs/reference/troubleshooting.md (1)

87-94: ⚠️ Potential issue | 🟡 Minor

Prefer graceful termination first for port-conflict resolution.

Line 91 still defaults to kill <PID>. For beginner safety, use kill -15 <PID> first, then keep kill -9 only as fallback.

Suggested doc patch

 Identify the conflicting process, verify it is safe to stop, and terminate it:

 ```console
 $ lsof -i :18789
-$ kill <PID>
+$ kill -15 <PID>

If the process does not exit, use kill -9 <PID> to force-terminate it.

</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

Verify each finding against the current code and only fix it if needed.

In @docs/reference/troubleshooting.md around lines 87 - 94, Update the
port-conflict termination example to recommend a graceful SIGTERM before a
forceful kill: replace the immediate "kill " example following "lsof -i
:18789" with "kill -15 " (SIGTERM) and retain "kill -9 " only as the
fallback if the process does not exit; ensure the doc text around the commands
reflects this order (the snippet containing "lsof -i :18789", "kill "
should be changed to use "kill -15 " instead).

</details>

</blockquote></details>

</blockquote></details>

<details>
<summary>🧹 Nitpick comments (1)</summary><blockquote>

<details>
<summary>docs/reference/troubleshooting.md (1)</summary><blockquote>

`25-25`: **Consider adding a network/proxy/firewall install subsection to fully meet issue scope.**

Issue `#364` objectives include surfacing network/proxy/firewall guidance; Installation currently covers four cases but not that one.  
 

I can draft a concise subsection with proxy env vars, firewall checks, and connectivity diagnostics if helpful.

<details>
<summary>🤖 Prompt for AI Agents</summary>

Verify each finding against the current code and only fix it if needed.

In @docs/reference/troubleshooting.md at line 25, Add a new "Network / Proxy /
Firewall" subsection under the existing "Installation" header that addresses
Issue #364 by listing required proxy environment variables (e.g., HTTP_PROXY,
HTTPS_PROXY, NO_PROXY), common firewall/port checks and commands to verify them,
and basic connectivity diagnostics (curl/wget tests, DNS resolution, and
traceroute) with concise examples and remediation steps; ensure the subsection
follows the same tone and formatting as the other Installation cases and links
back to the main troubleshooting section.

</details>

</blockquote></details>

</blockquote></details>

<details>
<summary>🤖 Prompt for all review comments with AI agents</summary>

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @docs/reference/troubleshooting.md:

• Line 46: The code fence commands like "$ node --version" (and the other
  $-prefixed command lines around 53-54, 65, 76-78, 90-91) are triggering
  markdownlint MD014; fix by either removing the leading "$ " from those inline
  command lines or by disabling MD014 for this document (add a top-of-file HTML
  comment like or wrap only those blocks with

... ).

Update the occurrences of the strings starting with "$ " (e.g., "$ node
--version") to one of these two options consistently across the listed blocks.

---

Duplicate comments:
In @docs/reference/troubleshooting.md:

• Around line 87-94: Update the port-conflict termination example to recommend a
  graceful SIGTERM before a forceful kill: replace the immediate "kill "
  example following "lsof -i :18789" with "kill -15 " (SIGTERM) and retain
  "kill -9 " only as the fallback if the process does not exit; ensure the
  doc text around the commands reflects this order (the snippet containing "lsof
  -i :18789", "kill " should be changed to use "kill -15 " instead).

---

Nitpick comments:
In @docs/reference/troubleshooting.md:

• Line 25: Add a new "Network / Proxy / Firewall" subsection under the existing
  "Installation" header that addresses Issue #364 by listing required proxy
  environment variables (e.g., HTTP_PROXY, HTTPS_PROXY, NO_PROXY), common
  firewall/port checks and commands to verify them, and basic connectivity
  diagnostics (curl/wget tests, DNS resolution, and traceroute) with concise
  examples and remediation steps; ensure the subsection follows the same tone and
  formatting as the other Installation cases and links back to the main
  troubleshooting section.

</details>

---

<details>
<summary>ℹ️ Review info</summary>

<details>
<summary>⚙️ Run configuration</summary>

**Configuration used**: Path: .coderabbit.yaml

**Review profile**: CHILL

**Plan**: Pro

**Run ID**: `a185d9e0-ed13-481c-a5e3-918a9388aa44`

</details>

<details>
<summary>📥 Commits</summary>

Reviewing files that changed from the base of the PR and between b93b9fc3b82fe596dd92e5bb166d0fbe19c661f2 and 29c275929654e7967bb13bb7880d55fbbb7d079a.

</details>

<details>
<summary>📒 Files selected for processing (1)</summary>

* `docs/reference/troubleshooting.md`

</details>

</details>

<!-- This is an auto-generated comment by CodeRabbit for review status -->

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs/reference/troubleshooting.md (1)

27-98: ⚠️ Potential issue | 🟡 Minor

Installation troubleshooting still misses proxy/firewall diagnostics from the linked objective.

The new Installation section is useful, but it still doesn’t add a concrete network/proxy/firewall failure entry (checks + remediation), which was explicitly called out in Issue #364 objectives.

If helpful, I can draft a compact subsection with common symptoms (ETIMEDOUT, ECONNRESET, TLS/proxy errors), quick diagnostics, and proxy env var examples.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/reference/troubleshooting.md` around lines 27 - 98, Add a compact
"Network / proxy / firewall" subsection under the Installation heading that
addresses common connectivity failures (ETIMEDOUT, ECONNRESET, TLS/proxy errors)
and provides concrete diagnostics and remediation: list quick checks
(curl/openssl to target endpoints, traceroute, check Docker network, verify port
18789), show how to inspect and set HTTP_PROXY/HTTPS_PROXY/NO_PROXY env vars and
npm proxy config, and include firewall steps (ufw/systemctl rules and how to
open/allow the gateway port) plus brief example commands and expected outcomes;
update the Installation doc (near the "Port already in use" and Node.js/docker
checks) to include these checks so readers can diagnose and fix
network/proxy/firewall issues referenced by Issue `#364`.

♻️ Duplicate comments (1)

docs/reference/troubleshooting.md (1)

91-97: ⚠️ Potential issue | 🟡 Minor

Use graceful termination first in the port-conflict example.

At Line 93, prefer kill -15 <PID> before escalating to kill -9, to reduce accidental disruption for beginners.

Suggested doc tweak

 ```console
 $ lsof -i :18789
-$ kill <PID>
+$ kill -15 <PID>

If the process does not exit, use kill -9 <PID> to force-terminate it.

</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

Verify each finding against the current code and only fix it if needed.

In @docs/reference/troubleshooting.md around lines 91 - 97, Update the
port-conflict troubleshooting example to suggest a graceful termination first:
replace the plain "kill " invocation with "kill -15 " (SIGTERM) in the
example block, and keep the existing fallback sentence that recommends "kill -9
" only if the process does not exit; this targets the example command shown
in the docs reference/troubleshooting.md snippet.

</details>

</blockquote></details>

</blockquote></details>

<details>
<summary>🤖 Prompt for all review comments with AI agents</summary>

Verify each finding against the current code and only fix it if needed.

Outside diff comments:
In @docs/reference/troubleshooting.md:

• Around line 27-98: Add a compact "Network / proxy / firewall" subsection under
  the Installation heading that addresses common connectivity failures (ETIMEDOUT,
  ECONNRESET, TLS/proxy errors) and provides concrete diagnostics and remediation:
  list quick checks (curl/openssl to target endpoints, traceroute, check Docker
  network, verify port 18789), show how to inspect and set
  HTTP_PROXY/HTTPS_PROXY/NO_PROXY env vars and npm proxy config, and include
  firewall steps (ufw/systemctl rules and how to open/allow the gateway port) plus
  brief example commands and expected outcomes; update the Installation doc (near
  the "Port already in use" and Node.js/docker checks) to include these checks so
  readers can diagnose and fix network/proxy/firewall issues referenced by Issue
  #364.

---

Duplicate comments:
In @docs/reference/troubleshooting.md:

• Around line 91-97: Update the port-conflict troubleshooting example to suggest
  a graceful termination first: replace the plain "kill " invocation with
  "kill -15 " (SIGTERM) in the example block, and keep the existing fallback
  sentence that recommends "kill -9 " only if the process does not exit; this
  targets the example command shown in the docs reference/troubleshooting.md
  snippet.

</details>

---

<details>
<summary>ℹ️ Review info</summary>

<details>
<summary>⚙️ Run configuration</summary>

**Configuration used**: Path: .coderabbit.yaml

**Review profile**: CHILL

**Plan**: Pro

**Run ID**: `40ad9eca-5283-47c0-8a5c-e140dcbe39e5`

</details>

<details>
<summary>📥 Commits</summary>

Reviewing files that changed from the base of the PR and between 29c275929654e7967bb13bb7880d55fbbb7d079a and ac054fd50a954741e316f7c4111fddaf24939a49.

</details>

<details>
<summary>📒 Files selected for processing (1)</summary>

* `docs/reference/troubleshooting.md`

</details>

</details>

<!-- This is an auto-generated comment by CodeRabbit for review status -->