From 6b812807b1541e9e109dd5abe7e4d71c9cc9ca90 Mon Sep 17 00:00:00 2001 From: Ivorisnoob <179814302+Ivorisnoob@users.noreply.github.com> Date: Sun, 16 Aug 2026 16:56:31 +0530 Subject: [PATCH] docs: fix stale commands and references The docs had drifted from the code: - `RPC_REQUIRED_SCOPE` was renamed to `RPC_REQUIRED_SCOPES` in apps/server/src/auth/RpcAuthorization.ts. - The Ghostty upstream pin was attributed to mobile's VERSION file; it lives at native/libghostty-vt/VERSION and is shared by Android and web. - Several pages still used `pnpm` invocations from before the `vp` migration, so the commands fail when pasted. - The mobile test skill pointed at `scripts/pair-client.sh`, which does not resolve from the repository root. - docs/user/composer.md and docs/architecture/terminal-renderers.md existed but were not linked from the docs index. - terminal-renderers.md was missing the "For maintainers" banner that the other internals and operations pages carry. Docs only; no source or behavior changes. --- .agents/skills/test-t3-mobile/SKILL.md | 2 +- apps/web/src/terminal/ghostty/README.md | 2 +- docs/README.md | 2 + docs/architecture/terminal-renderers.md | 15 +++++--- docs/internals/overview.md | 4 +- docs/internals/t3-connect.md | 2 +- .../mobile-app-store-screenshots.md | 38 +++++++++---------- docs/user/updating.md | 5 ++- 8 files changed, 38 insertions(+), 32 deletions(-) diff --git a/.agents/skills/test-t3-mobile/SKILL.md b/.agents/skills/test-t3-mobile/SKILL.md index fbcd52e697dd..d98981f9e139 100644 --- a/.agents/skills/test-t3-mobile/SKILL.md +++ b/.agents/skills/test-t3-mobile/SKILL.md @@ -182,7 +182,7 @@ Keep local verification focused. Do not turn this workflow into a full repositor - **The environment remains empty:** verify the platform-specific HTTP origin, use a fresh token, and confirm project seeding used the identical base directory. - **A second client cannot pair:** pairing tokens are single-use; issue another token. - **The pairing form opens but does not connect:** confirm the deep link uses the existing `connections/new` route, includes `autoConnect=1`, and carries a freshly minted encoded `pairingUrl`. -- **Pairing text changes case or punctuation:** do not retry semantic typing. Use `scripts/pair-client.sh`; the simulator keyboard layout and HID input path are not reliable for credentials. +- **Pairing text changes case or punctuation:** do not retry semantic typing. Use `.agents/skills/test-t3-mobile/scripts/pair-client.sh`; the simulator keyboard layout and HID input path are not reliable for credentials. - **iOS semantic actions fail:** set explicit XcodeBuildMCP defaults and refresh with `snapshot_ui`. - **Android cannot reach Metro:** verify `adb reverse` for the exact Metro port and relaunch the development-client URL. - **Android cannot reach the backend:** use `10.0.2.2`, not `127.0.0.1`, for the Android Emulator. diff --git a/apps/web/src/terminal/ghostty/README.md b/apps/web/src/terminal/ghostty/README.md index 37e1c52fb0ca..e4cccbc11a6a 100644 --- a/apps/web/src/terminal/ghostty/README.md +++ b/apps/web/src/terminal/ghostty/README.md @@ -13,7 +13,7 @@ It is intentionally not an xterm compatibility layer. - `vendor/` holds only the artifacts, reproducibly generated by `apps/web/scripts/build-libghostty-wasm.sh`. The upstream pin and license live once, at `native/libghostty-vt/` at the repository root; the wasm embeds the pinned revision - in its build info and the ABI test verifies it against mobile's `VERSION`. + in its build info and the ABI test verifies it against that `VERSION` file. Keep browser behavior here and terminal transport in the existing client runtime. Do not add React state to the render loop. Both WASM artifacts are ordinary read-only assets, not executables. diff --git a/docs/README.md b/docs/README.md index f1698a66e179..43b7eb0408d8 100644 --- a/docs/README.md +++ b/docs/README.md @@ -4,6 +4,7 @@ - [Install and first run](./user/install.md) - [Permission modes](./user/permission-modes.md) +- [Message composer](./user/composer.md) - [Keyboard shortcuts](./user/keybindings.md) - [Organizing threads](./user/thread-sidebar.md) - [Review usage](./user/usage.md) @@ -30,6 +31,7 @@ policy in [CONTRIBUTING.md](../CONTRIBUTING.md); agent rules in [AGENTS.md](../A - [Scripts](./internals/scripts.md) - [Connection runtime](./internals/connection-runtime.md) - [Providers](./internals/providers.md) +- [Terminal renderers](./architecture/terminal-renderers.md) - [Remote environments](./internals/remote.md) - [Server updates](./internals/server-updates.md) - [Resource telemetry](./internals/resource-telemetry.md) diff --git a/docs/architecture/terminal-renderers.md b/docs/architecture/terminal-renderers.md index 4b66a13f68c4..683368ba6e6e 100644 --- a/docs/architecture/terminal-renderers.md +++ b/docs/architecture/terminal-renderers.md @@ -1,5 +1,7 @@ # Terminal renderers +> For maintainers. Using T3 Code? See [docs/user](../user/). + Terminal sessions remain server-owned PTYs. Clients receive the existing raw byte stream and send input and resize events over the existing terminal contracts; renderer choices never cross the wire. @@ -28,15 +30,16 @@ detaches the PTY callback so historical device queries cannot emit replies into ## Updating Ghostty -Update and rebuild Android first, because mobile's `VERSION` file is the single source of truth for -the upstream pin (the upstream `LICENSE` lives beside it). Then run: +Update `native/libghostty-vt/VERSION` and rebuild Android first, because that file is the single +source of truth for the upstream pin shared by Android and web (the upstream `LICENSE` lives beside +it). Then run: ```sh -pnpm --dir apps/web build:ghostty-wasm +vp run --filter @t3tools/web build:ghostty-wasm ``` Commit the regenerated web `wasm` artifacts. The build embeds the pinned revision into the binary as semver build metadata, and the focused web ABI test reads it back through `ghostty_build_info` and -compares it against mobile's `VERSION` — so the web vendor directory holds only the artifacts, drift -cannot hide, and there is no second pin to keep in sync. The same test enforces the artifact budget -and exercises repeated create/write/free cycles with multi-codepoint graphemes. +compares it against `native/libghostty-vt/VERSION` — so the web vendor directory holds only the +artifacts, drift cannot hide, and there is no second pin to keep in sync. The same test enforces the +artifact budget and exercises repeated create/write/free cycles with multi-codepoint graphemes. diff --git a/docs/internals/overview.md b/docs/internals/overview.md index b9454f7b58d0..b45b20908b61 100644 --- a/docs/internals/overview.md +++ b/docs/internals/overview.md @@ -39,8 +39,8 @@ subscription. [`ws.ts`][ws] serves the group. `websocketRpcRouteLayer` mounts `GET /ws`, authenticates the upgrade through `EnvironmentAuth.authenticateWebSocketUpgrade`, then hands the socket to -`RpcServer.toHttpEffectWebsocket`. Authorization is per method: `RPC_REQUIRED_SCOPE` maps each method -to a scope, and `authorizeEffect`/`authorizeStream` enforce it. Holding a valid socket is not +`RpcServer.toHttpEffectWebsocket`. Authorization is per method: `RPC_REQUIRED_SCOPES` maps each +method to a scope, and `authorizeEffect`/`authorizeStream` enforce it. Holding a valid socket is not authorization to call everything on it. See [environment-auth.md](./environment-auth.md). On the client, [`session.ts`][session] opens the socket and builds the typed client. diff --git a/docs/internals/t3-connect.md b/docs/internals/t3-connect.md index 6f796123e98b..c4439b16099a 100644 --- a/docs/internals/t3-connect.md +++ b/docs/internals/t3-connect.md @@ -223,7 +223,7 @@ installed app executable with `VITE_DEV_SERVER_URL` and `T3CODE_PORT` set. Rebui after native dependency, main-process, preload, entitlement, provisioning, or signing changes; renderer-only changes can reuse the installed app. -For the default development ports, run `pnpm dev:web` in one terminal and launch the installed +For the default development ports, run `vp run dev:web` in one terminal and launch the installed binary from another: ```sh diff --git a/docs/operations/mobile-app-store-screenshots.md b/docs/operations/mobile-app-store-screenshots.md index 0e3c1784429b..f6319f97d415 100644 --- a/docs/operations/mobile-app-store-screenshots.md +++ b/docs/operations/mobile-app-store-screenshots.md @@ -17,7 +17,7 @@ Environments screen. The local environment cards always come from real paired se From the repository root: - pnpm screenshots:mobile + vp run screenshots:mobile The command: @@ -44,7 +44,7 @@ active. Both platforms record readiness in the simulator/emulator app container. delay allows native terminal and Git review data to finish rendering. A full capture regenerates the selected native project with Expo's clean production prebuild before -building it. Use --skip-build for repeated captures after the first build. +building it. Use `--skip-build` for repeated captures after the first build. The harness uses fixed Metro port `8199`, which separates it from Expo's normal default port but is shared across every checkout. The readiness check only verifies that the port is open; it does not @@ -52,7 +52,7 @@ verify process ownership. Concurrent screenshot harnesses in different worktrees collide or attach to the wrong Metro process. Every configured device defaults to dark appearance and the `t3-code` palette, so plain -`pnpm screenshots:mobile` produces 30 dark PNGs. Pass `--appearance light`, `--appearance dark`, or +`vp run screenshots:mobile` produces 30 dark PNGs. Pass `--appearance light`, `--appearance dark`, or `--appearance both` to override the configured appearance; `both` produces 60 PNGs. Pass `--theme ` (repeatable) or `--theme all` to capture the app's other palettes: `t3-code`, @@ -122,46 +122,46 @@ debug APK matches its accelerated emulator. Capture one scene or device: - pnpm screenshots:mobile --device iphone-6.9 --scene thread - pnpm screenshots:mobile --platform android --scene review + vp run screenshots:mobile --device iphone-6.9 --scene thread + vp run screenshots:mobile --platform android --scene review Override the configured appearance or capture both variants: - pnpm screenshots:mobile --appearance light - pnpm screenshots:mobile --appearance dark - pnpm screenshots:mobile --appearance both + vp run screenshots:mobile --appearance light + vp run screenshots:mobile --appearance dark + vp run screenshots:mobile --appearance both Capture other palettes: - pnpm screenshots:mobile --device iphone-6.9 --theme ocean - pnpm screenshots:mobile --device iphone-6.9 --theme ocean --theme ember - pnpm screenshots:mobile --device iphone-6.9 --theme all + vp run screenshots:mobile --device iphone-6.9 --theme ocean + vp run screenshots:mobile --device iphone-6.9 --theme ocean --theme ember + vp run screenshots:mobile --device iphone-6.9 --theme all Reuse the native build and retain the disposable environment: - pnpm screenshots:mobile --device ipad-13 --skip-build --keep-running + vp run screenshots:mobile --device ipad-13 --skip-build --keep-running By default, let the screenshot runner start Metro on port `8199`. To keep Metro in a separate terminal, start it with the same showcase environment and explicit harness port: cd apps/mobile - APP_VARIANT=development EXPO_PUBLIC_SHOWCASE=1 pnpm exec expo start --dev-client --port 8199 + APP_VARIANT=development EXPO_PUBLIC_SHOWCASE=1 vp exec expo start --dev-client --port 8199 Then run the capture from the repository root: - pnpm screenshots:mobile --skip-build --skip-metro --device iphone-6.9 + vp run screenshots:mobile --skip-build --skip-metro --device iphone-6.9 -`pnpm --filter @t3tools/mobile showcase` starts Expo on its normal port, so it is not compatible with -the harness's `--skip-metro` mode. +`vp run --filter @t3tools/mobile showcase` starts Expo on its normal port, so it is not compatible +with the harness's `--skip-metro` mode. List the matrix and flags: - pnpm screenshots:mobile --list + vp run screenshots:mobile --list Validate existing files without starting Metro, servers, simulators, or emulators: - pnpm screenshots:mobile --validate-only - pnpm screenshots:mobile --platform ios --validate-only + vp run screenshots:mobile --validate-only + vp run screenshots:mobile --platform ios --validate-only ## Customize the seeded environment diff --git a/docs/user/updating.md b/docs/user/updating.md index 564d05fd431f..f4c580aca8d1 100644 --- a/docs/user/updating.md +++ b/docs/user/updating.md @@ -60,8 +60,9 @@ commands. ## After the Update Keep the web or desktop app open while the server restarts. The update completes only after the -service launcher reports that exact update committed and the replacement server is ready to accept -commands. A rollback is reported immediately instead of waiting for a generic reconnect timeout. +service launcher reports that exact update as committed and the replacement server is ready to +accept commands. A rollback is reported immediately instead of waiting for a generic reconnect +timeout. If a step fails: