README.md (2)

188-191: Add blank line before horizontal rule to fix Markdown structure.

The horizontal rule --- immediately follows the blockquote without a blank line, which causes the static analysis warning. Adding a blank line improves the document structure.

📝 Suggested fix

 > When using local inference (Ollama or vLLM), the inference service binds to `0.0.0.0` so that containers can reach it via `host.openshell.internal`. This means the service is reachable from your local network, not just localhost. This is required for the sandbox architecture but should be considered in shared or untrusted network environments.
+
 ---

🤖 Prompt for AI Agents

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

In `@README.md` around lines 188 - 191, The blockquote beginning with "> **⚠️
Network exposure**" is directly adjacent to the horizontal rule '---', causing a
Markdown structure warning; insert a single blank line between the end of that
blockquote and the '---' horizontal rule so the separator is on its own line and
the document renders/analyses correctly.

---

176-180: Use console code block with $ prompt for CLI examples.

The coding guidelines specify CLI code blocks should use the console language tag with $ prompt prefix for consistency with the documentation style.

📝 Suggested fix

-```bash
-export NEMOCLAW_GATEWAY_PORT=9080
-export NEMOCLAW_VLLM_PORT=9000
-nemoclaw onboard
-```
+```console
+$ export NEMOCLAW_GATEWAY_PORT=9080
+$ export NEMOCLAW_VLLM_PORT=9000
+$ nemoclaw onboard
+```

As per coding guidelines: "CLI code blocks must use the console language tag with $ prompt prefix. Flag bash or shell for CLI examples."

🤖 Prompt for AI Agents

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

In `@README.md` around lines 176 - 180, Replace the current bash code block in
README.md (the block showing NEMOCLAW_GATEWAY_PORT, NEMOCLAW_VLLM_PORT, and the
`nemoclaw onboard` command) with a console-style CLI example: change the fence
from ```bash to ```console and prefix each command line with a `$ ` prompt so
the three lines become `$ export NEMOCLAW_GATEWAY_PORT=9080`, `$ export
NEMOCLAW_VLLM_PORT=9000`, and `$ nemoclaw onboard`, then close the block with
```.

docs/reference/port-configuration.md (1)

23-24: Consider active voice for the introduction.

Line 24 uses passive voice ("are configurable"). Per coding guidelines, active voice is preferred.

📝 Suggested fix

 NemoClaw uses four network ports.
-All ports are configurable through environment variables or a `.env` file at the project root.
+You can configure all ports through environment variables or a `.env` file at the project root.

As per coding guidelines: "Active voice required. Flag passive constructions."

🤖 Prompt for AI Agents

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

In `@docs/reference/port-configuration.md` around lines 23 - 24, Change the
passive sentence "All ports are configurable through environment variables or a
`.env` file at the project root." to an active-voice phrasing; locate the
sentence text and replace it with something like "Configure all ports using
environment variables or a `.env` file at the project root" (or similar active
construction) so the intro reads actively after "NemoClaw uses four network
ports."

docs/reference/troubleshooting.md (2)

93-94: Use second-person wording in this troubleshooting intro.

The new paragraph switches to an impersonal “onboarding fails …” description instead of telling the reader what they see. Keep the guide’s voice consistent and address the reader directly here.

As per coding guidelines, "Second person ("you") when addressing the reader."

🤖 Prompt for AI Agents

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

In `@docs/reference/troubleshooting.md` around lines 93 - 94, The troubleshooting
intro uses impersonal phrasing; change the sentence "If another process is bound
to one of these ports, onboarding fails with a message identifying the
conflicting process." to second-person voice so it addresses the reader directly
(e.g., "If another process is bound to one of these ports, you will see
onboarding fail with a message identifying the conflicting process.")—update the
sentence in the docs/reference/troubleshooting.md paragraph so the guide
consistently uses "you" when addressing the reader.

---

110-115: Wrap the default port values in inline code.

These are literal configuration values in the table, so format them the same way as the environment variable names in the next column.

As per coding guidelines, "CLI commands, file paths, flags, parameter names, and values must use inline code formatting."

🤖 Prompt for AI Agents

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

In `@docs/reference/troubleshooting.md` around lines 110 - 115, The default port
numeric values (8080, 8000, 18789, 11434) in the table are not formatted as
inline code; update the table so each default port is wrapped in backticks
(e.g., `8080`) to match the inline code style used for the env vars like
NEMOCLAW_GATEWAY_PORT and comply with the project's formatting guideline for
CLI/parameter values.

README.md (1)

184-190: Remove the emoji callout labels and fix the blockquote break.

The ℹ️ and ⚠️ labels violate the Markdown guideline for technical prose, and the blank quoted separator in this block is what MD028 is warning about on Line 187.

As per coding guidelines, "**/*.md: ... No emoji in technical prose."

🤖 Prompt for AI Agents

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

In `@README.md` around lines 184 - 190, Remove the emoji callout labels and the
extra blank quote line in the README block: replace the quoted lines starting
with "**ℹ️ Note**" and "**⚠️ Network exposure**" so they use plain text headings
(e.g., "**Note**" and "**Network exposure**") without emojis, and ensure there
is no empty blockquote separator between the two quoted paragraphs so the
blockquote is continuous (this will satisfy MD028 and the "no emoji in technical
prose" guideline).

.env.example (1)

5-8: Optional: reorder keys to satisfy dotenv-linter UnorderedKey warning.

This is non-blocking, but reordering avoids persistent lint noise.

Proposed diff

 NEMOCLAW_DASHBOARD_PORT=18789
 NEMOCLAW_GATEWAY_PORT=8080
-NEMOCLAW_VLLM_PORT=8000
 NEMOCLAW_OLLAMA_PORT=11434
+NEMOCLAW_VLLM_PORT=8000

🤖 Prompt for AI Agents

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

In @.env.example around lines 5 - 8, Reorder the environment variable lines so
they follow dotenv-linter's expected ordering (alphabetical by key) to remove
the UnorderedKey warning; specifically reorder the keys NEMOCLAW_DASHBOARD_PORT,
NEMOCLAW_GATEWAY_PORT, NEMOCLAW_OLLAMA_PORT, NEMOCLAW_VLLM_PORT into
alphabetical order (e.g., NEMOCLAW_DASHBOARD_PORT, NEMOCLAW_GATEWAY_PORT,
NEMOCLAW_OLLAMA_PORT, NEMOCLAW_VLLM_PORT → adjust as needed to be strictly
sorted) and commit the updated .env.example. Ensure no other unrelated changes
are made.

bin/lib/nim.js (1)

188-209: Minor inconsistency in port coercion.

In waitForNimHealth (line 159), the port is coerced with Number(port) before use, but in nimStatus (line 200), the port is used directly in the template literal. While this works because the port should already be a number, consider applying consistent coercion for defensive coding.

♻️ Optional consistency fix

 function nimStatus(sandboxName, port = VLLM_PORT) {
   const name = containerName(sandboxName);
+  const safePort = Number(port);
   try {
     const state = runCapture(
       `docker inspect --format '{{.State.Status}}' ${shellQuote(name)} 2>/dev/null`,
       { ignoreError: true }
     );
     if (!state) return { running: false, container: name };

     let healthy = false;
     if (state === "running") {
-      const health = runCapture(`curl -sf http://localhost:${port}/v1/models 2>/dev/null`, {
+      const health = runCapture(`curl -sf http://localhost:${safePort}/v1/models 2>/dev/null`, {
         ignoreError: true,
       });
       healthy = !!health;
     }

🤖 Prompt for AI Agents

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

In `@bin/lib/nim.js` around lines 188 - 209, nimStatus uses the port directly in
the curl template while waitForNimHealth coerces it via Number(port); make this
consistent and defensive by coercing the port at the top of nimStatus (e.g.,
const p = Number(port) or similar) and use p when building the curl/runCapture
call and any other place the port is interpolated; update nimStatus (function
name) so the default param remains VLLM_PORT but all runtime uses use the
numeric value to avoid string/formatting issues with runCapture/curl.

docs/reference/port-configuration.md (2)

24-24: Passive voice detected.

Line 24 uses passive voice: "All ports are configurable."

Consider active voice: "You can configure all ports through environment variables or a .env file at the project root."

🤖 Prompt for AI Agents

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

In `@docs/reference/port-configuration.md` at line 24, Replace the passive
sentence "All ports are configurable through environment variables or a `.env`
file at the project root." with an active-voice instruction such as "You can
configure all ports through environment variables or a `.env` file at the
project root." in docs/reference/port-configuration.md to improve clarity.

---

54-54: Passive voice detected.

Line 54 uses passive voice: "The .env file is gitignored and not committed to the repository."

Consider: "Git ignores the .env file, so your changes remain local."

🤖 Prompt for AI Agents

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

In `@docs/reference/port-configuration.md` at line 54, Replace the passive
sentence "The `.env` file is gitignored and not committed to the repository."
with an active-voice version; for example, change it to "Git ignores the `.env`
file, so your changes remain local." Update the exact string in the docs to use
that active phrasing (refer to the sentence "The `.env` file is gitignored and
not committed to the repository.") so the intent is clearer and uses active
voice.

scripts/start-services.sh (1)

19-24: Minor inconsistency with the documented fallback chain.

The documented fallback chain (in docs/reference/port-configuration.md lines 73-76) is:

1. NEMOCLAW_DASHBOARD_PORT
2. DASHBOARD_PORT
3. PUBLIC_PORT
4. 18789

This script's fallback omits PUBLIC_PORT:

DASHBOARD_PORT="${NEMOCLAW_DASHBOARD_PORT:-${DASHBOARD_PORT:-18789}}"

If PUBLIC_PORT is intentionally excluded here (since this script focuses on services rather than the dashboard itself), consider adding a comment to clarify. Otherwise:

♻️ Align with the documented fallback chain

-DASHBOARD_PORT="${NEMOCLAW_DASHBOARD_PORT:-${DASHBOARD_PORT:-18789}}"
+DASHBOARD_PORT="${NEMOCLAW_DASHBOARD_PORT:-${DASHBOARD_PORT:-${PUBLIC_PORT:-18789}}}"

🤖 Prompt for AI Agents

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

In `@scripts/start-services.sh` around lines 19 - 24, The DASHBOARD_PORT
assignment omits the documented PUBLIC_PORT fallback; update the expansion so
DASHBOARD_PORT="${NEMOCLAW_DASHBOARD_PORT:-${DASHBOARD_PORT:-${PUBLIC_PORT:-18789}}}"
to match the documented chain (referencing NEMOCLAW_DASHBOARD_PORT,
DASHBOARD_PORT, PUBLIC_PORT), or if omission was intentional, add a short
comment above the DASHBOARD_PORT line stating why PUBLIC_PORT is excluded to
avoid confusion.