docs: begin non-turn-based surfaces protocol planning

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

@@ -26,6 +26,23 @@ Shared browser dev is single-origin: Vite proxies the backend paths, so never se
 
 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.
 
+### Previewing the dev server from a remote client
+
+When T3 itself is being driven from another machine — the app connected to this environment over a
+tailnet or LAN address rather than `localhost` — a dev server bound to loopback is not reachable at
+that address just because the hostname is. Opening it does **not** require `--share`: the
+environment resolves the port on demand, reusing an existing `tailscale serve` route, using the
+environment's own address when the port already answers there, and otherwise publishing a
+tailnet-only HTTPS route for the port and withdrawing it when the dev server exits.
+
+Give the preview a `localhost:<port>` URL and let it resolve. Never hand-write the environment's
+hostname with the dev port appended — that is the shape that fails, because nothing promises the
+dev port is published under the same number or scheme.
+
+If the port cannot be made reachable, the preview reports why and what to do (dev server not
+running, tailscale not logged in, no permission to manage routes, tailnet port already taken).
+Treat that message as the result; do not retry the same URL.
+
 ### 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.

.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
 
-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.
+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.
 
 ## Start or reuse Metro safely
 

.easignore

@@ -0,0 +1,56 @@
+# Keep EAS project archives small. Mobile only needs the monorepo packages it
+# resolves through pnpm — not vendored agent reference trees or desktop shells.
+
+# Vendored reference repos (agents only; never imported by app code)
+.repos/
+
+# Desktop / electron / native host tooling
+apps/desktop/
+apps/vscode/
+apps/discord-bot/
+/native/
+release/
+release-mock/
+dist-electron/
+.electron-runtime/
+
+# Infra, docs, agent metadata
+docs/
+.agents/
+.grok/
+.github/
+.claude/
+.cursor/
+.vscode/
+infra/
+artifacts/
+.showcase/
+apps/mobile/.showcase/
+
+# Tests and snapshots (not needed for EAS bundle)
+**/__screenshots__/
+**/*.test.ts
+**/*.test.tsx
+**/*.spec.ts
+**/*.spec.tsx
+**/test-results/
+**/playwright-report/
+**/.vitest-*/
+
+# Local / generated
+node_modules/
+.t3/
+.turbo/
+.alchemy/
+.dir-deploy-n
+.logs/
+*.log
+.DS_Store
+.env
+.env.*
+!.env.example
+
+# Git / IDE noise
+.git/
+.idea/
+*.tsbuildinfo

.env.example

@@ -21,6 +21,17 @@ T3CODE_CLERK_CLI_OAUTH_CLIENT_ID=hzxSgY2cH10sDU2r
 # automatically.
 T3CODE_RELAY_URL=https://relay.t3.codes
 
+# Optional: GitHub App bridge for continuing an existing worktree-backed T3 thread
+# from a pull-request comment. See docs/integrations/github-app-setup.md.
+# The webhook route stays disabled unless all four required values are set.
+# T3CODE_GITHUB_APP_ID=123456
+# T3CODE_GITHUB_APP_PRIVATE_KEY_PATH=/absolute/path/to/private-key.pem
+# T3CODE_GITHUB_WEBHOOK_SECRET=replace-with-a-random-secret
+# T3CODE_GITHUB_APP_MENTION=t3-code-dev
+# T3CODE_GITHUB_ALLOWED_REPOSITORIES=patroza/*,macs-holding/*,effect-app/*
+# T3CODE_GITHUB_MIN_PERMISSION=write
+# T3CODE_GITHUB_TURN_TIMEOUT_MS=1800000
+
 # Optional: hosted app origin used by the CLI's out-of-band OAuth flow.
 # Defaults to https://app.t3.codes; override to test against a staging deployment.
 # T3CODE_HOSTED_APP_URL=https://nightly.app.t3.codes
@@ -29,3 +40,13 @@ T3CODE_RELAY_URL=https://relay.t3.codes
 # T3CODE_MOBILE_OTLP_TRACES_URL=https://api.axiom.co/v1/traces
 # T3CODE_MOBILE_OTLP_TRACES_DATASET=t3-code-mobile-traces-dev
 # T3CODE_MOBILE_OTLP_TRACES_TOKEN=xaat-...
