rnxsim 0.1.335 → 0.1.337

package/README.md

@@ -14,7 +14,7 @@ tarball, fetched from the contrast.dev CDN and unpacked into `~/.sootsim`.
 
 What this package gives you:
 
-- the `rnxsim` CLI — the primary debugging and automation surface (inspect the
+- the `rnx` CLI — the primary debugging and automation surface (inspect the
   UI tree, tap elements, capture flows, screenshot, record, run agents)
 - `rnxsim/vite` and `rnxsim/metro` — bundler plugins that serve the installed
   engine runtime from your own dev server
@@ -52,7 +52,7 @@ internally splits into shell, compositor, and tenant workers.
 
 ```mermaid
 graph TD
-  subgraph cli["rnxsim CLI process (short-lived, cli/)"]
+  subgraph cli["rnx CLI process (short-lived, cli/)"]
     BIN["bin.ts (dispatcher + telemetry)"]
     SETUP["commands/setup.ts (guided daemon setup)"]
     RUNTIMECMD["commands/runtime.ts (runtime install/use)"]
@@ -132,11 +132,11 @@ graph TD
 ```
 
 **The CLI process** (`cli/bin.ts`) parses argv, emits invocation telemetry, and
-lazy-imports exactly one command module per run. Bare `rnxsim` and
-`rnxsim setup` own guided one-time machine work: ask which package manager you
+lazy-imports exactly one command module per run. Bare `rnx` and
+`rnx setup` own guided one-time machine work: ask which package manager you
 use for app commands, explain repo-pinned Node versions, recommend a global
 `rnxsim` install, and install the faster background daemon when it is
-missing. `rnxsim open`
+missing. `rnx open`
 ensures the engine runtime exists and starts a local foreground bridge when no
 daemon is reachable, then opens a `WsBridge` (`cli/ws-bridge.ts`) on **port
 7668** and sends JSON commands. Inspection/interaction verbs live in
@@ -147,7 +147,7 @@ Browser sims launch in an isolated Playwright Chrome for Testing profile;
 Electron is the native desktop surface.
 
 **The daemon is one process** — `SootSimBridgeHost` (`src/host/bridge-host.ts`).
-`rnxsim serve` runs it in the foreground; the background daemon is the *same
+`rnx serve` runs it in the foreground; the background daemon is the *same
 process* wrapped with autostart and the `~/.sootsim/daemon.json` lockfile. It is
 an HTTP+WS hub: sims register over WS, CLI clients connect to drive them, and
 the host forwards each command to the targeted sim and relays the reply back. It
@@ -170,10 +170,11 @@ bridge always addresses the **shell worker**, never an undifferentiated sim.
 
 **Two distinct plugin families** round it out, and they must not be conflated:
 
-- The published **`rnxsim/vite`** (`src/vite-plugin-one.ts`, `sootsimPlugin`)
+- The published **`rnxsim/vite`** (`src/vite-plugin-one.ts`, `rnxPlugin`)
   and **`rnxsim/metro`** plugins do one thing: serve the installed runtime at
-  `/__soot/` so an app's own dev server can host the sim shell (the vite plugin
-  can also launch the Electron app).
+  `/__soot/` so an app's own dev server can host the sim shell. The vite
+  plugin's `open: true` option also launches the simulator when the dev server
+  starts (skipped when `CI` or `SOOTSIM_NO_OPEN` is set).
 - The internal **`sootsim()`** plugin (`src/vite-plugin.ts`) is a separate, much
   larger RN-resolution / native-stub plugin: it aliases `react-native` to the
   engine shim and native packages to `@sootsim/compat` stubs, applies worklets
@@ -185,58 +186,58 @@ bridge always addresses the **shell worker**, never an undifferentiated sim.
 
 | component | role | key files |
 | --- | --- | --- |
