docs: draft RFC — cross-surface work-item → thread linking

.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.

.env.example

@@ -18,6 +18,17 @@
 # Get this from your relay deployment. `infra/relay` deploys update it automatically.
 # T3CODE_RELAY_URL=https://relay.example.com
 
+# 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=owner/repository,owner/another-repository
+# 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
@@ -26,3 +37,13 @@
 # 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

.github/client-overlay-ownership.json

@@ -0,0 +1,40 @@
+{
+  "overlays": [
+    {
+      "id": "desktop-links",
+      "branch": "t3-discord/f7d37879-desktop-deeplinks",
+      "pullRequest": 10,
+      "paths": [
+        "apps/desktop/src/app/DesktopApp.ts",
+        "apps/desktop/src/app/DesktopClerk.test.ts",
+        "apps/desktop/src/app/DesktopClerk.ts",
+        "apps/desktop/src/app/DesktopDeepLinks.test.ts",
+        "apps/desktop/src/app/DesktopDeepLinks.ts",
+        "apps/desktop/src/backend/DesktopBackendPool.test.ts",
+        "apps/desktop/src/electron/ElectronProtocol.ts",
+        "apps/desktop/src/main.ts",
+        "apps/desktop/src/window/DesktopApplicationMenu.test.ts",
+        "apps/desktop/src/window/DesktopWindow.test.ts",
+        "apps/desktop/src/window/DesktopWindow.ts",
+        "scripts/build-desktop-artifact.ts"
+      ]
+    },
+    {
+      "id": "discord",
+      "branch": "fork/discord",
+      "pullRequest": 80,
+      "paths": [
+        "apps/discord-bot/**",
+        "docs/integrations/discord-bot.md",
+        "docs/architecture/discord-browser-automation.md",
+        "docs/examples/project-aliases.yaml"
+      ]
+    },
+    {
+      "id": "vscode",
+      "branch": "fork/vscode",
+      "pullRequest": 79,
+      "paths": ["apps/vscode/**", ".vscode/launch.json"]
+    }
+  ]
+}

.github/pr-stack.json

