Completion toast PR image upload

.agents/skills/test-t3-app/SKILL.md

@@ -13,15 +13,25 @@ Use this skill for the web client. For iOS Simulator, Android Emulator, or physi
 2. Choose a base directory that belongs only to the current worktree or test:
    - Use the repository's ignored `.t3` directory for reusable worktree-local state.
    - Use `mktemp -d /tmp/t3code-test.XXXXXX` for disposable state and retain the printed absolute path.
-3. Start the full web stack with `vp run dev`. In a linked worktree it defaults to that worktree's gitignored `.t3`; pass `--home-dir <base-dir>` only when the test needs a different isolated directory.
+3. Start the full web stack with `vp run dev`. Add `--share` when the user needs to open it from another tailnet device. In a linked worktree it defaults to that worktree's gitignored `.t3`; pass `--home-dir <base-dir>` only when the test needs a different isolated directory.
 4. Keep the terminal session alive and read the selected server port, web port, base directory, and pairing URL from its output.
 
 Treat a base directory as disposable only when it was created or deliberately selected for the current test. Never delete or directly seed the shared `~/.t3` directory. Prefer starting with a new temporary base directory over clearing state of uncertain ownership.
 
 The worktree-local default deliberately outranks an ambient `T3CODE_HOME`; do not pass the shared home through to a worktree dev server.
 
+Ports are derived from the worktree path but can shift when occupied. Always read the actual values from the `[dev-runner]` line.
+
+Shared browser dev is single-origin: Vite proxies the backend paths, so never set `VITE_HTTP_URL` or `VITE_WS_URL` for `dev`/`dev:web`.
+
 The dev runner disables browser auto-open by default. Do not pass `--browser` during automated testing: an automatically opened page can consume the one-time bootstrap token before the controlled browser uses it.
 
+### Verify a shared environment before human handoff
+
+When another person will use the printed pairing URL, first open the shared origin without the pairing path or fragment in the controlled browser and confirm the T3 Code app loads. This browser navigation is required even when curl succeeds because browsers block some otherwise reachable ports before making a network request.
+
+Do not open the other person's complete pairing URL during this reachability check; doing so consumes its one-time token. If the agent also needs an authenticated browser, create and consume a separate pairing token, then leave a fresh token for the other person.
+
 ## Preserve the environment while iterating
 
 Treat the overall testing or implementation loop—not an assistant turn or one verification pass—as the environment lifecycle boundary.
@@ -30,7 +40,7 @@ Treat the overall testing or implementation loop—not an assistant turn or one
 - Do not stop the server merely because one verification pass completed or because you are yielding a response to the user.
 - Before starting another environment, check whether the existing process and browser tab still serve the task. Reuse them when healthy instead of discarding useful state.
 - On a later turn, verify that the existing process is alive and reuse its printed ports and base directory. If it exited, restart with the same base directory; create a new pairing token only when the browser session is no longer valid.
-- Tell the user when a test environment remains available, including its non-secret web URL when useful. Never include a pairing token.
+- Tell the user when a test environment remains available, including its non-secret web URL when useful. Include a pairing token only when the user still needs to pair (see below).
 
 ## Authenticate the browser on the first navigation
 
@@ -40,24 +50,13 @@ Treat the overall testing or implementation loop—not an assistant turn or one
 4. Wait for the pairing exchange and redirect to finish before navigating elsewhere.
 5. Continue in the same browser context so its stored bearer session remains available.
 
-Treat pairing URLs as secrets. Do not copy them into final responses, screenshots, committed files, or durable logs. A pairing token is short-lived and single-use; opening the URL in another browser or opening it twice can consume it.
+Keep pairing URLs out of screenshots, committed files, and durable logs. When the user asked for a shared environment, the deliverable IS the full pairing URL — paste it in your reply, token and all; a bare origin is useless to them. A pairing token is short-lived and single-use; opening the URL in another browser or opening it twice can consume it, so never open a URL you handed to the user.
 
 ## Recover a consumed or expired pairing token
 