-| rnxsim CLI (bin + dispatcher) | Short-lived terminal entry point. Parses argv, emits telemetry, lazy-imports one command per run, and routes guided setup/open/runtime/inspection flows without a hidden bootstrap path. | `cli/bin.ts`, `cli/parse-args.ts`, `cli/help.ts`, `cli/commands/setup.ts`, `cli/commands/control.ts` |
+| rnx CLI (bin + dispatcher) | Short-lived terminal entry point. Parses argv, emits telemetry, lazy-imports one command per run, and routes guided setup/open/runtime/inspection flows without a hidden bootstrap path. | `cli/bin.ts`, `cli/parse-args.ts`, `cli/help.ts`, `cli/commands/setup.ts`, `cli/commands/control.ts` |
 | WsBridge client | Client side of the CLI→daemon link. Resolves the daemon port from the lockfile, opens a WS to `:7668`, sends JSON commands and awaits `{id,result}`/`{id,error}`. Used by every interactive command. | `cli/ws-bridge.ts`, `src/bridge-constants.ts`, `cli/current-sim.ts` |
 | inspect / SDK command surface | Runtime inspection + interaction verbs (describe, find, do tap, get errors, wait, layout, settle). Re-exported as `rnxsim/sdk` so programmatic callers drive a sim the same way the CLI does. | `cli/commands/inspect/core.ts`, `cli/commands/inspect/actions.ts`, `cli/commands/inspect.ts`, `src/sdk.ts` |
 | Maestro / Detox runners | Drop-in test compatibility. `bridge-flow-runner.ts` runs Maestro YAML and recorded flows over the bridge; `detox/` provides a `by`/`element`/`expect`/`device` driver + jest preset so existing Detox suites run unchanged. | `cli/bridge-flow-runner.ts`, `cli/commands/maestro.ts`, `cli/commands/detox.ts`, `detox/index.ts`, `detox/jest-preset.cjs` |
 | sim drivers | Launch or attach the actual sim page. Playwright owns isolated browser profiles; Electron owns the native desktop surface. The current sim is reused unless `--new`, `--profile`, or `--ephemeral` requests a separate one. | `cli/drivers/index.ts`, `cli/drivers/registry.ts`, `cli/drivers/electron.ts`, `cli/drivers/playwright.ts` |
-| SootSimBridgeHost (serve/daemon) | The bridge process (`rnxsim serve`, or autostarted as the daemon via launchd/systemd). HTTP+WS hub on `:7668`: relays commands between CLI clients and registered sims; also serves runtime HTTP, `/__server-scan`, and fetch/WS proxies. | `src/host/bridge-host.ts`, `cli/commands/serve.ts`, `cli/commands/daemon.ts`, `src/home-paths.ts` |
+| SootSimBridgeHost (serve/daemon) | The bridge process (`rnx serve`, or autostarted as the daemon via launchd/systemd). HTTP+WS hub on `:7668`: relays commands between CLI clients and registered sims; also serves runtime HTTP, `/__server-scan`, and fetch/WS proxies. | `src/host/bridge-host.ts`, `cli/commands/serve.ts`, `cli/commands/daemon.ts`, `src/home-paths.ts` |
 | AgentHost + sessions | Agent-routing extension of the host: owns the single FIFO reader per agent session and fans `agent:event`/`session-status` pushes to every WS subscriber. Backed by agent-sessions + attached-projects stores. | `src/host/agent-host.ts`, `src/agent-sessions.ts`, `src/attached-projects.ts`, `src/agent-daemon-client.ts` |
 | host proxies + dev-server scan | Host-side helpers so a cross-origin tenant worker can reach local dev servers and same-origin APIs: `/__server-scan` discovers running metro/expo/vxrn/one servers; fetch + websocket proxies relay guest-app network through the daemon. | `src/host/fetch-proxy-handler.ts`, `src/host/websocket-proxy.ts`, `scripts/dev-server-scanner.ts`, `src/dev-bundle-resolution.ts` |
 | runtime delivery + rnx home | Versioned engine runtime management. The shared machinery owns manifest fetch, sha256 verification, channels, and auto-update. rnx binds it to `https://contrast.dev` and `~/.sootsim/runtimes/<version>`. A repo can select `runtimeVersion` without changing the machine default. | `src/runtime-delivery.ts`, `packages/contrast-runtime-delivery/`, `src/home-paths.ts`, `src/runtime-assets.ts`, `scripts/postinstall.cjs` |
 | `rnxsim/vite` + `rnxsim/metro` (runtime serving) | Published bundler plugins. Both serve the installed engine runtime at `/__soot/` from `~/.sootsim/runtimes/<version>` so an app's own dev server can host the sim shell; the vite plugin can also launch the Electron app. | `src/vite-plugin-one.ts`, `src/metro-plugin.ts`, `src/runtime-assets.ts` |
 | `sootsim()` vite resolver plugin (internal) | The large RN-resolution / native-stub vite plugin: aliases `react-native` to the engine shim, native packages to `@sootsim/compat` stubs, applies worklets/babel transforms, and instantiates `SootSimBridgeHost` in its dev server. Distinct from the published `rnxsim/vite` export. | `src/vite-plugin.ts`, `src/worklets-babel.ts`, `packages/compat/src/stub-manifest.ts` |
-| skills registry | rnx agent skills (`rnx-setup`, `rnx-debug`, `rnx-test`, `rnx-visual`, and the generated `contrast` index) installable with `rnxsim skill`. | `skills/*.md`, `src/skills/registry.ts`, `src/skills/types.ts` |
+| skills registry | rnx agent skills (`rnx-setup`, `rnx-debug`, `rnx-test`, `rnx-visual`, and the generated `contrast` index) installable with `rnx skill`. | `skills/*.md`, `src/skills/registry.ts`, `src/skills/types.ts` |
 
 ## Getting started
 
 ```sh
 curl -fsSL https://rnxsim.com/install.sh | sh
-rnxsim setup           # guided one-time machine setup
-rnxsim open 8081       # load a running metro/expo dev server
-rnxsim open /settings  # dispatch a React Native deep link into that app
+rnx setup           # guided one-time machine setup
+rnx open 8081       # load a running metro/expo dev server
+rnx open /settings  # dispatch a React Native deep link into that app
 ```
 
-The first `sootsim open` launches an isolated Chrome for Testing sim. The CLI
+The first `rnx open` launches an isolated Chrome for Testing sim. The CLI
 resolves Playwright from the app or CLI install, asks that exact package for
 its required browser executable, and runs that package's installer once when
 the executable is absent. It never substitutes another revision found in the
 shared Playwright cache. Later opens reuse that sim and reload it at the
-requested target. Use `sootsim do reload` when the target has not changed.
+requested target. Use `rnx do reload` when the target has not changed.
 Reserve `--new` for a genuinely concurrent sim; repeated new browser trees
 consume memory and CPU on shared machines.
 
 The public shell script is the recommended, inspectable bootstrap path;
-`rnxsim` is the normal path afterward. Manual installs can use `npm install
+`rnx` is the normal path afterward. Manual installs can use `npm install
 --global rnxsim`, `bun add --global rnxsim`, or `pnpm add --global rnxsim`,
-followed by `rnxsim setup`. There is no per-app install:
+followed by `rnx setup`. There is no per-app install:
 start your Metro, Expo, or One dev server the way you already do, then open it
 from the CLI. There is no iOS native build in the inner loop; Metro alone is
-enough. `rnxsim open` starts a local bridge when no daemon is reachable; the
+enough. `rnx open` starts a local bridge when no daemon is reachable; the
 guided setup installs the faster background daemon so later CLI commands reuse
-one server. A desktop GUI (Electron) is optional on top, via `rnxsim desktop
-install`. Native Electron windows created by `rnxsim open` belong to that CLI
-session and close when the session exits; `rnxsim desktop` keeps the persistent
+one server. A desktop GUI (Electron) is optional on top, via `rnx desktop
+install`. Native Electron windows created by `rnx open` belong to that CLI
+session and close when the session exits; `rnx desktop` keeps the persistent
 desktop-app lifecycle. In Electron, `File > New Window`
 duplicates the focused simulator, while `File > New Simulator >` opens a new
 window for a selected device (same device list as the `Window >` menu).
 
 To uninstall the machine daemon and cached runtimes, run
-`rnxsim daemon uninstall`. It stops current and legacy launchd / systemd
+`rnx daemon uninstall`. It stops current and legacy launchd / systemd
 services, removes daemon logs, and removes `~/.sootsim/` (runtimes, profiles,
 recordings, and lockfiles). It does not remove the optional
 `/Applications/sootsim.app` desktop bundle or macOS preference plist. To inspect
-existing disk usage before uninstalling, run `rnxsim cleanup`; add `--apply`
+existing disk usage before uninstalling, run `rnx cleanup`; add `--apply`
 only after reviewing the preview.
 
 ## Jump to source in inspect mode
@@ -270,54 +271,81 @@ inspection, interaction, animation debugging, shell tracing, screenshots, and
 flow capture, not just as a test runner.
 
 ```sh
