docs: clarify macOS od command collision (#5219)

Author: zycaskevin

README.md

@@ -301,6 +301,12 @@ After install: the app auto-detects every coding-agent CLI on your `PATH`, loads
 
 You can use Open Design without ever opening the GUI — call it as a skill, plugin, or MCP server inside Claude Code, Codex, Cursor, Copilot, OpenClaw, Antigravity, Hermes, Kimi, and more.
 
+If you installed the macOS desktop app via the DMG or Homebrew cask, your shell
+may still resolve `od` to Apple's built-in `/usr/bin/od` octal-dump utility. In
+that case, open **Settings → MCP server** in the desktop app and copy the
+client-specific snippet; it uses absolute paths and does not rely on the bare
+`od` command.
+
 ```bash
 # One-line install into the agent you're using:
 od mcp install <agent>
@@ -316,9 +322,10 @@ curl -fsSL https://open-design.ai/install.sh | sh -s <agent>
 hosted URL returns shell instead of the landing-page HTML fallback and fails
 fast if your shell resolves a non-Open-Design `od` binary.
 
-> **WSL2 users:** If your coding-agent CLIs run inside WSL2, follow the
-> [`WSL2 setup guide`](docs/wsl-setup.md) first. Linux's `/usr/bin/od` can
-> shadow Open Design's `od` command.
+> **macOS / WSL2 users:** `/usr/bin/od` is a system octal-dump command and can
+> shadow Open Design's `od` command. Desktop-app users should prefer the
+> **Settings → MCP server** snippet; WSL2 users should follow the
+> [`WSL2 setup guide`](docs/wsl-setup.md) first.
 
 Then, inside the agent:
 
@@ -388,7 +395,7 @@ od skill list --scenario marketing
 
 **Why MCP?** Exporting and re-attaching a zip every iteration breaks flow. MCP exposes the design source directly — the agent always sees the live file.
 
-**For an agent starting from scratch,** the installer places `~/.config/<agent>/open-design.json` (or the platform equivalent) plus a copy-paste MCP snippet. Cursor gets a one-click deeplink; Claude Code gets a `claude mcp add-json` one-liner; every other agent gets JSON in the schema its config expects. Full per-agent flow → **Settings → MCP server** in the desktop app, or [`docs/agent-adapters.md`](docs/agent-adapters.md).
+**For an agent starting from scratch,** the installer places `~/.config/<agent>/open-design.json` (or the platform equivalent) plus a copy-paste MCP snippet. Cursor gets a one-click deeplink; Claude Code gets a `claude mcp add-json` one-liner; every other agent gets JSON in the schema its config expects. On macOS desktop installs, prefer that Settings snippet over typing bare `od mcp install <agent>` in Terminal, because `/usr/bin/od` may win on PATH. Full per-agent flow → **Settings → MCP server** in the desktop app, or [`docs/agent-adapters.md`](docs/agent-adapters.md).
 
 **Security model.** Read-only by default, the daemon binds to `127.0.0.1`, and SSRF is blocked at the proxy edge. LAN exposure requires an explicit `OD_BIND_HOST` plus `OD_ALLOWED_ORIGINS`. Connector credentials and live-artifact preview routes stay loopback-only regardless.
 

apps/landing-page/public/install.sh

@@ -60,9 +60,14 @@ if [ "${od_probe}" != "open-design-cli:mcp-install:v1" ]; then
   cat >&2 <<EOF
 Open Design install.sh: '${od_path}' does not look like the Open Design CLI.
 
-On Linux and WSL2, /usr/bin/od is usually the coreutils octal-dump command and
-can shadow Open Design's CLI. Put the Open Design CLI earlier on PATH, then
-re-run this command.
+On macOS, Linux, and WSL2, /usr/bin/od is the system octal-dump command and can
+shadow Open Design's CLI. Put the Open Design CLI earlier on PATH, then re-run
+this command.
+
+If you installed the macOS desktop app via the DMG or Homebrew cask, the app
+bundle does not add an 'od' shim to your shell PATH. Launch Open Design and use
+Settings -> MCP server to copy the client-specific install snippet instead;
+that snippet uses absolute paths and avoids the system 'od' collision.
 EOF
   exit 1
 fi

apps/landing-page/tests/install-sh-static.test.ts

@@ -85,6 +85,8 @@ exit 0
 
     assert.equal(result.status, 1);
     assert.match(result.stderr, /does not look like the Open Design CLI/);
+    assert.match(result.stderr, /macOS, Linux, and WSL2/);
+    assert.match(result.stderr, /Settings -> MCP server/);
     assert.throws(() => readFileSync(argvOut, 'utf8'), /ENOENT/);
   } finally {
     rmSync(tmp, { recursive: true, force: true });