diff --git a/docs/reference/scripts.md b/docs/reference/scripts.md
index d4d2b96869e..6bdea266665 100644
--- a/docs/reference/scripts.md
+++ b/docs/reference/scripts.md
@@ -1,29 +1,29 @@
 # Scripts
 
-- `bun run dev` — Starts contracts, server, and web in `turbo watch` mode.
-- `bun run dev:server` — Starts just the WebSocket server (uses Bun TypeScript execution).
-- `bun run dev:web` — Starts just the Vite dev server for the web app.
-- Dev commands default `T3CODE_STATE_DIR` to `~/.t3/dev` to keep dev state isolated from desktop/prod state.
+- `vp run dev` — Starts contracts, server, and web in watch mode.
+- `vp run dev:server` — Starts just the WebSocket server. The server process runs on Bun (`@effect/platform-bun` + `BunPtyAdapter`), but task running uses `vp run`.
+- `vp run dev:web` — Starts just the Vite dev server for the web app.
+- Dev commands default `T3CODE_HOME` to `~/.t3` — the same shared home the desktop/production app uses. Override with `--home-dir` (see below) to keep dev state separate.
 - Override server CLI-equivalent flags from root dev commands with `--`, for example:
-  `bun run dev -- --base-dir ~/.t3-2`
-- `bun run start` — Runs the production server (serves built web app as static files).
-- `bun run build` — Builds contracts, web app, and server through Turbo.
-- `bun run typecheck` — Strict TypeScript checks for all packages.
-- `bun run test` — Runs workspace tests.
-- `bun run dist:desktop:artifact -- --platform <mac|linux|win> --target <target> --arch <arch>` — Builds a desktop artifact for a specific platform/target/arch.
-- `bun run dist:desktop:dmg` — Builds a shareable macOS `.dmg` into `./release`.
-- `bun run dist:desktop:dmg:x64` — Builds an Intel macOS `.dmg`.
-- `bun run dist:desktop:linux` — Builds a Linux AppImage into `./release`.
-- `bun run dist:desktop:win` — Builds a Windows NSIS installer into `./release`.
+  `vp run dev -- --home-dir ~/.t3-2`
+- `vp run start` — Runs the production server (serves built web app as static files).
+- `vp run build` — Builds contracts, web app, and server.
+- `vp run typecheck` — Strict TypeScript checks for all packages.
+- `vp run test` — Runs workspace tests.
+- `vp run dist:desktop:artifact -- --platform <mac|linux|win> --target <target> --arch <arch>` — Builds a desktop artifact for a specific platform/target/arch.
+- `vp run dist:desktop:dmg` — Builds a shareable macOS `.dmg` into `./release`.
+- `vp run dist:desktop:dmg:x64` — Builds an Intel macOS `.dmg`.
+- `vp run dist:desktop:linux` — Builds a Linux AppImage into `./release`.
+- `vp run dist:desktop:win` — Builds a Windows NSIS installer into `./release`.
 
 ## Desktop `.dmg` packaging notes
 
 - Default build is unsigned/not notarized for local sharing.
-- The DMG build uses `assets/macos-icon-1024.png` as the production app icon source.
+- The DMG build uses `assets/prod/black-macos-1024.png` as the production app icon source.
 - Desktop production windows load the bundled UI from `t3code://app/index.html` (not a `127.0.0.1` document URL).
 - Desktop packaging includes `apps/server/dist` (the `t3` backend) and starts it on loopback with an auth token for WebSocket/API traffic.
 - Your tester can still open it on macOS by right-clicking the app and choosing **Open** on first launch.
-- To keep staging files for debugging package contents, run: `bun run dist:desktop:dmg -- --keep-stage`
+- To keep staging files for debugging package contents, run: `vp run dist:desktop:dmg -- --keep-stage`
 - To allow code-signing/notarization when configured in CI/secrets, add: `--signed`.
 - Signed macOS builds also require `T3CODE_APPLE_TEAM_ID` and
   `T3CODE_MACOS_PROVISIONING_PROFILE`. The passkey RP domain is derived from
@@ -38,8 +38,8 @@
 
 Set `T3CODE_DEV_INSTANCE` to any value to deterministically shift all dev ports together.
 
-- Default ports: server `3773`, web `5733`
+- Default ports: server `13773`, web `5733`
 - Shifted ports: `base + offset` (offset is hashed from `T3CODE_DEV_INSTANCE`)
-- Example: `T3CODE_DEV_INSTANCE=branch-a bun run dev:desktop`
+- Example: `T3CODE_DEV_INSTANCE=branch-a vp run dev:desktop`
 
 If you want full control instead of hashing, set `T3CODE_PORT_OFFSET` to a numeric offset.