-rnxsim list              # connected tabs
-rnxsim open 8081         # load a running metro/expo dev server
-rnxsim open /settings    # route via React Native Linking
-rnxsim describe          # dump UI tree
-rnxsim get errors 5      # recent runtime failures
-rnxsim compat            # scan native package compatibility
-rnxsim report-issue "…"  # preview an opt-in compatibility report
-rnxsim find --testid cta # inspect one node deeply
-rnxsim debug enable animated,layout
-rnxsim debug trace shell on 240
-rnxsim do tap-text "..." # interact
-rnxsim debug snapshot before
-rnxsim debug snapshot after
-rnxsim debug diff before after
-rnxsim maestro start     # begin a Maestro draft
-rnxsim maestro keep      # persist the last action
-rnxsim maestro end --output .maestro/login.yaml --validate
-rnxsim detox             # run Detox/Jest suites against rnx
+rnx list              # connected tabs
+rnx open 8081         # load a running metro/expo dev server
+rnx open /settings    # route via React Native Linking
+rnx describe          # dump UI tree
+rnx get errors 5      # recent runtime failures
+rnx compat            # scan native package compatibility
+rnx report-issue "…"  # preview an opt-in compatibility report
+rnx find --testid cta # inspect one node deeply
+rnx debug enable animated,layout
+rnx debug trace shell on 240
+rnx do tap-text "..." # interact
+rnx debug snapshot before
+rnx debug snapshot after
+rnx debug diff before after
+rnx maestro start     # begin a Maestro draft
+rnx maestro keep      # persist the last action
+rnx maestro end --output .maestro/login.yaml --validate
+rnx detox             # run Detox/Jest suites against rnx
 ```
 
-See the full command reference via `rnxsim --help` or at
+See the full command reference via `rnx --help` or at
 `src/features/site/docs/rnx/cli/` in the Contrast repo.
 
 Sim-scoped commands use the primary fallback only when one driveable sim is
 connected. With multiple driveable sims, the bridge lists their ids and refuses
-to choose. Run `rnxsim use <id>` to pin later commands, or pass `--sim <id>` to
+to choose. Run `rnx use <id>` to pin later commands, or pass `--sim <id>` to
 target one command.
 
 ## Bundler plugins (`rnxsim/vite` and `rnxsim/metro`)
 
-These serve the installed engine runtime from your own dev server. They do
-**not** resolve React Native or stub native modules — that is the internal
-`sootsim()` plugin's job (see Architecture).
+The Vite plugin serves the installed RNX runtime from your existing dev server.
 
 ```ts
 // vite.config.ts
-import { sootsimPlugin } from 'rnxsim/vite'
+import { rnxPlugin } from 'rnxsim/vite'
 
 export default {
-  plugins: [sootsimPlugin()],
+  plugins: [rnxPlugin()],
 }
 ```
 
 ```js
 // metro.config.js
-const { withSootsim } = require('rnxsim/metro')
+const { getDefaultConfig } = require('expo/metro-config')
+const { withRNX } = require('rnxsim/metro')
 
-module.exports = withSootsim({ /* your metro config */ })
+const config = getDefaultConfig(__dirname)
+
+module.exports = withRNX(config, { devServer: true })
+```
+
+The Metro wrapper has two independent opt-ins. `devServer` serves the RNX shell
+from the Metro process. `productionBundles` lets explicitly marked production
+bundle requests use the RNX host implementations of React and React Native
+while the rest of the app receives production transforms.
+
+```js
+module.exports = withRNX(config, { productionBundles: true })
+
+// enable both when the same Metro process should provide both integrations
+module.exports = withRNX(config, {
+  devServer: true,
+  productionBundles: true,
+})
+```
+
+Calling `withRNX(config)` changes nothing. Production requests must run in a
+Metro process started with `NODE_ENV=production` and use the URL helper:
+
+```js
+const { toRNXProductionBundleUrl } = require('rnxsim/metro')
+
+const bundleUrl = toRNXProductionBundleUrl(
+  'http://localhost:8081/index.bundle?platform=ios',
+)
 ```
 
 ## Coming from Detox
@@ -334,8 +362,8 @@ no code changes — just add one line to your jest config:
 Or use the CLI directly:
 
 ```sh
-rnxsim detox            # auto-discovers e2e/ tests and launches a shell
-rnxsim detox init       # scaffold a config + sample test
+rnx detox            # auto-discovers e2e/ tests and launches a shell
+rnx detox init       # scaffold a config + sample test
 ```
 
 See `../../docs/migrating-from-detox.md` for details.
@@ -346,10 +374,10 @@ Maestro is rnx's single YAML test surface. Point it at your existing
 `.maestro/` directory, generate a test, or author one from live actions:
 
 ```sh
-rnxsim maestro                      # discover .maestro/ and run all flows
-rnxsim maestro test .maestro/       # explicit
-rnxsim maestro generate "verify login"
-rnxsim maestro --list-compat        # see the verb support matrix
+rnx maestro                      # discover .maestro/ and run all flows
+rnx maestro test .maestro/       # explicit
+rnx maestro generate "verify login"
+rnx maestro --list-compat        # see the verb support matrix
 ```
 
 Most Maestro verbs work out of the box (`tapOn`, `assertVisible`, `inputText`,
@@ -362,22 +390,22 @@ need real device hardware (GPS, radio, photo library) throw a clear error. See
 For animation-heavy debugging, the useful path is usually:
 
 ```sh
-rnxsim debug enable animated
-rnxsim debug trace shell on 240
-rnxsim debug snapshot before
+rnx debug enable animated
+rnx debug trace shell on 240
+rnx debug snapshot before
 # reproduce the transition
-rnxsim debug snapshot after
-rnxsim debug diff before after
-rnxsim screenshot --with-frame --output /tmp/sootsim-framed.png
-rnxsim record --duration 5 --output /tmp/sootsim-anim.mp4
+rnx debug snapshot after
+rnx debug diff before after
+rnx screenshot --with-frame --output /tmp/sootsim-framed.png
+rnx record --duration 5 --output /tmp/sootsim-anim.mp4
 ```
 
-`rnxsim screenshot --with-frame` composes the real rnx shell device chrome
+`rnx screenshot --with-frame` composes the real rnx shell device chrome
 around the raw screen bitmap (reusing the shell bezel/button geometry, excluding
 the Electron top bar, rail gutter, and other window chrome). Flows can request
 the framed export inline without changing Maestro syntax:
 
-`rnxsim wait ready` and the screenshot readiness guard accept inspectable
+`rnx wait ready` and the screenshot readiness guard accept inspectable
 native content, a populated node tree, or a live-frame channel whose publish
 count advances across probes. Canvas-only GL, WebGPU, and video surfaces can
 therefore prove that they are painting without weakening the boot-card guard.
@@ -389,7 +417,7 @@ therefore prove that they are painting without weakening the boot-card guard.
     withFrame: true
 ```
 
-For plan-driven app-store exports, use `rnxsim screenshot appstore`:
+For plan-driven app-store exports, use `rnx screenshot appstore`:
 
 ```yaml
 app: 8081
@@ -412,14 +440,14 @@ compose:
 ```
 
 ```sh
-rnxsim screenshot appstore --plan .sootsim/app-store.yaml
+rnx screenshot appstore --plan .sootsim/app-store.yaml
 ```
 
 The plan runner can reuse a visible sim for capture (`--sim a9`), stop after
 raw/framed intermediates (`--capture-only`), or rerender final marketing
 canvases from an existing raw directory (`--compose-only`). If your flow already
 writes screenshots to explicit project paths, set `from:` + `pathMode: flow` so
-`rnxsim screenshot appstore` respects the flow's own `takeScreenshot` paths
+`rnx screenshot appstore` respects the flow's own `takeScreenshot` paths
 instead of prepending `--screenshots <rawDir>`:
 
 ```yaml
@@ -436,7 +464,7 @@ frame for quick art-direction passes.
 
 ## Skills registry
 
-`rnxsim skill install` installs rnx agent skills in the standard
+`rnx skill install` installs rnx agent skills in the standard
 `<skill-name>/SKILL.md` layout used by Codex and Claude Code. The bundled
 skills cover setup, debugging/perf/accessibility, testing, visual review, and
 the generated `contrast` command index. The published CLI registry and generated
@@ -475,7 +503,7 @@ verifies its sha256, and unpacks it under `~/.sootsim`:
 ```
 
 The bridge daemon serves these assets over HTTP and exposes a self-update route;
-`rnxsim upgrade` / `rnxsim runtime` drive explicit version changes from the
+`rnx upgrade` / `rnx runtime` drive explicit version changes from the
 CLI side. Installation retains the active runtime plus one rollback and removes
 the downloaded archive after extraction. Disposable Playwright caches live in a
 bounded per-session temporary directory; Electron's persistent HTTP cache is
@@ -483,11 +511,11 @@ disabled for simulator profiles and globally capped for app chrome. Cookies,
 localStorage, IndexedDB, service workers, recordings, and captured frames are
 user-owned data and are not removed by the default cleanup command.
 
