Windows: the dashboard setup silently drops CLIs installed with npm (.cmd shims), and the docs give no Windows install for Codex or Copilot that works #211

What

On Windows the router never starts a CLI through a .cmd or .ps1 shim. That is a deliberate and sound security choice. But the desktop app's first-run path, the dashboard's Set up SemanticRouter, silently drops any CLI that is installed only as a shim. The documented install commands for Codex and Copilot produce exactly that kind of install.

• The documented npm installs produce shims. npm install -g @openai/codex (docs/providers.md:254, the only install step given for Codex) and npm install -g @github/copilot (docs/providers.md:211) create codex.cmd/codex.ps1 and copilot.cmd/copilot.ps1 in %APPDATA%\npm. The router refuses these.

• init explains, but the dashboard setup drops the explanation. init adds a note for this case: "only a script wrapper was found …; install the native codex.exe" (src/SemanticRouter.Hosting/InitCommand.cs:286-289). The dashboard setup runs the same detection but throws the notes away:

  • SetupDetector.DetectAsync collects the notes (src/SemanticRouter.Hosting/SetupDetector.cs:42).
  • It reads them back only for LM Studio and Ollama (Local, line 67).
  • CliAsync (line 77) looks only at lookup.Path.

  So a Windows user with npm-installed Codex or Claude Code sees no Codex or Claude Code card and no reason why. Yet the desktop app is meant to need no command line (docs/desktop.md "Using it").

• The message doesn't say where the .exe comes from. Where the message is shown (init, doctor, the connector error from CliExecutableLookup.Problem in src/SemanticRouter.AspNetCore/Connectors/Cli/CliExecutableLocator.cs:24-28), it says "Install the native binary (codex.exe)" without saying where to get it. The docs are no better:

  • Codex: no Windows route at all.
  • Copilot: "or a native package; on Windows make sure copilot.exe is on PATH".
  • Claude Code: the only one with a concrete Windows instruction, "use the native installer" (docs/providers.md:174).

Evidence

• src/SemanticRouter.Hosting/SetupDetector.cs:38-53 and :74-77: notes are collected, then never used for CLI detections.
• src/SemanticRouter.AspNetCore/Connectors/Cli/CliExecutableLocator.cs:80-86: on Windows only .exe and .com count, and .cmd, .bat and .ps1 are reported as ScriptPath.
• docs/providers.md:211, docs/providers.md:254, docs/host.md:100.
• docs/roadmap.md:45: "The real vendor CLIs have been exercised on Linux only."

Impact

On Windows, where most V1 users are expected to be, two of the three subscription CLIs cannot be set up by following the docs. In the desktop app the failure gives no feedback, so people will report it as "SemanticRouter doesn't find Codex".

Suggested fix

• Return script-wrapper findings from SetupDetector as a detection with a problem state, instead of dropping them. For example, a card that says "Codex: found %APPDATA%\npm\codex.cmd, which the router cannot start safely; install codex.exe from … or set Executable".
• In docs/providers.md, give a supported Windows install for each CLI, tested on Windows 11:
  • Claude Code: the native installer, which puts claude.exe in %USERPROFILE%\.local\bin.
  • Codex: the standalone codex.exe from OpenAI's GitHub releases, or the .exe that the npm package carries, set as Executable.
  • Copilot: the copilot.exe from a WinGet or standalone package, if there is one.
• Optionally, when a shim is found, look for the native .exe that the npm package installs next to it (for example under node_modules\@openai\codex\…). Suggest that path in the message, or use it after checking it is an .exe.

Done when

• On Windows, the dashboard setup shows a CLI that is installed only as a script shim, with what to do about it.
• docs/providers.md has a Windows install route for Claude Code, Codex and Copilot that yields a startable .exe, checked on a Windows machine.
• The "script wrapper" message names where to get the .exe for each preset.