-Create another token against the same database and web URL as the running dev server:
-
-```bash
-T3CODE_PORT=<server-port> node apps/server/src/bin.ts auth pairing create \
-  --base-dir <base-dir> \
-  --dev-url <web-url> \
-  --base-url <web-url> \
-  --ttl 15m \
-  --label agent-ui-test
-```
-
-Use the `Pair URL` from this command once. Derive `<server-port>` and `<web-url>` from the current dev-runner output, including any automatically selected port offset. Setting `T3CODE_PORT` keeps the administrative CLI from probing for an unrelated free port.
+Run `node apps/server/src/bin.ts pair` from the repository root. It discovers the running dev server (worktree `.t3` first, same precedence as the dev runner) and prints a fresh `Pair URL` against the server's current web origin, including a `--share` tailnet origin. Pass `--base-dir <base-dir>` only when the server was started with `--home-dir`, using the identical path.
 
-Always pass `--dev-url` for a dev-runner environment so the generated pairing URL uses the current web origin. An explicit base directory stores runtime state in `<base-dir>/userdata`; the `<base-dir>/dev` fallback is only used by an implicit dev home. A worktree-local `.t3` counts as explicit, so its state lives in `<worktree>/.t3/userdata`. Use `auth pairing list` to inspect active token metadata; it intentionally cannot reveal token secrets.
+Tokens from `pair` carry standard client scopes. The startup pairing URL carries admin scopes; if the user needs Settings → Connections management (`access:write`), restart the server and hand over the new startup URL instead.
 
 ## Inspect or seed SQLite state
 

.agents/skills/test-t3-mobile/SKILL.md

@@ -66,7 +66,7 @@ Use these client origins:
 - Android Emulator: `http://10.0.2.2:<server-port>`
 - Physical device: bind the backend to `0.0.0.0` and use the host's reachable LAN origin
 
-Always enter the complete `http://` origin; the mobile host field otherwise assumes HTTPS. When testing web and mobile together, run `vp run dev --home-dir <base-dir> --host 127.0.0.1` instead and do not launch a second backend over the same base directory.
+Enter the complete `http://` origin to make the test transport explicit. Bare IP addresses default to HTTP, while bare hostnames default to HTTPS. When testing web and mobile together, run `vp run dev --home-dir <base-dir> --host 127.0.0.1` instead and do not launch a second backend over the same base directory.
 
 ## Start or reuse Metro safely
 
@@ -80,7 +80,6 @@ Run Metro from `apps/mobile`.
    APP_VARIANT=development vp exec expo start \
      --dev-client \
      --scheme t3code-dev \
-     --clear \
      --lan \
      --port <metro-port>
    ```
@@ -125,31 +124,29 @@ Do not start, stop, erase, or reconfigure an emulator owned by another task. Tra
 
 ## Pair each client once
 
-Issue a fresh credential against the running backend's exact base directory:
+Use the bundled helper from the repository root. It issues a fresh credential against the running backend's exact base directory, opens the existing Add Environment route with the credential in an encoded query parameter, and asks that route to connect once:
 
 ```bash
-T3CODE_PORT=<server-port> node apps/server/src/bin.ts auth pairing create \
-  --base-dir <base-dir> \
-  --base-url <mobile-origin> \
-  --ttl 15m \
-  --label agent-mobile-<short-device-id>
+.agents/skills/test-t3-mobile/scripts/pair-client.sh \
+  ios <simulator-udid> <server-port> <base-dir>
+
+.agents/skills/test-t3-mobile/scripts/pair-client.sh \
+  android <emulator-serial> <server-port> <base-dir>
 ```
 
-In PowerShell, set `$env:T3CODE_PORT = "<server-port>"` first and run the `node ... auth pairing create` command without the leading assignment.
+Run only the command for the selected platform. The helper uses `http://127.0.0.1:<server-port>` for iOS and `http://10.0.2.2:<server-port>` for Android. Pass a fifth argument only when testing a non-development URL scheme.
 