+
+# Optional: sign and publish the mobile app from your own Expo and Apple teams.
+# Development and preview builds append .dev and .preview to the bundle identifier.
+# T3CODE_MOBILE_IOS_TEAM_ID=ABC1234567
+# T3CODE_MOBILE_IOS_BUNDLE_IDENTIFIER=com.example.t3code
+# Set to 1 only for free Xcode Personal Team builds. This disables paid-only
+# widgets, push capabilities, App Groups, associated domains, and EAS updates.
+# T3CODE_MOBILE_IOS_PERSONAL_TEAM=1
+# T3CODE_MOBILE_EAS_PROJECT_ID=00000000-0000-0000-0000-000000000000
+# T3CODE_MOBILE_EXPO_OWNER=your-expo-username

.envrc

@@ -0,0 +1,9 @@
+# Prefer the repo gh policy shim so coding agents cannot undraft with raw
+# `gh pr ready` (use `pnpm pr:ready`). Installed by scripts/install-git-hooks.mjs.
+PATH_add .tools/bin
+
+# Default bare `gh` commands to the fork, not gh's upstream-parent default
+# (`pingdotgg/t3code`). Without this, `gh pr view`/`create`/`checks` resolve
+# against upstream and miss the fork's PRs. Explicit `--repo` always overrides,
+# so the stack tooling (which always passes `--repo`) is unaffected.
+export GH_REPO="${T3CODE_FORK_REPOSITORY:-patroza/t3code}"

.githooks/README.md