-Per-repo configuration is optional. Every installed-runtime `rnxsim open`
+Per-repo configuration is optional. Every installed-runtime `rnx open`
 serves its selected version from a version-specific localhost origin, so a
 background activation cannot mix an already loaded shell with chunks from the
 next runtime. Without config, each new open selects the active stable version.
-When `sootsim.config.ts` sets `runtimeVersion`, `rnxsim open` installs that
+When `sootsim.config.ts` sets `runtimeVersion`, `rnx open` installs that
 version without changing the machine default. Running from a monorepo root
 resolves the only React Native app from package workspaces, then shares that app
 root across config, font, and splash discovery. The fallback scan is bounded and
@@ -499,7 +527,7 @@ maintenance process. The app and terminal command are usable before the legacy
 filesystem scan begins. The worker prints the reclaimed size to stderr, records
 completion, and does not run the scan again. Open browser profiles and a runtime
 served by a live daemon or development bridge are left untouched. The automatic
-pass retries on a later command after they close. The explicit `rnxsim cleanup --aggressive`
+pass retries on a later command after they close. The explicit `rnx cleanup --aggressive`
 command remains the only path that removes the rollback runtime or user-created
 recordings.
 
@@ -512,6 +540,6 @@ bun run build:cli
 ```
 
 The output is `dist-cli/bin.js` — a single esbuild output published as the
-`rnxsim` npm bin. Library exports build to `dist-lib/` (consumed via the
+`rnx` (and `rnxsim`) npm bin. Library exports build to `dist-lib/` (consumed via the
 `exports` map: `.`, `./vite`, `./metro`, `./sdk`, `./skills`, `./detox`, and the
 host/agent helpers). `bun run pack:smoke` validates the publishable tarball.

package/cli/auth.ts

@@ -4,7 +4,7 @@
 //   1. RNX_API_KEY, or SOOTSIM_API_KEY if that is unset — ci path
 //   2. CONTRAST_INSTALLATION_TOKEN/GITHUB_TOKEN + repo env — github action
 //      preview uploads from the Contrast runner, no extra secret
-//   3. desktop session token from shared desktop auth (`rnxsim login`)
+//   3. desktop session token from shared desktop auth (`rnx login`)
 //
 // callers wanting an auth header: `authHeaderOrExit('upload')`.
 
@@ -148,7 +148,7 @@ export function authHeaderOrExit(commandLabel: string): {
   process.stderr.write(
     `\n  rnx ${commandLabel} needs to be authenticated.\n\n` +
       `  pick one:\n` +
-      `    • run \`rnxsim login\` to sign in with your GH account\n` +
+      `    • run \`rnx login\` to sign in with your GH account\n` +
       `    • set RNX_API_KEY=sk_rnx_... (recommended for CI)\n\n`,
   )
   process.exit(1)

package/cli/bin.ts