-If the visible Add Environment action is not exposed as a semantic target, open the app's registered route instead of guessing coordinates:
+The helper opens this registered route:
 
-```bash
-xcrun simctl openurl <simulator-udid> 't3code-dev://connections/new'
-adb -s <emulator-serial> shell am start -W \
-  -a android.intent.action.VIEW \
-  -d 't3code-dev://connections/new' \
-  com.t3tools.t3code.dev
+```text
+t3code-dev://connections/new?pairingUrl=<encoded-pairing-url>&autoConnect=1
 ```
 
-Run only the command for the selected platform.
+The Add Environment route owns the behavior: `pairingUrl` prefills its normal host and token inputs, while `autoConnect=1` submits once in development builds and returns to Home after success. Without `autoConnect`, the same route only prefills the form for manual inspection.
+
+Do not enter pairing hosts or tokens through simulator keyboard automation. Xcode's semantic typer sends HID-style key events through the simulator's active keyboard state, which can corrupt uppercase tokens and punctuation even when the host Mac uses a U.S. input source. The one-shot route is the deterministic pairing path. Use the visible form only as a fallback, and paste credentials rather than typing them character by character.
 
-In T3 Code Dev, open Add Environment and enter the complete `<mobile-origin>` and newly printed `Token`. Verify the expected seeded projects appear before exercising the affected flow.
+Verify the expected seeded projects appear before exercising the affected flow.
 
 Pairing credentials are secret, short-lived, and single-use. Create a different credential for every simulator, emulator, physical device, or browser. If an attempt fails, issue a new credential rather than retrying the old one. Do not expose tokens in screenshots, commits, or final responses.
 
@@ -181,8 +178,11 @@ Keep local verification focused. Do not turn this workflow into a full repositor
 ## Troubleshoot predictable failures
 
 - **Old UI or an old error appears:** verify Metro's worktree, variant, URL, and port before diagnosing the app.
+- **Metro serves stale or invalid transforms after those checks:** stop the owned Metro process and run `vp run dev:client:reset` once on the standard port. For a custom port, add `--clear` to the complete explicit `expo start` command above.
 - **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.
 - **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.

.agents/skills/test-t3-mobile/scripts/pair-client.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+usage() {
+  echo "Usage: $0 <ios|android> <device-id> <server-port> <base-dir> [url-scheme]" >&2
+  exit 2
+}
+
+[[ $# -ge 4 && $# -le 5 ]] || usage
+
+platform="$1"
+device_id="$2"
+server_port="$3"
+base_dir="$4"
+url_scheme="${5:-t3code-dev}"
+
+case "$platform" in
+  ios)
+    mobile_origin="http://127.0.0.1:${server_port}"
+    ;;
+  android)
+    mobile_origin="http://10.0.2.2:${server_port}"
+    ;;
+  *)
+    usage
+    ;;
+esac
+
+repo_root="$(git rev-parse --show-toplevel)"
+cd "$repo_root"
+
+if ! pairing_output="$({
+  T3CODE_PORT="$server_port" node apps/server/src/bin.ts auth pairing create \
+    --base-dir "$base_dir" \
+    --base-url "$mobile_origin" \
+    --ttl 15m \
+    --label "agent-mobile-${device_id:0:8}"
+} 2>&1)"; then
+  echo "Could not mint a mobile pairing credential." >&2
+  exit 1
+fi
+
+pairing_url="$(printf '%s\n' "$pairing_output" | sed -n 's/^Pair URL: //p' | tail -n 1)"
+if [[ -z "$pairing_url" ]]; then
+  echo "Could not parse the mobile pairing URL." >&2
+  exit 1
+fi
+
+deep_link="$(PAIRING_URL="$pairing_url" URL_SCHEME="$url_scheme" node - <<'NODE'
+const query = new URLSearchParams({
+  pairingUrl: process.env.PAIRING_URL,
+  autoConnect: "1",
+});
+process.stdout.write(`${process.env.URL_SCHEME}://connections/new?${query}`);
+NODE
+)"
+
+case "$platform" in
+  ios)
+    xcrun simctl openurl "$device_id" "$deep_link"
+    ;;
+  android)
+    # adb shell re-joins its arguments and evaluates them through the device
+    # shell, so the deep link's `?`/`&` must be quoted once more for that shell.
+    adb -s "$device_id" shell \
+      "am start -W -a android.intent.action.VIEW -d '$deep_link' com.t3tools.t3code.dev" \
+      >/dev/null
+    ;;
+esac
+
+echo "Opened the existing Add Environment route with a fresh pairing credential."