@@ -0,0 +1,49 @@
+# Native Git hooks
+
+`pnpm install` configures `core.hooksPath=.githooks`. The tracked hooks exist
+immediately in every linked worktree; `post-checkout` reconciles dependencies
+after branch checkout and worktree creation before Git returns. T3 configures
+the hook path and triggers that checkout once for a fresh clone, before exposing
+the repository to the user.
+
+## `post-checkout`
+
+### 1. Clear TypeScript project emit (always on branch / worktree checkout)
+
+Composite packages and build outputs leave gitignored `dist/` and
+`*.tsbuildinfo`. After a branch switch those artifacts can still belong to
+another tree while sources follow HEAD. That produces phantom type errors (or
+stale emit consumers) that disappear after a clean rebuild — same class of
+failure as [scanner#1495](https://github.com/macs-holding/scanner/pull/1495) /
+[scanner#2166](https://github.com/macs-holding/scanner/pull/2166) and upstream
+typescript-go incremental gaps.
+
+On every **branch** checkout (flag `1`), this hook deletes:
+
+- `apps/*/dist` **except** `apps/server/dist` (live-served SPA + `bin.mjs`; wiping
+  it 503s any process still serving from this checkout), `apps/*/dist-electron`,
+  `packages/*/dist`
+- any remaining `*.tsbuildinfo` outside `node_modules` / `.git` / `.vite-plus`
+
+File-only checkouts (flag `0`) are left alone.
+
+**This is a workaround.** Remove when TypeScript/tsgo incremental invalidation
+is reliable ([typescript-go#2666](https://github.com/microsoft/typescript-go/issues/2666),
+[#4664](https://github.com/microsoft/typescript-go/issues/4664),
+[#4262](https://github.com/microsoft/typescript-go/issues/4262)). Do not
+re-enable cross-tree dist reuse without an exact source-identity key.
+
+### 2. Seed copy + pnpm install
+
+Successful reconciliation records the package/lockfile state under
+`node_modules`, so T3's explicit handoff invocation does not repeat an install
+which Git already completed. Explicit invocation from the target is required
+for bare or stale source repositories.
+
+When T3 will launch a configured worktree setup script, its VCS driver sets
+`T3CODE_DEFER_DEPENDENCY_INSTALL=1`. The hook still clears stale emit and copies
+seed files, but skips `pnpm install` so setup can perform it asynchronously in
+the thread terminal. Raw Git worktree creation does not set this marker and
+continues to return with dependencies prepared.
+
+Lefthook may later orchestrate parallel jobs, but is intentionally unused now.

.githooks/post-checkout

@@ -0,0 +1,177 @@
+#!/bin/sh
+# Reconcile packages after branch checkout and prepare linked git worktrees.
+#
+# Canonical hook: scripts/install-git-hooks.mjs installs this into the shared
+# hooks dir (core.hooksPath) on EVERY host via `pnpm install`, so a raw
+# `git worktree add` sets up node_modules identically on smart and the t3vm
+# guest -- not only when a worktree is created through the T3 app / t3.json.
+#
+# Strategy (metadata-safe):
+#   1. Drop TypeScript project emit (dist / tsbuildinfo) so composite/incremental
+#      builds never typecheck against foreign-tree .d.ts after a branch switch.
+#   2. Copy *small* gitignored seeds from .worktreeinclude (CLAUDE.md, .nuxt, …)
+#      via reflink/hardlink when available. NEVER clone node_modules -- that
+#      creates millions of inodes per worktree on btrfs.
+#   3. Populate node_modules with `pnpm install --frozen-lockfile --prefer-offline`
+#      against the shared store (hardlinks -> one inode per package file).
+#
+# Idempotent: never overwrites existing seed paths; pnpm is safe to re-run.
+
+# Host-agnostic: pick up pnpm/mise from the invoking user's home on either host.
+PATH="$HOME/.local/bin:$HOME/.local/share/pnpm:$HOME/.local/share/mise/shims:/run/current-system/sw/bin:/usr/local/sbin:/usr/local/bin:/usr/bin:/bin:$PATH"
+export PATH
+
+# post-checkout also runs after file-only checkouts; those do not change packages.
+[ "${3:-0}" = "1" ] || exit 0
+
+main_wt=$(git worktree list --porcelain | sed -n '1s/^worktree //p')
+wt_root=$(git rev-parse --show-toplevel 2>/dev/null)
+[ -n "$wt_root" ] || exit 0
+
+# --- TS build-cache wipe (every branch / worktree checkout) -----------------
+#
+# Composite/incremental emit (and leftover dist from builds) can outlive a
+# branch switch. Foreign .tsbuildinfo / .d.ts produce phantom type errors that
+# vanish after clean rebuild — same class as macs-holding/scanner#1495 / #2166
+# and typescript-go incremental gaps (#2666, #4664, #4262).
+# Workaround until upstream invalidation is solid; see .githooks/README.md.
+#
+clean_ts_project_emit() {
+  root=$1
+  removed=0
+
+  for d in \
+    "$root"/apps/*/dist \
+    "$root"/apps/*/dist-electron \
+    "$root"/packages/*/dist
+  do
+    [ -e "$d" ] || continue
+    # Deploy clones (and any long-running `t3 serve` from this checkout) read
+    # apps/server/dist/client from disk per request. Wiping that tree on every
+    # `git switch` immediately 503s the UI with "Web assets unavailable" until
+    # something rebuilds it — including Discord-only deploys that never rebuild
+    # the server. packages/*/dist + tsbuildinfo still clear below for the
+    # incremental-cache workaround.
+    case "$d" in
+      */apps/server/dist) continue ;;
+    esac
+    rm -rf "$d"
+    removed=1
+  done
+
+  if [ -d "$root" ]; then
+    # Prune by basename so nested apps/*/node_modules are skipped too.
+    tsbuild_files=$(
+      find "$root" \
+        \( -name node_modules -o -name .git -o -name .vite-plus \) -prune -o \
+        -type f -name '*.tsbuildinfo' -print 2>/dev/null || true
+    )
+    if [ -n "$tsbuild_files" ]; then
+      printf '%s\n' "$tsbuild_files" | while IFS= read -r f; do
+        [ -n "$f" ] || continue
+        rm -f "$f"
+      done
+      removed=1
+    fi
+  fi
+
+  if [ "$removed" = 1 ]; then
+    echo "post-checkout: cleared TypeScript project emit (dist / tsbuildinfo) under $root" >&2
+    echo "post-checkout: workaround for tsgo/tsc stale incremental cache after tree switch — see .githooks/README.md (remove when upstream fixed)" >&2
+  fi
+}
+
+clean_ts_project_emit "$wt_root"
+
+if [ -n "$main_wt" ] && [ "$main_wt" != "$wt_root" ]; then
+  # Effective include: repo .worktreeinclude if present, else nothing to seed-copy.
+  include=""
+  if [ -f "$main_wt/.worktreeinclude" ]; then
+    include="$main_wt/.worktreeinclude"
+  fi
+
+# Probe once: reflink (CoW fs) > hard link (same fs) > plain copy (cross-device).
+probe="$main_wt/.git-hook-clone-probe.$$"
+probe_dst="$wt_root/.clone-probe.$$"
+: >"$probe"
+if cp --reflink=always "$probe" "$probe_dst" 2>/dev/null; then
+  clone() { cp -a --reflink=always "$1" "$2"; }
+elif ln "$probe" "$probe_dst" 2>/dev/null; then
+  clone() { cp -al "$1" "$2"; }
+else
+  clone() { cp -a "$1" "$2"; }
+fi
+rm -f "$probe" "$probe_dst"
+
+# True if path is node_modules or under one (never clone these).
+is_node_modules_path() {
+  case "/$1/" in
+    */node_modules/*) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+if [ -n "$include" ] && [ -f "$include" ]; then
+  git -C "$main_wt" ls-files --others --ignored --exclude-from="$include" --directory |
+    while IFS= read -r rel; do
+      rel=${rel%/}
+      [ -n "$rel" ] || continue
+      is_node_modules_path "$rel" && continue
+      src="$main_wt/$rel"
+      dst="$wt_root/$rel"
+      [ -e "$dst" ] && continue
+      [ -e "$src" ] || continue
+      mkdir -p "$(dirname "$dst")"
+      if [ -d "$src" ]; then
+        clone "$src" "$dst"
+      else
+        cp "$src" "$dst"
+      fi
+    done
+fi
+fi
+
+# T3 can hand dependency installation to its asynchronous worktree setup
+# terminal. Keep the metadata cleanup and seed copy above synchronous so the
+# checkout is structurally ready, but let the UI become responsive before a
+# potentially slow package install finishes.
+if [ "${T3CODE_DEFER_DEPENDENCY_INSTALL:-0}" = "1" ]; then
+  echo "post-checkout: dependency installation deferred to T3 workspace initialization" >&2
+  exit 0
+fi
+
+# Shared-store hardlink install: fast when the store is warm, no inode clone storm.
+[ -f "$wt_root/package.json" ] || exit 0
+[ -f "$wt_root/pnpm-lock.yaml" ] || {
+  echo "post-checkout: package.json without pnpm-lock.yaml; skip install" >&2
+  exit 0
+}
+state_file="$wt_root/node_modules/.pnpm-checkout-state"
+state=$(cksum "$wt_root/package.json" "$wt_root/pnpm-lock.yaml" | cksum | awk '{print $1 ":" $2}')
+if [ -f "$wt_root/node_modules/.modules.yaml" ] && [ "$(cat "$state_file" 2>/dev/null)" = "$state" ]; then
+  exit 0
+fi
+command -v pnpm >/dev/null 2>&1 || {
+  echo "post-checkout: pnpm not on PATH; node_modules not installed" >&2
+  exit 0
+}
+
+export CI=1
+echo "post-checkout: pnpm install (hardlink from store) in $wt_root" >&2
+cd "$wt_root" || exit 1
+if pnpm install \
+    --frozen-lockfile \
+    --prefer-offline \
+    --config.package-import-method=hardlink \
+    --config.confirmModulesPurge=false
+then
+  printf '%s\n' "$state" >"$state_file"
+else
+  status=$?
+  echo "post-checkout: dependency preparation failed (exit $status); worktree remains usable but degraded" >&2
+  echo "post-checkout: fix the lockfile/configuration or rerun this hook after transient failures clear" >&2
+  # Native Git invokes this hook inside `git worktree add`; dependency setup
+  # must not turn an already-created worktree into a structural Git failure.
+  [ "${T3CODE_WORKTREE_PREPARATION_STRICT:-0}" = "1" ] && exit "$status"
+  exit 0
+fi

.githooks/pre-commit

@@ -0,0 +1,8 @@
+#!/bin/sh
+root=$(git rev-parse --show-toplevel 2>/dev/null) || exit 1
+if [ ! -x "$root/node_modules/.bin/lint-staged" ]; then
+  echo "pre-commit: worktree preparation is incomplete (lint-staged is missing)" >&2
+  echo "pre-commit: T3/manual checkout must finish post-checkout before commit" >&2
+  exit 1
+fi
+exec pnpm lint-staged

.githooks/pre-push

@@ -0,0 +1,16 @@
+# Agent-only ship gate (humans: no-op). See scripts/agent-pre-push.mjs.
+# Draft / no PR: static gate (vp check + typecheck). Ready PR: + unit tests.
+# Publish: pnpm pr:ready, or raw `gh pr ready` — the shim runs the same full gate first.
+#
+# Humans: SKIP_AGENT_PREPUSH=1 git push
+# Agents: never SKIP_AGENT_PREPUSH / never --no-verify
+# Nested Git commands must discover their own repositories, not inherit this
+# hook's GIT_DIR/GIT_WORK_TREE from the outer push.
+for name in $(git rev-parse --local-env-vars); do
+  unset "$name"
+done
+# Plain `node`, not `pnpm exec node`: pnpm runs a dependency-status check first
+# and will try to purge node_modules when the lockfile moved (a rebase does it),
+# which aborts without a TTY — the hook then fails with a pnpm error instead of
+# anything about the gate. The gate puts node_modules/.bin on PATH itself.
+node scripts/agent-pre-push.mjs