@@ -0,0 +1,204 @@
+{
+  "upstreamRemote": "upstream",
+  "upstreamBranch": "main",
+  "forkChangesBranch": "fork/changes",
+  "integrationBranch": "fork/integration",
+  "pullRequests": [
+    {
+      "number": 1,
+      "branch": "fork/tim"
+    },
+    {
+      "number": 27,
+      "branch": "fork/candidates"
+    },
+    {
+      "number": 2,
+      "branch": "fork/changes"
+    }
+  ],
+  "integrationOverlays": [
+    {
+      "number": 173,
+      "branch": "t3-discord/f7d37879-desktop-deeplinks"
+    },
+    {
+      "number": 174,
+      "branch": "fork/discord"
+    },
+    {
+      "number": 175,
+      "branch": "fork/vscode"
+    }
+  ],
+  "conflictResolutions": [
+    {
+      "branch": "fork/changes",
+      "commit": "10de598e790218c772ada3d908bc7b1eb1e54f0e",
+      "path": "apps/mobile/src/lib/threadActivity.ts",
+      "strategy": "theirs"
+    },
+    {
+      "branch": "fork/changes",
+      "commit": "*",
+      "path": "apps/mobile/src/lib/threadActivity.ts",
+      "strategy": "theirs"
+    },
+    {
+      "branch": "fork/changes",
+      "commit": "*",
+      "path": "packages/contracts/src/settings.test.ts",
+      "strategy": "theirs"
+    },
+    {
+      "branch": "fork/changes",
+      "commit": "ce3318775d74c566b4eef309c3f374e6d220891d",
+      "path": "packages/contracts/src/settings.test.ts",
+      "strategy": "theirs"
+    },
+    {
+      "branch": "fork/changes",
+      "commit": "*",
+      "path": "apps/web/src/components/ChatMarkdown.tsx",
+      "strategy": "theirs"
+    },
+    {
+      "branch": "fork/changes",
+      "commit": "1f8a2c58ae115df840d98d5854825123c502d54c",
+      "path": "apps/web/src/components/ChatMarkdown.tsx",
+      "strategy": "theirs"
+    },
+    {
+      "branch": "fork/changes",
+      "commit": "*",
+      "path": "apps/mobile/src/features/home/HomeScreen.tsx",
+      "strategy": "theirs"
+    },
+    {
+      "branch": "fork/changes",
+      "commit": "4d97aafb8e216dd27b6835b13ad20fca2884691e",
+      "path": "apps/mobile/src/features/home/HomeScreen.tsx",
+      "strategy": "theirs"
+    },
+    {
+      "branch": "fork/integration",
+      "commit": "*",
+      "path": "pnpm-lock.yaml",
+      "strategy": "theirs"
+    },
+    {
+      "branch": "fork/integration",
+      "commit": "286efa51172d3cbf46684c9923ca9d2b003d0967",
+      "path": "pnpm-lock.yaml",
+      "strategy": "theirs"
+    },
+    {
+      "branch": "fork/integration",
+      "commit": "*",
+      "path": "AGENTS.md",
+      "strategy": "ours"
+    },
+    {
+      "branch": "fork/integration",
+      "commit": "46c3697f207ea2de04c0a9ef72ca867d4d9f01da",
+      "path": "AGENTS.md",
+      "strategy": "ours"
+    },
+    {
+      "branch": "fork/integration",
+      "commit": "*",
+      "path": "docs/fork-stack.md",
+      "strategy": "ours"
+    },
+    {
+      "branch": "fork/changes",
+      "commit": "*",
+      "path": "AGENTS.md",
+      "strategy": "theirs"
+    },
+    {
+      "branch": "fork/changes",
+      "commit": "206981716ef30b5fb58338e32653339ed958a7f7",
+      "path": "AGENTS.md",
+      "strategy": "theirs"
+    },
+    {
+      "branch": "fork/candidates",
+      "commit": "*",
+      "path": "apps/web/src/components/SidebarV2.tsx",
+      "strategy": "theirs"
+    },
+    {
+      "branch": "fork/candidates",
+      "commit": "0cf437e7681face0550d5f9620b58f7b6327e57f",
+      "path": "apps/web/src/components/SidebarV2.tsx",
+      "strategy": "theirs"
+    },
+    {
+      "branch": "fork/changes",
+      "commit": "*",
+      "path": "package.json",
+      "strategy": "theirs"
+    },
+    {
+      "branch": "fork/changes",
+      "commit": "d21149c3666035d6afd61fbc87b4e6ceac2314e8",
+      "path": "package.json",
+      "strategy": "theirs"
+    },
+    {
+      "branch": "fork/tim",
+      "commit": "*",
+      "path": "apps/web/src/localApi.test.ts",
+      "strategy": "theirs"
+    },
+    {
+      "branch": "fork/tim",
+      "commit": "*",
+      "path": "packages/contracts/src/ipc.ts",
+      "strategy": "theirs"
+    },
+    {
+      "branch": "fork/tim",
+      "commit": "*",
+      "path": "apps/server/src/server.ts",
+      "strategy": "theirs"
+    },
+    {
+      "branch": "fork/tim",
+      "commit": "*",
+      "path": "apps/server/src/provider/Layers/ProviderRegistry.test.ts",
+      "strategy": "theirs"
+    },
+    {
+      "branch": "fork/tim",
+      "commit": "*",
+      "path": "apps/server/src/ws.ts",
+      "strategy": "theirs"
+    },
+    {
+      "branch": "fork/tim",
+      "commit": "*",
+      "path": "packages/client-runtime/src/rpc/client.ts",
+      "strategy": "theirs"
+    },
+    {
+      "branch": "fork/candidates",
+      "commit": "*",
+      "path": "apps/server/src/vcs/VcsStatusBroadcaster.ts",
+      "strategy": "theirs"
+    },
+    {
+      "branch": "fork/candidates",
+      "commit": "*",
+      "path": "apps/web/src/components/ChatView.tsx",
+      "strategy": "theirs"
+    },
+    {
+      "branch": "fork/changes",
+      "commit": "*",
+      "path": ".github/workflows/ci.yml",
+      "strategy": "theirs"
+    }
+  ]
+}

.github/pull_request_template.md

@@ -19,12 +19,30 @@ we may close it without merging it, or never review it.
 
 <!-- Explain the problem being solved and why this approach is the right one. -->
 
+## Downstream Fork Relationship
+
+<!--
+For downstream-fork work, name the base branch, affected areas, and whether this depends on another
+open PR. Delete this section for upstream contributions.
+-->
+
+## External-Fork Provenance
+
+<!--
+For an external-fork import, list what was imported unchanged, adapted locally, intentionally
+excluded, and the fully qualified source links. Delete this section for original work.
+-->
+
 ## UI Changes
 
 <!-- If this PR changes UI, include clear before/after screenshots.
      If the change involves motion or interaction, include a short video.
      Delete this section if not applicable. -->
 
+## Verification
+
+<!-- List focused tests and checks run for this change. -->
+
 ## Checklist
 
 - [ ] This PR is small and focused