.coderabbit.yaml

@@ -0,0 +1,4 @@
+reviews:
+  review_status: false
+  auto_review:
+    enabled: true

.devcontainer/devcontainer.json

@@ -1,29 +1,73 @@
+// Dev container for T3 Code. Mirrors CI (ubuntu-24.04, Node 24, Rust stable)
+// and the canonical setup in docs/operations/development.md: global `vp`, `vp i`.
+// Contributor doc: docs/internals/devcontainer.md
 {
-  "name": "T3 Code Dev",
-  "image": "debian:bookworm",
+  "name": "T3 Code",
+  "image": "mcr.microsoft.com/devcontainers/base:ubuntu-24.04",
   "features": {
-    "ghcr.io/devcontainers/features/git:1": {},
-    "ghcr.io/devcontainers-extra/features/bun:1": {
-      "version": "1.3.11"
+    // nodeGypDependencies (default true) brings python3/make/g++, which Linux
+    // needs for node-pty's node-gyp fallback (its prebuilds are mac/win only).
+    "ghcr.io/devcontainers/features/node:2": {
+      "version": "24"
     },
-    "ghcr.io/devcontainers/features/node:1": {
-      "version": "24.13.1"
-    },
-    "ghcr.io/devcontainers/features/python:1": {
-      "version": "3.10",
-      "installTools": false
-    }
+    // native/resource-monitor (edition 2024, needs stable >= 1.85). The server
+    // degrades gracefully without the binary, but CI checks cargo fmt + test.
+    "ghcr.io/devcontainers/features/rust:1": {},
+    "ghcr.io/devcontainers/features/github-cli:1": {}
+  },
+  "hostRequirements": {
+    "cpus": 4,
+    "memory": "8gb",
+    "storage": "32gb"
+  },
+  "containerEnv": {
+    // Keep all runtime state inside the (gitignored) workspace .t3, matching
+    // the worktree default. An explicit --home-dir still wins.
+    "T3CODE_HOME": "${containerWorkspaceFolder}/.t3"
   },
-  "overrideFeatureInstallOrder": [
-    "ghcr.io/devcontainers/features/git",
-    "ghcr.io/devcontainers-extra/features/bun"
+  "mounts": [
+    // vp keeps the pnpm content-addressable store and metadata cache under
+    // ~/.cache/pnpm (verified: the v11 store dir lives there); mounting a
+    // volume there lets installs survive container rebuilds.
+    "source=t3code-pnpm-store,target=/home/vscode/.cache/pnpm,type=volume",
+    // Root node_modules holds the whole pnpm virtual store (.pnpm), so one
+    // volume keeps the heavy tree off the slow macOS/Windows bind mount.
+    // Scoped by devcontainerId so parallel checkouts do not share it.
+    // Codespaces note: prebuild snapshots exclude volumes; drop these mounts
+    // if prebuilt codespaces become the primary workflow.
+    "source=t3code-node-modules-${devcontainerId},target=${containerWorkspaceFolder}/node_modules,type=volume"
   ],
-  "postCreateCommand": {
-    "bun-install": "bun install --backend=copyfile --frozen-lockfile"
+  "onCreateCommand": "bash .devcontainer/on-create.sh",
+  "updateContentCommand": "bash .devcontainer/update-content.sh",
+  "forwardPorts": [5733, 13773],
+  "portsAttributes": {
+    "5733": {
+      "label": "t3 web (open via the pairing URL, not the bare origin)",
+      "onAutoForward": "notify"
+    },
+    "13773": {
+      "label": "t3 server",
+      "onAutoForward": "silent"
+    }
   },
   "customizations": {
+    "codespaces": {
+      "openFiles": ["docs/internals/devcontainer.md"]
+    },
     "vscode": {
-      "extensions": ["oxc.oxc-vscode"]
+      "extensions": ["oxc.oxc-vscode", "rust-lang.rust-analyzer"],
+      "settings": {
+        // .repos is a large vendored read-only reference tree; watching it
+        // burns CPU and file handles.
+        "files.watcherExclude": {
+          "**/.repos/**": true,
+          "**/.t3/**": true
+        },
+        "search.exclude": {
+          "**/.repos": true
+        }
+      }
     }
-  }
+  },
+  "remoteUser": "vscode"
 }

.devcontainer/on-create.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# One-time container setup, baked into prebuilds. Content-dependent work
+# (dependency install, Chromium) lives in update-content.sh.
+set -euo pipefail
+
+# The Vite+ CLI is the repo task runner (vp i, vp run dev, vp test run).
+# Download to a file first: a curl failure inside $( ) would yield an empty
+# script and a false success. VP_NODE_MANAGER=no skips the installer's node
+# shims; Node comes from the devcontainer feature. The VP_*_DIR group (set
+# together, absolute) pins the install location instead of the installer's
+# XDG platform defaults, which moved the binary from ~/.vite-plus/bin to
+# ~/.local/share/vite-plus/bin between releases and would break the check
+# below either way.
+export VP_BIN_DIR="$HOME/.local/share/vite-plus/bin"
+export VP_DATA_DIR="$HOME/.local/share/vite-plus"
+export VP_CACHE_DIR="$HOME/.cache/vite-plus"
+installer=$(mktemp)
+curl -fsSL https://vite.plus -o "$installer"
+VP_NODE_MANAGER=no bash "$installer"
+rm -f "$installer"
+
+# Non-login lifecycle shells never source the profile the installer edits,
+# so expose vp on the default PATH. test -x keeps a bad install loud.
+test -x "$VP_BIN_DIR/vp"
+sudo ln -sf "$VP_BIN_DIR/vp" /usr/local/bin/vp
+
+# First-run terminal notice, rendered by the devcontainers base image.
+sudo mkdir -p /usr/local/etc/vscode-dev-containers
+sudo tee /usr/local/etc/vscode-dev-containers/first-run-notice.txt >/dev/null <<'EOF'
+T3 Code devcontainer
+
+  vp run dev            start server + web, then open the pairing URL it
+                        prints (the bare forwarded port will not authenticate)
+  cp .env.example .env  optional: enable T3 Connect cloud features
+                        (public identifiers, not secrets)
+
+Details: docs/internals/devcontainer.md
+EOF

.devcontainer/update-content.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# Runs at creation and on every prebuild content refresh, so codespaces start
+# with deps installed and caches warm. Everything here is idempotent.
+set -euo pipefail
+
+# Volume mounts (pnpm store, node_modules) and the directories docker creates
+# for them arrive root-owned; hand them to the dev user before installing.
+for dir in "$HOME/.cache" "$HOME/.cache/pnpm" node_modules; do
+  if [ -d "$dir" ] && [ "$(stat -c %U "$dir")" != "$(id -un)" ]; then
+    sudo chown "$(id -un):$(id -gn)" "$dir"
+  fi
+done
+
+CI=true vp i
+# Repairs electron's path.txt and exec bits after install, same as CI.
+vp run --filter @t3tools/desktop ensure:electron
+# Pre-warms Vite's dep optimizer (cache is keyed on the absolute path, which
+# is stable inside the container).
+node apps/web/scripts/warm-dep-cache.ts