@@ -196,7 +196,7 @@ if (parsed.version) {
   const { getCliVersion } = await import('../src/cli-version')
   const { IS_BETA, BETA_LABEL } = await import('../src/beta')
   const suffix = IS_BETA ? ` · ${BETA_LABEL}` : ''
-  console.log(`rnxsim v${getCliVersion()}${suffix}`)
+  console.log(`${rnxPublicBrand.commandName} v${getCliVersion()}${suffix}`)
   // runtime version on its own line — keeps the first line parseable while
   // surfacing the (independently-versioned) engine runtime users actually
   // render with. see `sootsim upgrade`.
@@ -262,7 +262,9 @@ if (!command) {
     const attempted =
       parsed.commandArgs.find((a) => !a.startsWith('-')) ?? parsed.commandArgs[0]
     console.error(`  unknown command: ${attempted}`)
-    console.error(`  run \`rnxsim --help\` to see the full surface.`)
+    console.error(
+      `  run \`${rnxPublicBrand.commandName} --help\` to see the full surface.`,
+    )
     await exitWithFlush(1)
   }
   const { printHelp } = await import('./help')
@@ -578,7 +580,9 @@ if (TOP_LEVEL_RUNTIME_COMMANDS.has(command)) {
 
     default: {
       console.error(`  unknown command: ${command}`)
-      console.error(`  run \`rnxsim --help\` to see the full surface.`)
+      console.error(
+        `  run \`${rnxPublicBrand.commandName} --help\` to see the full surface.`,
+      )
       await exitWithFlush(1)
     }
   }

package/cli/bridge-flow-runner.ts

@@ -608,8 +608,8 @@ export class SootSimBridgeFlowRunner {
         if (consecutiveBridgeFailures >= 4) {
           throw new Error(
             `target sim is not responding to the bridge (${lastError.message}). ` +
-              `it is likely a stale orphan — run \`rnxsim list\`, then close it ` +
-              `with \`rnxsim close <id>\` or start a fresh one with \`rnxsim open --new <port>\`.`,
+              `it is likely a stale orphan — run \`rnx list\`, then close it ` +
+              `with \`rnx close <id>\` or start a fresh one with \`rnx open --new <port>\`.`,
           )
         }
         await this.refreshSimId()

package/cli/commands/agent-wrapper.ts

@@ -131,7 +131,7 @@ export async function runAgentWrapper(argv: string[]): Promise<number> {
     !args.eventsOut
   ) {
     process.stderr.write(
-      'usage: rnxsim agent-wrapper --session-id <id> --project-id <id>\n' +
+      'usage: rnx agent-wrapper --session-id <id> --project-id <id>\n' +
         '                            --provider codex|claude --cwd <path>\n' +
         '                            --prompt-in <fifo> --events-out <fifo>\n' +
         '                            [--transcript <file>]\n' +

package/cli/commands/agent.ts

@@ -140,7 +140,7 @@ async function cmdAttach(argv: string[]): Promise<number> {
   const dir = positional[0]
   if (!dir) {
     process.stderr.write(
-      'usage: rnxsim agent attach <dir> [--name X] [--provider codex|claude]\n',
+      'usage: rnx agent attach <dir> [--name X] [--provider codex|claude]\n',
     )
     return 2
   }
@@ -167,7 +167,7 @@ async function cmdAttach(argv: string[]): Promise<number> {
 async function cmdProjects(): Promise<number> {
   const projects = [...listProjects()].sort((a, b) => b.updatedAt - a.updatedAt)
   if (projects.length === 0) {
-    process.stdout.write('no attached projects yet. try `rnxsim agent attach <dir>`.\n')
+    process.stdout.write('no attached projects yet. try `rnx agent attach <dir>`.\n')
     return 0
   }
   const header = `${'ID'.padEnd(18)} ${'NAME'.padEnd(20)} ${'FRAMEWORK'.padEnd(10)} ${'PROVIDER'.padEnd(8)} ${'7D COST'.padEnd(10)} CWD\n`
@@ -186,7 +186,7 @@ async function cmdProject(argv: string[]): Promise<number> {
   const [action, id] = argv
   if (action === 'show') {
     if (!id) {
-      process.stderr.write('usage: rnxsim agent project show <id>\n')
+      process.stderr.write('usage: rnx agent project show <id>\n')
       return 2
     }
     const project = findProjectById(id)
@@ -199,14 +199,14 @@ async function cmdProject(argv: string[]): Promise<number> {
   }
   if (action === 'remove') {
     if (!id) {
-      process.stderr.write('usage: rnxsim agent project remove <id>\n')
+      process.stderr.write('usage: rnx agent project remove <id>\n')
       return 2
     }
     deleteProject(id)
     process.stdout.write(`✓ removed project ${id}\n`)
     return 0
   }
-  process.stderr.write('usage: rnxsim agent project [show|remove] <id>\n')
+  process.stderr.write('usage: rnx agent project [show|remove] <id>\n')
   return 2
 }
 
@@ -247,7 +247,7 @@ async function cmdStart(argv: string[]): Promise<number> {
   const projectId = positional[0]
   if (!projectId) {
     process.stderr.write(
-      'usage: rnxsim agent start <projectId> [--provider codex|claude] [--fresh-thread]\n',
+      'usage: rnx agent start <projectId> [--provider codex|claude] [--fresh-thread]\n',
     )
     return 2
   }
@@ -268,8 +268,8 @@ async function cmdStart(argv: string[]): Promise<number> {
       `  project: ${project.name} (${project.id})\n` +
       `  provider: ${result.session.provider}\n` +
       `  pid: ${result.wrapperPid}\n` +
-      `  prompt with: rnxsim agent prompt ${result.session.id} "<text>"\n` +
-      `  watch events: rnxsim agent watch ${result.session.id}\n`,
+      `  prompt with: rnx agent prompt ${result.session.id} "<text>"\n` +
+      `  watch events: rnx agent watch ${result.session.id}\n`,
   )
   return 0
 }
@@ -278,7 +278,7 @@ async function cmdPrompt(argv: string[]): Promise<number> {
   const [sessionId, ...rest] = argv
   const text = rest.join(' ')
   if (!sessionId || !text) {
-    process.stderr.write('usage: rnxsim agent prompt <sessionId> "<text>"\n')
+    process.stderr.write('usage: rnx agent prompt <sessionId> "<text>"\n')
     return 2
   }
   await withDaemon((client) => client.sendPrompt(sessionId, { text }))
@@ -289,7 +289,7 @@ async function cmdPrompt(argv: string[]): Promise<number> {
 async function cmdWatch(argv: string[]): Promise<number> {
   const sessionId = argv[0]
   if (!sessionId) {
-    process.stderr.write('usage: rnxsim agent watch <sessionId>\n')
+    process.stderr.write('usage: rnx agent watch <sessionId>\n')
     return 2
   }
   process.stdout.write(`watching ${sessionId}\n---\n`)
@@ -363,7 +363,7 @@ function formatEvent(ev: AgentEvent): string {
 async function cmdTranscript(argv: string[]): Promise<number> {
   const sessionId = argv[0]
   if (!sessionId) {
-    process.stderr.write('usage: rnxsim agent transcript <sessionId>\n')
+    process.stderr.write('usage: rnx agent transcript <sessionId>\n')
     return 2
   }
   const p = transcriptPath(sessionId)
@@ -378,7 +378,7 @@ async function cmdTranscript(argv: string[]): Promise<number> {
 async function cmdEnd(argv: string[]): Promise<number> {
   const sessionId = argv[0]
   if (!sessionId) {
-    process.stderr.write('usage: rnxsim agent end <sessionId>\n')
+    process.stderr.write('usage: rnx agent end <sessionId>\n')
     return 2
   }
   await withDaemon((client) => client.endSession(sessionId))

package/cli/commands/app-fonts.ts

@@ -38,7 +38,7 @@ async function stage(args: string[]): Promise<void> {
   const manifestPath = flag(args, 'manifest')
   if (!outDir || !manifestPath) {
     console.error(
-      '  usage: rnxsim app-fonts stage --wire <wire> --out-dir <dir> --manifest <path>',
+      '  usage: rnx app-fonts stage --wire <wire> --out-dir <dir> --manifest <path>',
     )
     process.exit(1)
   }

package/cli/commands/assert.ts

@@ -501,10 +501,10 @@ function sleep(ms: number): Promise<void> {
 
 function printHelp(): void {
   process.stdout.write(`
-rnxsim assert — run any read verb and convert its output into a bisect-friendly exit code.
+rnx assert — run any read verb and convert its output into a bisect-friendly exit code.
 
 usage:
-  rnxsim assert <verb> <verb-args...> <assertion-flags...>
+  rnx assert <verb> <verb-args...> <assertion-flags...>
 
 exit codes:
   0    assertion passed          (git bisect: good)
@@ -532,10 +532,10 @@ assertion flags (AND'd when multiple are given):
   --quiet                        suppress the one-line pass/fail summary
 
 examples:
-  rnxsim assert find --testid set-max-input --count 4
-  rnxsim assert describe --contains "swap-form-header"
-  rnxsim assert get errors --count 0
-  rnxsim assert find --testid submit --exists --within 3000
-  rnxsim assert describe --jq '.shell.state == "app"'
+  rnx assert find --testid set-max-input --count 4
+  rnx assert describe --contains "swap-form-header"
+  rnx assert get errors --count 0
+  rnx assert find --testid submit --exists --within 3000
+  rnx assert describe --jq '.shell.state == "app"'
 `)
 }

package/cli/commands/auth.ts

@@ -3,13 +3,13 @@ import { resolveCliAuth } from '../auth'
 
 function printHelp(): void {
   console.log(`
-rnxsim auth — inspect CLI auth
+rnx auth — inspect CLI auth
 
 usage:
-  rnxsim auth
+  rnx auth
 
 API keys are read from RNX_API_KEY, or SOOTSIM_API_KEY if that is unset.
-Use \`rnxsim login\` to sign in and \`rnxsim logout\` to clear the desktop session.
+Use \`rnx login\` to sign in and \`rnx logout\` to clear the desktop session.
 `)
 }
 
@@ -17,7 +17,7 @@ async function printStatus(): Promise<number> {
   const auth = resolveCliAuth()
   if (!auth) {
     console.log('  not signed in')
-    console.log('  set RNX_API_KEY=sk_rnx_... or run `rnxsim login`')
+    console.log('  set RNX_API_KEY=sk_rnx_... or run `rnx login`')
     return 1
   }