Commit 9e1fb459a985d13c1d4e57080f49d70dabf3b681 | the-knife

author	Julius Marminge <julius0216@outlook.com> 2026-09-04 12:45:04-07:00
committer	GitHub <noreply@github.com> 2026-09-04 12:45:04-07:00
log	9e1fb459a985d13c1d4e57080f49d70dabf3b681
tree	d1ab6a5a07a426ad54fa9736447f36513a27f994
parent	2e688a53cf8fc7a9caa9fd5070148bfcd3d5a741
signature	Signed by PGP key B5690EEEBB952194

docs: focus user guides on features and workflows (#9756)

23 files changed, 955 insertions(+), 1962 deletions(-)

README.md+2-2

...	@@ -79,12 +79,12 @@ Full docs live in [docs/](./docs). There's no docs site yet.	...	@@ -79,12 +79,12 @@ Full docs live in [docs/](./docs). There's no docs site yet.
79	- [Install and first run](./docs/user/install.md)	79	- [Install and first run](./docs/user/install.md)
80	- [Permission modes](./docs/user/permission-modes.md)	80	- [Permission modes](./docs/user/permission-modes.md)
81	- [Keyboard shortcuts](./docs/user/keybindings.md)	81	- [Keyboard shortcuts](./docs/user/keybindings.md)
82	- [Customize a project icon](./docs/user/project-settings.md)	82	- [Project settings](./docs/user/project-settings.md)
83	- [Remote access from a phone or another machine](./docs/user/remote-access.md)	83	- [Remote access from a phone or another machine](./docs/user/remote-access.md)
84	- [Keeping app and server in sync](./docs/user/updating.md)	84	- [Keeping app and server in sync](./docs/user/updating.md)
85	- [Source control integrations](./docs/user/source-control.md)	85	- [Source control integrations](./docs/user/source-control.md)
86	- Multiple accounts: [Codex](./docs/user/providers-codex.md) · [Claude](./docs/user/providers-claude.md)	86	- Multiple accounts: [Codex](./docs/user/providers-codex.md) · [Claude](./docs/user/providers-claude.md)
87	- Linux: [run T3 Code as a background service](./docs/user/background-service.md)	87	- [Run T3 Code as a background service](./docs/user/background-service.md)
88		88
89	Building from source? Start at [docs/internals/overview.md](./docs/internals/overview.md).	89	Building from source? Start at [docs/internals/overview.md](./docs/internals/overview.md).
90		90

docs/README.md+13-13

 @@ -2,22 +2,22 @@
 ## Using T3 Code
-- [Install and first run](./user/install.md)
+- [Install T3 Code](./user/install.md)
+- [Messages and context](./user/composer.md)
+- [Working with threads](./user/thread-sidebar.md)
 - [Permission modes](./user/permission-modes.md)
+- [Terminal history](./user/terminal.md)
+- [Source control](./user/source-control.md)
+- [Project settings](./user/project-settings.md)
+- [Appearance and themes](./user/appearance.md)
 - [Keyboard shortcuts](./user/keybindings.md)
-- [Organizing threads](./user/thread-sidebar.md)
+- [Import browser sessions](./user/browser-import.md)
-- [Review usage](./user/usage.md)
+- [Usage and limits](./user/usage.md)
-- [Anonymous usage data](./user/telemetry.md)
+- [Product usage data](./user/telemetry.md)
-- [Customize a project icon](./user/project-settings.md)
-- [Mobile appearance](./user/mobile-appearance.md)
-- [Environment themes](./user/environment-theme.md)
 - [Remote access](./user/remote-access.md)
-- [Keeping app and server in sync](./user/updating.md)
+- [Running in the background](./user/background-service.md)
-- [Source control integrations](./user/source-control.md)
+- [Updating T3 Code](./user/updating.md)
-- [Background service (Linux)](./user/background-service.md)
+- Provider guides: [Codex](./user/providers-codex.md) · [Claude](./user/providers-claude.md) · [OpenCode](./user/providers-opencode.md) · [Antigravity](./user/providers-antigravity.md)
-- Providers: [Codex](./user/providers-codex.md) · [Claude](./user/providers-claude.md) · [OpenCode](./user/providers-opencode.md)
-Mobile app: [apps/mobile/README.md](../apps/mobile/README.md)
 ---

docs/user/appearance.md created+66

...	@@ -0,0 +1,66 @@
1	# Appearance and themes
2
3	Open Settings → Appearance to choose a theme and follow the system appearance or stay in light
4	or dark mode. To use different themes for light and dark mode, select the corresponding preview
5	within each theme. Appearance preferences are saved separately on each device or browser.
6
7	Mobile has its own themes and text, code, and terminal preferences. It does not follow environment
8	themes or defaults.
9
10	## Custom themes
11
12	On web and desktop, choose Create theme to adjust a palette, or import a T3 Code or VS Code
13	theme. The theme editor's color picker lets you select an area of the app to find the color to
14	change. Export your theme as JSON to share it.
15
16	## Environment themes
17
18	Environment themes and defaults come from the server serving your web app or the desktop app's
19	main local environment. app.t3.codes and additional connections do not use them.
20
21	Select a published theme in Settings → Appearance to follow its palette as the server updates
22	it. Duplicate makes an independent copy you can edit. A saved custom theme with the same ID
23	takes precedence. If the server stops publishing the selected theme, T3 Code falls back to its
24	standard theme.
25
26	Run this on the server to set a default and switch connected clients to it:
27
28	```bash
29	t3 theme set nightfall
30	```
31
32	Clients that are offline apply it when they reconnect. Each client applies the setting once;
33	choosing another theme afterward sticks until the next `t3 theme set`. Run the command again to
34	reapply it, even if the name is unchanged.
35
36	`t3 theme clear` removes the default without changing anyone's current theme. `t3 theme show` lists
37	the default and published themes.
38
39	### Publish a theme
40
41	Save a theme exported from T3 Code into `~/.t3/userdata/themes/` on the server, or the `themes`
42	directory under your custom state directory. The filename supplies the theme ID: `nightfall.json`
43	can be selected with `t3 theme set nightfall`. Keep the filename stable when updating its colors.
44	Do not use `system`, `light`, `dark`, or a built-in theme's ID.
45
46	For an integration that generates a palette, this shorter format also works:
47
48	```json
49	{
50	"name": "Nightfall",
51	"appearance": "dark",
52	"canvas": "#1a1b26",
53	"accent": "#7aa2f7",
54	"colors": {
55	"terminalSelection": "#292e42",
56	"error": "#f7768e"
57	}
58	}
59	```
60
61	Set `appearance` to `light` or `dark` and supply hex colors for `canvas` and `accent`. T3 Code
62	generates the rest. The optional `colors` overrides use the names in the theme editor's advanced
63	view.
64
65	Write updates to a temporary file and rename it into place so clients never read a partial theme.
66	Invalid files are not published.

docs/user/background-service.md+59-101

...	@@ -1,123 +1,81 @@	...	@@ -1,123 +1,81 @@
1	# Running T3 Code in the Background	1	# Running T3 Code in the background
2		2
3	On Linux and macOS, T3 Code can run as a background service for your user, so it is ready without	3	On Linux and macOS, T3 Code can run as a service for your user so you do not need
4	keeping a terminal open.	4	to keep a terminal open.
5		5
6	## Manage the Service	6	## Manage the service
7		7
8	Install it with the latest T3 Code release:	8	Run these commands on the machine that will host T3 Code:
9		9
10	```sh	10	\| Task \| Command \|
11	npx t3@latest service install	11	\| ------------------------------- \| --------------------------------- \|
12	```	12	\| Install and start \| `npx t3@latest service install` \|
13		13	\| Inspect status and log location \| `npx t3@latest service status` \|
14	Check whether it is installed. On Linux this also checks whether the service is running, enabled	14	\| Update or repair \| `npx t3@latest service update` \|
15	at startup, and allowed to keep running after logout:	15	\| Stop and remove from startup \| `npx t3@latest service uninstall` \|
16
17	```sh
18	npx t3@latest service status
19	```
20
21	Update or repair it:
22
23	```sh
24	npx t3@latest service update
25	```
26
27	The service uses the same T3 Code version as the CLI you run. To install a nightly or an exact
28	version, use that version of the CLI:
29
30	```sh
31	npx t3@nightly service update
32	npx t3@1.2.3 service update
33	```
34
35	The install and update commands refuse to replace a newer service with an older version. Setup
36	through T3 Connect leaves a newer service unchanged. To downgrade, select the exact older version
37	and pass `--allow-downgrade`:
38		16
39	```sh	17	Uninstalling the service leaves your projects, threads, and settings intact.
40	npx t3@1.2.3 service update --allow-downgrade
41	```
42
43	Stop it and remove it from startup:
44
45	```sh
46	npx t3@latest service uninstall
47	```
48
49	Updating restarts T3 Code briefly. Let active agent work and terminal commands finish first.
50	If a remote update is already in progress, wait for it to finish before retrying a local update.
51
52	The service runs a small stable launcher. Exact T3 Code versions are installed separately, so a
53	failed remote candidate can return to the previous version without rewriting the service
54	definition. The launcher snapshots the database before a remote candidate starts, so database
55	updates roll back with the server version. An older launcher may require one local
56	`service update` before this is available.
57		18
58	## Platform Support	19	Install and update use the version of the CLI you invoke. For nightly, use
		20	`npx t3@nightly service update`; replace `nightly` with an exact version to pin
		21	one. An older CLI refuses to replace a newer service unless you explicitly add
		22	`--allow-downgrade`.
59		23
60	Linux uses a systemd user unit at `~/.config/systemd/user/t3code.service`. The service starts	24	Updating restarts the server. Finish active work first, and wait for any remote
61	when the machine boots and keeps running after you log out (lingering is enabled during install).	25	update already in progress. To match a remote client's version, follow
62	Setup checks the systemd user manager and enables lingering before installing a runtime or stopping	26	[Updating T3 Code](./updating.md).
63	an existing service. If that requires administrator permission, setup stops with a recovery command.
64		27
65	macOS uses a launch agent at `~/Library/LaunchAgents/com.t3tools.t3code.service.plist`. It	28	## Platform support
66	starts when you log in, not when the Mac boots, and it stops when you log out; macOS has no
67	equivalent of Linux lingering for user agents. For a Mac that should stay reachable unattended,
68	turn on automatic login (System Settings → Users & Groups; unavailable while FileVault is on) and
69	keep the Mac from sleeping.
70		29
71	A few more macOS notes:	30	Linux needs systemd user services. Setup enables lingering so T3 Code starts at
		31	boot and keeps running after logout. If this needs administrator permission,
		32	setup prints a recovery command before changing the service.
72		33
73	- Installing over SSH needs someone logged in at the Mac's screen to start the agent right away.	34	macOS starts the service when you log in and stops it when you log out. Keep the
74	Without that, the install command reports an error at the final start step, but the agent is	35	Mac logged in and awake for unattended remote access. Installing over SSH while
75	fully installed and starts at the next login.	36	nobody is logged in at the Mac's screen can fail at the final start step; the
76	- macOS may show privacy prompts for protected folders such as Desktop, Documents, or Downloads,	37	service is still installed and will start at the next login.
77	attributed to a bare `node` process, or deny access without a prompt. If agent work fails to
78	read those folders, grant Full Disk Access to the node binary listed in the launch agent's
79	`ProgramArguments`.
80	- The agent appears under System Settings → General → Login Items. If it was switched off there,
81	or disabled with `launchctl disable`, macOS will not start it at login until you switch it back
82	on.
83		38
84	Windows is not supported yet.	39	Windows background services are not supported.
85		40
86	## Using It with T3 Connect	41	T3 Connect can offer service installation during setup, but the two are managed
87		42	separately. Signing out of T3 Connect does not stop or uninstall the service.
88	T3 Connect may offer to install the service during setup so the host stays reachable in the
89	background. This is only an onboarding shortcut: the service and T3 Connect are managed separately.
90
91	Signing out of T3 Connect does not remove the service. Use `t3 service uninstall` when you no longer
92	want T3 Code to start in the background.
93		43
94	## Troubleshooting	44	## Troubleshooting
95		45
96	Run `t3 service status` on the server machine. An installed version alone does not mean the service	46	Start with `t3 service status` on the host. It prints the log path and, on Linux,
97	is running or will survive logout. Linux status reports these problems:	47	checks whether the installed service is running, enabled, and allowed to survive
		48	logout.
98		49
99	\| Code \| What it means \| Recovery \|	50	If it stops when your SSH session closes, check for `linger-disabled`. An
100	\| -------------------------- \| -------------------------------------------------------------------------------- \| ------------------------------------------------------------------------------------------------------------------------------------------ \|	51	administrator can enable lingering with:
101	\| `linger-disabled` \| The service stops after your last login session ends and does not start at boot. \| Run `sudo loginctl enable-linger "$(id -un)"`, then retry setup as your normal user. \|
102	\| `linger-unavailable` \| T3 Code could not verify the logout setting. \| Run `loginctl show-user "$(id -un)" --property=Linger` and check that systemd-logind is available. \|
103	\| `user-manager-unavailable` \| T3 Code cannot reach your systemd user manager. \| Run `systemctl --user status` in a login session for the service user. Install your distribution's systemd user-session support if needed. \|
104	\| `service-disabled` \| The service is not enabled to start automatically. \| Run the repair command shown by `t3 service status`. \|
105	\| `service-stopped` \| The service is installed but is not running. \| Read the service log and `systemctl --user status t3code.service`, then run the displayed repair command. \|
106
107	For an SSH host, run the administrator command in an interactive terminal so sudo can prompt for
108	your password:
109		52
110	```sh	53	```sh
111	ssh -t your-server 'sudo loginctl enable-linger "$(id -un)"'	54	sudo loginctl enable-linger "$(id -un)"
112	```	55	```
113		56
114	Run only the `loginctl` command with sudo. Running `t3` with sudo creates a separate installation and	57	Over SSH, allow sudo to prompt:
115	Connect identity for root. If an administrator is unavailable, run `t3 serve` in a terminal and
116	keep that session open.
117		58
118	The repair command shown by status uses the CLI version, or the installed service version if that	59	```sh
119	is newer. An older stable CLI therefore does not recommend downgrading a nightly installation.	60	ssh -t your-server 'sudo loginctl enable-linger "$(id -un)"'
120	Setup leaves an existing service running if the user-manager or lingering check fails.	61	```
121		62
122	`t3 service status` prints the log path. The adjacent `server.trace.ndjson` file contains detailed	63	Then retry service setup as your normal user. Run only the `loginctl` command
123	server traces. For failures after authorization, see [T3 Connect troubleshooting](./remote-access.md#t3-connect-troubleshooting).	64	with sudo; running T3 Code as root creates a separate installation and Connect
		65	identity. Without administrator access, run `t3 serve` in a terminal and keep
		66	that session open.
		67
		68	\| Status problem \| Next step \|
		69	\| --------------------------------------- \| ------------------------------------------------------------------------------------------------------------------------------ \|
		70	\| `linger-unavailable` \| Run `loginctl show-user "$(id -un)" --property=Linger` and check that systemd-logind is available. \|
		71	\| `user-manager-unavailable` \| Run `systemctl --user status` in a login session for the service user; check your distribution's systemd user-session support. \|
		72	\| `service-disabled` or `service-stopped` \| Read the log and `systemctl --user status t3code.service`, then use the repair command printed by T3 Code. \|
		73
		74	On macOS, check System Settings → General → Login Items if the service no
		75	longer starts at login. If agent work cannot access Desktop, Documents, or
		76	Downloads, it may need Full Disk Access for the Node executable listed in
		77	`ProgramArguments` in
		78	`~/Library/LaunchAgents/com.t3tools.t3code.service.plist`.
		79
		80	For failures after signing in to T3 Connect, see
		81	[connection troubleshooting](./remote-access.md#t3-connect-troubleshooting).

docs/user/browser-import.md+12-14

...	@@ -1,17 +1,15 @@	...	@@ -1,17 +1,15 @@
1	# Import browser logins	1	# Import browser sessions
2		2
3	In the desktop app, open Settings → Integrations → Browser profiles → Add profile	3	The desktop app can import cookies from another browser so you can reuse its signed-in sessions
4	and choose a browser under Import from. The import copies cookies into a T3 Code browser	4	in the preview browser.
5	profile so you can use existing logins in the preview browser. Changes made afterward stay
6	separate from the source browser.
7		5
8	Linux discovery includes Helium and both native and Snap installations of Firefox. Windows	6	Open Settings → Integrations → Browser profiles → Add profile, then choose a browser under
9	discovery includes Firefox and Helium builds that still use Windows' standard profile	7	Import from. Close the source browser before importing, and allow an operating-system keyring
10	encryption. Other Chromium-based browsers on Windows use app-bound cookie encryption and cannot	8	unlock prompt if one appears.
11	be imported. A browser appears once it has a profile with a cookie database. Close the source
12	browser before importing; the import wizard will prompt you if it is still running.
13		9
14	On Linux, Chromium-based browsers use your desktop keyring to protect their cookies. T3 Code	10	This is a one-time copy. Later login changes stay separate between the two browsers, and some
15	includes the keyring reader; no separate command-line tool is needed. Allow the desktop unlock	11	sites may still require you to sign in again.
16	prompt if one appears. If the keyring cannot be accessed, T3 Code reports that failure when no	12
17	cookies can be imported. Partitioned cookies are skipped.	13	On Windows, import supports Firefox and Helium profiles that use standard profile encryption.
		14	Other Chromium-based browsers use app-bound encryption and cannot be imported. Partitioned cookies
		15	are skipped on all platforms.

docs/user/composer.md+87-208

...	@@ -1,240 +1,119 @@	...	@@ -1,240 +1,119 @@
1	# Message composer	1	# Messages and context
2
3	Messages can contain up to 120,000 characters. If a draft is longer, T3 Code keeps it in the
4	composer and shows how many characters need to be removed. Shorten the draft or split it into
5	multiple messages, then send again in the same thread.
6
7	On mobile, an empty composer shows an interrupt button while the agent is working. Adding text
8	or an attachment replaces it with the send button. This applies to both compact and expanded
9	composers.
10
11	You can attach images up to 10 MB. On servers that support file uploads, you can also
12	attach videos, text files, PDFs, ZIP archives, and other files. Each file can be up to the limit advertised
13	by the server, capped at 50 MB. Each message can contain up to eight attachments in total. Files
14	upload directly to the environment, where your agent can read, copy, or edit them by their file path.
15
16	Attachments upload as soon as you add them while connected to a server that supports uploads.
17	The send button becomes available after every upload finishes. Failed uploads can be retried or
18	removed. On mobile, tap + to open
19	the photo library from either the compact or expanded composer. When the connected server supports
20	file uploads, + opens a menu beside the button with Photo Library and Choose Files.
21	Videos use the server's file upload limit. You can also share photos, videos, and files into
22	T3 Code from other apps through the system share sheet. Mobile keeps a local copy of each draft
23	attachment, so you can still preview it and queue messages while offline. Uploads resume when
24	you reconnect. Drafts and queued messages survive app restarts; signing out of T3 Connect keeps
25	them on your device until you sign back into the same account. Select a received file on mobile
26	to preview it or open the system share options.
27
28	Tap an image or PDF before or after sending to open it. On iOS, images zoom from their thumbnail
29	into the native viewer. Pinch or double-tap to zoom, and swipe down or tap Close to return.
30	Use Share to save a copy or send it to another app. PDFs support page navigation and search.
31	PDF links in assistant responses open the same preview. On Android, images open in the image
32	viewer and PDFs open the system chooser.
33
34	On web and desktop, select a sent PDF or HTML attachment to open it in the file viewer, or use the
35	download button beside it to save a copy. Other attached files download when selected.
36
37	Select a video attachment before or after sending to play it. Web and desktop use the browser's
38	built-in controls. On mobile, videos open in a full-screen player with native playback controls.
39	Supported videos show a thumbnail in the conversation and composer.
40	Received videos stream from their environment as they play on every platform. Supported formats and
41	codecs depend on the browser or device; you can save an unsupported video to open it in another app.
42
43	On iOS, the system player zooms from the attachment. Swipe down or tap Close to return to the
44	conversation or draft. Touch and hold a video thumbnail, then choose Save or share to open
45	the system share options. On Android, the same menu is also available inside the preview.
46
47	On web and desktop, if you reload before a file finishes uploading, the draft keeps the file's name
48	and shows Attach again next to it. Attach the file again or remove it, then send.
49
50	On web and desktop, HEIC and HEIF photos are automatically converted to JPEG when you drag them into
51	the composer or paste them into a message. On iOS, selecting them from Photo Library also
52	converts them to JPEG. The 10 MB image limit applies to the converted photo.
53
54	On web and desktop, an existing thread settles its composer into a single-line resting state when
55	the composer loses focus. At wider sizes, scrolling the conversation also rests a focused composer,
56	except when scrolling toward the end while already there. When the thread-context strip has room,
57	the model and mode controls stay available beside the thread context; otherwise they return when the
58	composer is focused. Focus the composer or start typing to expand it again. The conversation keeps
59	the expanded composer's space clear above its last message while the composer rests, so expanding it
60	again never covers what you scrolled to. New-thread layouts keep the full composer. Settings → General → Collapse composer chooses which triggers rest it:
61	On unfocus, On scroll, both, or neither. With neither selected the composer stays expanded.
62
63	At phone-sized web or desktop window widths, existing threads animate between their compact and
64	expanded layouts. Up to three image attachments remain visible in either resting layout, followed
65	by a count when more are attached. At wider sizes, videos, files, and other draft context remain
66	visible at their natural height; the phone-sized compact row reveals those details when expanded.
67
68	On mobile, the model picker shows each OpenCode model's upstream provider, such as Anthropic,
69	GitHub Copilot, or OpenCode Zen, beneath its name. Search by that provider name to narrow the list
70	when starting a thread or changing an existing thread's model.
71		2
72	## Model defaults	3	Give the agent a task in the composer. Add files, quote a previous response, or
		4	include a skill when the task needs more context.
73		5
74	T3 Code remembers the last provider, model, and model options you selected and reuses that	6	Messages can contain up to 120,000 characters. Longer drafts stay in the composer
75	selection for new threads. A model configured in a project's settings overrides the remembered	7	so you can shorten them or split them into several messages.
76	selection for that project; resetting the project setting returns it to the remembered selection.
77		8
78	Model options shown as provider defaults remain display values until you choose them in T3 Code.	9	## Attach files
79	T3 Code only sends options you selected explicitly, so an unset reasoning level or service tier can
80	still come from the provider's own configuration.
81		10
82	## Quote an assistant response	11	Attach up to eight files per message. Images can be up to 10 MB; other files can
		12	be up to 50 MB, subject to the environment's upload support and limit. The agent
		13	receives them on the environment's machine.
83		14
84	On web and desktop, select text in an assistant response, then choose Cite in composer from the	15	Uploads begin when you add an attachment. All uploads must finish before the
85	menu that appears when you release the selection. This inserts an inline quote chip at your cursor	16	message can send. Retry or remove a failed upload. On web and desktop, reloading
86	and opens an optional comment bubble beside the selected text; press `Enter` or choose Save to	17	before an upload finishes requires you to attach that file again.
87	attach the comment, or leave it blank to keep just the quote. You can type before and after the
88	chip, such as a quote followed by "what do you mean?". A selection must stay within one response
89	and fit in 8,000 characters.
90		18
91	The chip shows your comment when it has one, or a short quote preview otherwise. Use the pencil	19	You can drag or paste images into the web or desktop composer. HEIC and HEIF
92	button to add or change the comment, and the remove button to delete the quote and its comment from	20	photos are converted to JPEG there and when selected from the iOS photo library;
93	the draft. Copying, reloading, and restoring a [stashed prompt](#prompt-stash) keep each comment	21	the image limit applies after conversion. On mobile, you can also send files to
94	with its quote, and sending tells the agent which words were quoted and which comment you wrote.	22	T3 Code through another app's system share sheet.
95	The quoted text and comment count toward the message limit.
96		23
97	Select a chip in the composer or a sent message to open the source thread, scroll to the response,	24	See [images and videos](#images-and-videos-in-messages) for previewing and saving media.
98	and highlight the quoted passage — including in older history. The
99	highlight pulses, holds for a moment, then fades on its own; press `Escape` to stop the navigation
100	or clear it early. If the source is unavailable or its text has changed, the saved quote stays
101	readable and T3 Code shows a warning.
102		25
103	Mobile shows the full saved quote and its comment in sent messages. It does not offer	26	## Queue messages offline on mobile
104	Cite in composer or navigation to a quote's source.
105		27
106	## Images and videos in messages	28	Mobile keeps local copies of draft attachments, so you can preview them and queue
		29	messages while disconnected. Uploads resume when you reconnect. Drafts and queued
		30	messages survive app restarts. Signing out of T3 Connect keeps that work on your
		31	device until you sign back into the same account.
107		32
108	On web, desktop, and mobile, select a link to an image or video to open it inside T3 Code.	33	## Model defaults
109	Workspace image and video links open the file viewer. Links to media outside the workspace
110	open a media preview.
111	Videos opened from the file explorer or a file-viewer tab also play inside T3 Code. They
112	stream from the environment as needed, rather than downloading the entire video before playback.
113	Paths in inline code, such as `/tmp/recording.mp4`, work the same way. Image embeds stay inline;
114	video embeds show a player with the browser's controls, full screen included. Visible video previews load
115	an initial frame when supported, but stay paused until you press Play. Video file references use
116	a filmstrip icon.
117
118	On web and desktop, hover over a preview to see its full file path or original URL. Right-click
119	to copy that reference, save the image or video, or copy an image to the clipboard. The video
120	player's built-in controls can download a video too. If the player cannot decode a video, its error message
121	offers a link to open the source in the browser. Workspace media also offers **Copy relative
122	path and Open in file viewer**. These actions are available in expanded previews too.
123
124	On mobile, touch and hold an inline image or a video thumbnail to see its source,
125	copy the path or URL, or choose Save or share. Workspace files can open in the file viewer
126	from the same menu. Saving downloads a copy only when you request it; it does not change how
127	the video buffers during playback. On iOS, touch and hold a file reference in a message to
128	copy its full or relative path or open it in the file viewer.
129
130	Use Markdown image syntax to embed either kind of media:
131
132	```markdown
133	![Screenshot](/tmp/screenshot.png)
134	![Recording](/tmp/recording.mp4)
135	[Open recording](/tmp/recording.mp4)
136	```
137
138	Relative paths resolve from the thread's workspace. Absolute paths and `file://` links refer to
139	the environment's machine, even when you connect remotely or use your phone. Supported media
140	can live outside the workspace, including in Downloads or `/tmp`.
141
142	T3 Code serves the original file without adding it to attachment storage. If that file is moved
143	or deleted, its preview can no longer load from the environment. A browser or device may still
144	have a cached copy. Supported video formats and codecs depend on the browser or device.
145
146	Bare paths in ordinary prose and paths inside code blocks stay text. Raw HTML `<video>` tags
147	are not supported; use the Markdown embed syntax above.
148		34
149	## Files outside the workspace	35	T3 Code remembers your provider, model, and model options for new threads. A
		36	project's configured model takes precedence; resetting that project setting
		37	returns to the remembered selection.
150		38
151	When an agent links to a file it wrote outside the workspace, such as a Markdown report in	39	Leaving reasoning level or service tier unset uses the provider's own configuration.
152	`/tmp`, select the link to open it in the file viewer. The viewer shows the file read-only, with
153	rendered Markdown available as usual; it cannot edit files outside the workspace. The workspace
154	file tree stays hidden because it does not describe the open file. HTML and PDF files outside the
155	workspace open the same way as ones inside it. Because such a file is served on its own, an HTML
156	page outside the workspace cannot load scripts, styles, or images from files beside it.
157		40
158	## HTML and PDF files in the file viewer	41	## Quote an assistant response
159		42
160	On web and desktop, the file viewer shows HTML and PDF files as a rendered page. Use the	43	On web and desktop, select text within one assistant response and choose
161	source toggle in the viewer's header to switch an HTML file between the page and its markup; the	44	Cite in composer. You can add a comment about the quote and write instructions
162	choice persists like the rendered-Markdown toggle. A link to a line always opens the source. HTML	45	around it.
163	runs in an isolated frame with no access to your T3 Code session. On desktop, the integrated
164	browser remains available from the same header for a full browser view.
165		46
166	## Changing projects	47	Select the quote in a draft or sent message to return to its source. If the source
		48	is unavailable or has changed, the saved quote remains readable.
167		49
168	On web and desktop, changing the project from a new thread keeps the current environment when that	50	Mobile displays saved quotes and comments, but does not create citations or
169	project exists there. If it does not, T3 Code selects another environment that has the project.	51	navigate to their sources.
170		52
171	## Notices above the composer	53	## Prompt stash
172		54
173	On web and desktop, loading and syncing statuses fill the available banner width beside the	55	On web and desktop, press `Cmd+S` on macOS or `Ctrl+S` on Windows and Linux to save
174	stash tab. Task progress appears above the composer, while the timeline's working timer shows	56	the current prompt and its attachments for later. Wait for uploads to finish first.
175	only elapsed time.	57	With an empty composer, the same shortcut restores a single stash or opens the
		58	stash menu when there are several.
176		59
177	Loading, syncing, and server-update icons are static. Live tool labels do not shimmer.	60	Stashes containing uploaded files must be restored in their original environment.
		61	Those files are retained for 24 hours. After an upload expires, restore the prompt
		62	and use Attach again or remove the missing file before sending.
178		63
179	On web and desktop, additional notices peek out above the attached banner. Hover over the peek	64	## Voice input on iPhone
180	to reveal them, or focus Show other notices with `Tab` and press `Enter` or `Space`. Press
181	`Escape` to close the stack and return focus to that control. On a touchscreen, tap the peek to
182	open the stack. Interacting with the attached banner or composer does not open the stack.
183		65
184	## Prompt stash	66	On supported iPhones with iOS 26 or later, use the composer's microphone to record,
		67	then confirm to transcribe. Text is inserted where your selection was when
		68	recording started, ready for you to review and edit before sending.
185		69
186	Use the default shortcut, `Cmd+S` on macOS or `Ctrl+S` on Windows and Linux, to stash the current	70	The first use may download Apple's speech model and needs a network connection.
187	prompt and its attachments after all file uploads finish. When the composer is empty and the stash	71	Later transcription works offline for that language. Recordings can be up to five
188	has one entry, press the shortcut again to restore it. The shortcut opens the stash menu if there	72	minutes long. Canceling, leaving the screen, or an audio interruption discards the
189	are multiple entries or the entry's images are still saving. You can also open the menu from the	73	recording and preserves your existing draft.
190	stash badge. Stashes that contain files must be restored in the environment where those files were
191	uploaded. Stashed files stay uploaded on the server for 24 hours. If you restore an entry after
192	that, the file comes back with Attach again next to it. Attach the file again or remove it, then
193	send.
194		74
195	## Voice input on iPhone	75	Transcription runs on your device. T3 Code deletes the temporary audio after
196		76	transcription or cancellation; only the message text is sent when you submit.
197	On supported iPhones with iOS 26 or later, tap the microphone in the composer to record a message.
198	An expanded composer keeps your draft visible and flips its bottom toolbar into recording controls
199	with waves that respond to your voice. A collapsed composer flips into a compact recording strip
200	without changing height. Tap the checkmark to finish and transcribe on your device. The waves fade
201	into a transcription status, then the usual
202	controls return with the text inserted at the selection where recording started. If the keyboard
203	is open when you start, it stays open during voice input. You can review and edit the text before
204	you send it.
205
206	The first use can download Apple's speech model and needs a network connection. Later transcription
207	works offline for that language. A recording can be up to five minutes long. Canceling voice input,
208	leaving the screen, or an audio interruption discards the new recording and keeps the existing draft
209	and attachments. T3 Code deletes the local audio file after transcription or cancellation. It sends
210	only the normal message text when you submit the draft.
211		77
212	## Commands and skills	78	## Commands and skills
213		79
214	Type `/` to open the command menu. Type `$` to find and add a skill. Skill rows show their source,	80	Type `/` for commands or `$` to add a skill from the selected environment and
215	such as System, Personal, Project, or App.	81	provider. On mobile, both are also available before starting a thread on
		82	New task.
		83
		84	The slash menu also includes skills unless you turn off **Settings → General →
		85	Show skills in slash menu**. Only skills enabled for the provider are listed.
		86
		87	Provider commands must start the message to run. T3 Code commands such as
		88	`/model` and `/plan`, and skill mentions, work on any line.
		89
		90	Send `/compact` in an existing conversation to reduce context usage when the
		91	provider supports it. Web and desktop also offer compaction from the context meter.
		92
		93	## Images and videos in messages
		94
		95	Select an image or video attachment or link to preview it. Playback support depends
		96	on your browser or device; save an unsupported video to open it in another app.
216		97
217	On mobile, these menus are available on the New task screen before you start a thread. They	98	On web and desktop, right-click media to save it or copy its path or URL. On mobile,
218	use the skills and commands from the selected environment and provider.	99	touch and hold an image or video thumbnail and choose Save or share. On iOS,
		100	return to the thumbnail to open this menu after watching a full-screen video.
219		101
220	In a thread with prior conversation context, send `/compact` to reduce context usage. Web and desktop also offer this action from the context meter, and the work log records token counts when the provider reports them.	102	File links refer to the environment's machine, including when you connect remotely.
		103	Previews use the original file, even outside the workspace. Moving or deleting it
		104	can break the preview, so save a copy if you need to keep it.
221		105
222	By default, the `/` menu includes skills. To keep this menu command-only, turn off **Show skills in	106	## Files outside the workspace
223	slash menu in Settings → General**. Skill results use the `/skill:Skill Name` label and add the
224	same `$name` skill token to your message. The original skill name remains searchable. If the provider
225	also reports that skill as a native slash command, T3 Code hides the duplicate native entry and keeps
226	the `/skill:Skill Name` label.
227		107
228	A skill token runs the skill wherever it sits in your message. T3 Code sends it to each provider in	108	Follow an agent's file link to read a report or other file outside the workspace.
229	the form that provider runs, so the text before and after the token is kept. Skills that only you may	109	These files open read-only. An HTML file outside the workspace cannot load scripts,
230	start, and never the agent on its own, work the same way. A skill you switched off in the provider's	110	styles, or images from neighboring files.
231	settings does not appear in either menu.	111
		112	## HTML and PDF files in the file viewer
232		113
233	Provider commands such as `/compact` only run when they open the message, so the `/` menu offers	114	On web and desktop, HTML and PDF files open as rendered pages. Switch an HTML
234	them only there. T3 Code's own commands, such as `/model` and `/plan`, and skills stay available on	115	file to source view to read its markup; a link to a specific line opens source
235	any line.	116	automatically. HTML previews cannot access your T3 Code session.
236		117
237	On desktop, press `Cmd+Enter` on macOS or `Ctrl+Enter` on Windows and Linux from a new thread to	118	On mobile, select a PDF attachment or link to open it. iOS uses the native viewer;
238	start it in the background. T3 Code opens another new thread and shows an Open action for the	119	Android opens the system chooser.
239	thread that started. The new thread keeps the selected workspace mode and base branch. If **New
240	worktree** is selected, each background thread creates its own worktree.

docs/user/environment-theme.md deleted-92

...	@@ -1,92 +0,0 @@
1	# Environment theme
2
3	Some desktops publish the palette they are currently wearing so that apps can match it. When the
4	machine running your T3 Code server does that, its themes appear in the theme library alongside
5	your own, and T3 Code follows them: change the desktop theme and T3 Code retints with it, without
6	a restart.
7
8	To use one:
9
10	1. Open Settings.
11	2. Select Appearance.
12	3. Choose the theme published by your environment.
13
14	Like every theme, this is a per-client choice: picking it on your desktop does not change what your
15	phone or another browser shows.
16
17	The machine can also set the environment's theme:
18
19	```bash
20	t3 theme set nightfall
21	```
22
23	Web and desktop clients switch to it — immediately when connected, on their next connect
24	otherwise — and a fresh client opens with it. Each client applies a set once, so picking a
25	different theme in Settings afterwards sticks until the next `t3 theme set`, and running the same
26	set again is how you bring clients back. `t3 theme clear` removes the setting without changing
27	what anyone currently has, and `t3 theme show` prints the current theme and everything the
28	machine publishes. Only the environment you are anchored to publishes themes, so a remote client
29	follows the machine it is connected to, not the device it runs on. T3 Code Mobile keeps its own
30	appearance settings and does not follow environment themes.
31
32	Select Duplicate on a published theme's card to keep a copy you can edit. The published theme
33	itself cannot be edited or removed, because the environment rewrites it whenever its own theme
34	changes. If the machine stops publishing it, the card disappears and clients using it fall back to
35	the standard T3 Code look. A theme you saved always wins over a published one with the same id.
36
37	When the theme editor is open, its draft stays visible while published themes change.
38	Close the editor to show the latest selected theme.
39
40	## Publishing themes
41
42	A machine publishes themes by writing files into the `themes` directory of the T3 Code state
43	directory (`~/.t3/userdata/themes/` by default). The filename is the theme id — `nightfall.json`
44	appears as `nightfall` — and stays stable while the machine rewrites the colors underneath, so
45	selections and defaults keep pointing at it.
46
47	The filename may not be an appearance keyword (`system`, `light`, `dark`) or a built-in theme's
48	id — those names already mean something on every client. Two formats are accepted. A theme
49	exported from T3 Code (the Download button's output) works as-is, so any theme someone shared
50	can be dropped in unchanged. Or, for a desktop that only knows
51	its own palette, a short seeded form:
52
53	```json
54	{
55	"name": "Nightfall",
56	"appearance": "dark",
57	"canvas": "#1a1b26",
58	"accent": "#7aa2f7"
59	}
60	```
61
62	`appearance` is `light` or `dark`, and `canvas` and `accent` are hex colors. T3 Code generates the
63	rest of the palette from those two, the same way the guided theme editor does, so the result reads
64	as a T3 Code theme wearing your desktop's colors rather than a transplant of another app's.
65
66	A machine that knows a role better than a derivation can guess — its terminal palette, its
67	semantic colors — can publish that role directly under `colors`, layered over the generated
68	palette:
69
70	```json
71	{
72	"name": "Nightfall",
73	"appearance": "dark",
74	"canvas": "#1a1b26",
75	"accent": "#7aa2f7",
76	"colors": {
77	"terminalSelection": "#292e42",
78	"error": "#f7768e"
79	}
80	}
81	```
82
83	Any of the roles shown in the theme editor's advanced view can be published this way; roles left
84	out keep their generated value. A role this version of T3 Code does not know is ignored rather
85	than rejected, so publishing a role added by a newer release is safe. An `id` inside the file is
86	ignored — the filename decides.
87
88	A theme with no usable colors is not listed on that client.
89
90	Write each file atomically — write a temporary file beside it and rename — so T3 Code never reads
91	a half-written theme. An unreadable or invalid file is simply not published; the machine's other
92	themes are unaffected.

docs/user/install.md+71-114

...	@@ -1,142 +1,99 @@	...	@@ -1,142 +1,99 @@
1	# Install T3 Code	1	# Install T3 Code
2		2
3	T3 Code is a web and desktop GUI for running coding agents on your machine.	3	T3 Code runs coding agents on your computer and lets you control them from its
		4	desktop, web, or mobile app. Set up the machine where the agents will work first.
4		5
5	## Requirements	6	## Requirements
6		7
7	Node.js `^22.16 \|\| ^23.11 \|\| >=24.10` on the machine that runs the T3 Code server.	8	Command-line use, SSH hosts, and WSL backends need Node.js 22.16+ (22.x), 23.11+
		9	(23.x), or 24.10 and later. The native desktop app includes its server runtime.
8		10
9	At least one provider runtime, installed and authenticated. You can install Antigravity from	11	You need an installed, authenticated provider before starting a thread. You can
10	T3 Code settings. See [Providers](#providers) below.	12	launch T3 Code and configure providers afterwards.
11		13
12	## Run Without Installing	14	## Run without installing
13		15
14	```bash	16	```bash
15	npx t3@latest	17	npx t3@latest
16	```	18	```
17		19
18	This starts the T3 Code server on your machine and opens the local web app. Use	20	This starts the server and opens the local web app. Run
19	`npx t3@latest --help` for the full CLI reference.	21	`npx t3@latest --help` for command-line options.
20		22
21	If the web or desktop app shows "T3 Code could not load", check your connection and select	23	## Desktop app
22	Reload to try again.
23		24
24	## Open a project in the desktop app	25	Download a release from [GitHub Releases](https://github.com/pingdotgg/t3code/releases),
		26	or use a package manager:
25		27
26	When the T3 Code desktop app is running on the same machine, open the current directory with:	28	\| Platform \| Install \|
		29	\| ------------------ \| ------------------------------- \|
		30	\| Windows \| `winget install T3Tools.T3Code` \|
		31	\| macOS \| `brew install --cask t3-code` \|
		32	\| Arch Linux \| `yay -S t3code-bin` \|
		33	\| Arch Linux nightly \| `yay -S t3code-nightly-bin` \|
27		34
28	```bash	35	### Windows Subsystem for Linux
29	npx t3 app
30	```
31
32	Pass a path to open another directory:
33
34	```bash
35	npx t3 app ../my-project
36	```
37
38	The command adds the directory as a project when needed, focuses the desktop app, and opens a new
39	thread. It does not launch the desktop app, open a browser, or start a T3 Code server. A background
40	server does not count as the desktop app. The command also rejects SSH sessions because a remote
41	shell cannot focus a local desktop window. The CLI package and the running desktop app must both
42	include `t3 app` support.
43
44	## Desktop App
45
46	Download the latest release from
47	[GitHub Releases](https://github.com/pingdotgg/t3code/releases), or install from a package
48	registry.
49		36
50	Windows:	37	Choose a WSL distro in Settings → Connections to run agents and projects
		38	there. Install Node.js and provider CLIs inside that distro. T3 Code installs its
		39	matching server runtime there automatically; the first launch after an app
		40	update can take longer.
51		41
52	```bash	42	### Open a project from a terminal
53	winget install T3Tools.T3Code
54	```
55		43
56	macOS:	44	With the desktop app already running on the same machine:
57		45
58	```bash	46	```bash
59	brew install --cask t3-code	47	npx t3 app
60	```	48	```
61		49
62	Arch Linux:	50	This opens a new thread for the current directory, adding the project if needed.
		51	Pass a path, such as `npx t3 app ../my-project`, to open another directory. It requires
		52	the desktop app, so a standalone server or an SSH session is not enough. If the
		53	command cannot reach the app, start or update the desktop app and try again.
63		54
64	Stable:	55	## Mobile app
65		56
66	```bash	57	Install T3 Code from the
67	yay -S t3code-bin	58	[App Store](https://apps.apple.com/us/app/t3-code-remote-claude-more/id6787819824) or
68	```	59	[Google Play](https://play.google.com/store/apps/details?id=com.t3tools.t3code).
69		60	The phone connects to a server on another machine. Follow
70	Nightly:	61	[remote access](./remote-access.md) to link it through T3 Connect or a pairing URL.
71
72	```bash
73	yay -S t3code-nightly-bin
74	```
75
76	### Windows Subsystem for Linux
77
78	When the desktop app runs a WSL backend, it installs the matching server runtime into
79	`~/.t3/wsl-runtime` inside the selected distro. The first launch after installing or updating T3
80	Code may take a little longer while that release's runtime is extracted. Later launches reuse the
81	Linux-local copy so startup does not depend on reading application files through `/mnt/c`. After a
82	successful launch, T3 Code keeps the current runtime and one previous runtime for rollback and
83	removes older caches automatically. If a cached runtime stops working, T3 Code launches from the
84	application files under `/mnt/c` instead and reinstalls the runtime on the next launch.
85		62
86	## Providers	63	## Providers
87		64
88	T3 Code uses provider runtimes but does not bundle them. Install and authenticate each	65	Open Settings → Providers in the web or desktop app, select the environment,
89	provider's CLI, or use T3 Code's managed setup for Antigravity.	66	and enable the provider you want. Installation, login, and configuration belong
90		67	to that environment's machine, even when you connect from a phone or another
91	\| Provider \| CLI \| Default binary \| Log in with \|	68	computer.
92	\| ----------- \| ---------------------------------------------------------------------------------------------------------- \| ------------------ \| ---------------------------------- \|	69
93	\| Codex \| [Codex CLI](https://developers.openai.com/codex/cli) \| `codex` \| `codex login` \|	70	\| Provider \| Install and authenticate \|
94	\| Claude \| [Claude Code](https://claude.com/product/claude-code) \| `claude` \| `claude auth login` \|	71	\| ----------- \| -------------------------------------------------------------------------------------------- \|
95	\| Cursor \| [Cursor CLI](https://cursor.com/cli) \| `cursor-agent` \| `agent login` \|	72	\| Codex \| Install [Codex CLI](https://developers.openai.com/codex/cli), then run `codex login`. \|
96	\| Grok Build \| [Grok Build CLI](https://x.ai/cli) \| `grok` \| `grok login` \|	73	\| Claude \| Install [Claude Code](https://claude.com/product/claude-code), then run `claude auth login`. \|
97	\| OpenCode \| [OpenCode](https://opencode.ai) \| `opencode` \| `opencode auth login` \|	74	\| Cursor \| Install [Cursor CLI](https://cursor.com/cli), then run `agent login`. \|
98	\| Antigravity \| [Official ACP agent](https://github.com/agentclientprotocol/registry/blob/main/antigravity-acp/agent.json) \| Managed by T3 Code \| Sign in with Google in T3 Code \|	75	\| Grok Build \| Install [Grok Build CLI](https://x.ai/cli), then run `grok login`. \|
99		76	\| OpenCode \| Install [OpenCode](https://opencode.ai), then run `opencode auth login`. \|
100	Codex and Claude are on by default. Cursor, Grok Build, OpenCode, and Antigravity are off by	77	\| Antigravity \| Install and sign in with Google from T3 Code's provider settings. \|
101	default. Turn them on in Settings > Providers when you want to use them.	78
102		79	Provider CLIs must be on the server's `PATH`. If T3 Code cannot find one, set its
103	For Antigravity, select the environment in provider settings, then install and sign in there.	80	Binary path in provider settings, especially when using a version manager.
104	The runtime and credentials stay on that environment, even when you use a phone or remote	81	Cursor's executable is `cursor-agent`, although its login command is
105	browser. See [Antigravity setup](./providers-antigravity.md) for Google sign-in, remote callback	82	`agent login`. Antigravity can use its managed runtime without a `PATH` entry.
106	steps, and supported hosts.	83
107		84	Add another provider instance for a separate account or configuration. Each
108	Cursor is the one to watch: install Cursor CLI, which provides the `cursor-agent` binary that	85	instance can have its own environment variables, such as API keys or a custom
109	T3 Code looks for, but authenticate with `agent login`, not `cursor-agent login`.	86	base URL. Mark secret values as sensitive; after saving, T3 Code does not display
110		87	their original values.
111	Grok models that support adjustable reasoning show a Reasoning control beside the model picker.	88
112	The available levels and default come from the installed Grok Build CLI, so they can vary by model	89	For provider-specific setup and accounts, see [Codex](./providers-codex.md),
113	and CLI version.	90	[Claude](./providers-claude.md), [OpenCode](./providers-opencode.md), and
114		91	[Antigravity](./providers-antigravity.md).
115	Run CLI login commands on the machine running the T3 Code server, not on the device you browse	92
116	from. Antigravity uses its sign-in controls in T3 Code instead of a CLI login command.	93	## Next steps
117		94
118	### Binary Discovery	95	- [Working with threads](./thread-sidebar.md): start tasks and organize parallel work.
119		96	- [Permission modes](./permission-modes.md): choose when agents ask before acting.
120	Each provider CLI must be on the server's `PATH`, or have an explicit binary path set in	97	- [Remote access](./remote-access.md): connect from another device.
121	Settings → the provider instance → Binary path. Use the explicit path when a version	98	- [Running in the background](./background-service.md): keep a Linux or macOS host available.
122	manager or a non-standard install location keeps the CLI off the `PATH` of the shell that	99	- [Updating T3 Code](./updating.md): update the app and connected servers.
123	started T3 Code.
124
125	Antigravity can use its managed runtime without a `PATH` entry. Its optional Binary path
126	overrides the managed runtime and must point to the official ACP executable.
127
128	### When Auth Is Needed
129
130	Provider auth is required before you start a session with that provider, not before you start
131	T3 Code. You can install T3 Code, open it, and add providers afterwards. A provider that is not
132	authenticated shows its status and setup instructions in Settings.
133
134	For multi-account setups, see [Codex](./providers-codex.md), [Claude](./providers-claude.md), and
135	[Antigravity](./providers-antigravity.md#accounts-and-removal).
136
137	## Next Steps
138
139	- [Permission modes](./permission-modes.md): how much T3 Code asks before acting
140	- [Remote access](./remote-access.md): connect from a phone, tablet, or another desktop
141	- [Keeping T3 Code in sync](./updating.md): client and server version skew
142	- [Running in the background](./background-service.md): Linux background service

docs/user/keybindings.md+46-93

...	@@ -1,14 +1,13 @@	...	@@ -1,14 +1,13 @@
1	# Keybindings	1	# Keybindings
2		2
3	Edit keybindings from Settings → Keybindings. That page lists every command, its current	3	Customize shortcuts in Settings → Keybindings on web and desktop. That page
4	shortcut, whether it is a default or your own, and warns about conflicts.	4	also lists the command IDs and defaults available in your version.
5		5
6	The same configuration lives in `~/.t3/userdata/keybindings.json` on the machine running the	6	## Edit the configuration file
7	server, if you prefer editing it directly. T3 Code writes the built-in defaults into that file on
8	first run, and adds any new defaults on later startups unless a rule of yours already claims the
9	command or the shortcut.
10		7
11	The file is a JSON array of rules.	8	Keybindings live on the environment's machine, in
		9	`~/.t3/userdata/keybindings.json` by default. You can edit this file directly.
		10	It is a JSON array of rules:
12		11
13	```json	12	```json
14	[	13	[
...	@@ -17,109 +16,63 @@ The file is a JSON array of rules.	...	@@ -17,109 +16,63 @@ The file is a JSON array of rules.
17	]	16	]
18	```	17	```
19		18
20	Invalid rules are ignored. An invalid file is ignored entirely, and the server logs a warning.	19	T3 Code creates the file with its defaults and adds new defaults on later startups.
		20	New defaults do not replace commands you customized. If a new default overlaps one
		21	of your shortcuts, [rule order](#precedence) decides which runs.
		22	Invalid rules are ignored; if the file cannot be parsed, T3 Code uses defaults.
21		23
22	## Rule Shape	24	## Rule shape
23		25
24	- `key` (required): shortcut string, like `mod+j`, `ctrl+k`, `cmd+shift+d`	26	Each rule requires a `key` shortcut and a `command` ID. An optional `when`
25	- `command` (required): the command ID to run	27	expression restricts when it runs.
26	- `when` (optional): boolean expression controlling when the shortcut is active
27		28
28	## Key Syntax	29	Project scripts use `script.{id}.run`, such as `script.test.run`.
29		30
30	Modifiers: `mod` (`cmd` on macOS, `ctrl` elsewhere), `cmd` / `meta`, `ctrl` / `control`, `shift`,	31	## Key syntax
31	`alt` / `option`.
32		32
33	Examples: `mod+j`, `mod+shift+d`, `ctrl+l`, `cmd+k`.	33	Join modifiers and a key with `+`, such as `mod+shift+d` or `ctrl+l`.
		34	`mod` means Command on macOS and Control elsewhere. Other modifiers are
		35	`cmd` / `meta`, `ctrl` / `control`, `alt` / `option`, and `shift`.
34		36
35	## Commands	37	## When conditions
36		38
37	Commands are IDs like `terminal.toggle`, `commandPalette.toggle`, `preview.refresh`, and	39	Available context keys are `terminalFocus`, `terminalOpen`, `previewFocus`,
38	`chat.new`. Project scripts are addressable as `script.{id}.run`, for example `script.test.run`.	40	`previewOpen`, and `modelPickerOpen`. Unknown keys evaluate to `false`.
39		41
40	`filePicker.toggle` opens file search for the active project and defaults to `mod+p`.	42	Combine keys with `!` for not, `&&` for and, `\|\|` for or, and parentheses:
41	`projectSearch.toggle` searches inside the active project's files and defaults to `mod+shift+f`.
42	Repeating either shortcut closes that search, and switching shortcuts replaces the open search.
43	`themeEditor.toggle` opens or closes the floating theme editor and defaults to
44	`mod+alt+shift+t`. Select a color label to spotlight the elements that use it; select the label
45	again to clear the spotlight. The swatch and hex field keep that color selected while you edit it.
46	Advanced mode groups related app tokens into a smaller set of color families. Changing a family
47	updates its paired text and interaction states while leaving every unrelated imported color intact.
48	Use Inspect to pick an element in the app and reveal its color token. Inspect disarms after one
49	successful pick; its hover glow and badge preview the element and color family that click will select.
50	Cancel or `Escape` exits Inspect and clears its selection and spotlight.
51		43
52	`rightPanel.toggleMaximized` maximizes or restores the open right panel. It has no default shortcut,	44	```json
53	so add one in Settings → Keybindings if you want to use it.	45	{ "key": "mod+j", "command": "terminal.toggle", "when": "terminalOpen && !terminalFocus" }
54		46	```
55	`rightPanel.close` closes the active right panel tab and defaults to `mod+w`. Press it again to close
56	the next tab. With the terminal focused, `mod+w` closes the terminal instead, and with nothing left
57	to close it closes the desktop window as before. Browsers reserve `mod+w` for closing their own tab
58	and never pass it to the page, so in a browser rebind this command (and `terminal.close`) to a
59	shortcut the browser leaves alone, such as `alt+w`.
60		47
61	`thread.copyReference` copies the active thread's pull request link, or its thread ID when no pull	48	## Precedence
62	request is available. Its default shortcut is `mod+shift+c`, and it does not replace terminal copy
63	while the terminal has focus.
64		49
65	`thread.settle` settles the active thread or restores it when it is already settled. Its default	50	The last rule whose key and condition both match wins, even if it belongs to a
66	shortcut is `mod+shift+s`, and it does not run while the terminal has focus.	51	different command. Put a more specific rule after a general one when they share
		52	a shortcut.
67		53
68	`thread.pin` pins the active thread to the pinned section of the sidebar, or unpins it when it is	54	## Commands with special behavior
69	already pinned. Its default shortcut is `mod+shift+p`, and it does not run while the terminal has
70	focus. See [Organizing threads](./thread-sidebar.md) for how pinned threads are ordered.
71		55
72	The command palette searches settings, active thread titles, projects, branches, user messages, and	56	`chat.new` may ask you to choose a project when there is more than one.
73	final agent responses across connected environments. A setting result opens its exact control or	57	`chat.newLocal` skips that chooser. Both use your
74	section. Message matches show one labeled excerpt while keeping the thread's project, branch, and	58	[new-thread defaults](./thread-sidebar.md#start-a-thread).
75	machine context visible. Message search begins after two characters and uses SQLite's ASCII
76	case-insensitive matching.
77		59
78	The full command list and the current defaults are shown in Settings → Keybindings, which	60	## Reserved shortcuts
79	always matches the build you are running. Use that rather than a copied list.
80		61
81	Note that `chat.new` and `chat.newLocal` both create a thread through the same path. A new thread	62	In the desktop app, `mod+w` closes the focused terminal or the active right-panel
82	inherits the project you were in, along with model and mode selections. Branch, worktree, and	63	tab. When nothing remains to close, it closes the window. In a browser, `mod+w`
83	environment mode always come from your configured defaults, not from the thread you were looking	64	closes the browser tab; rebind `rightPanel.close` and `terminal.close` to an available
84	at. To keep a worktree, use the explicit "new thread in this worktree" action in the branch	65	shortcut such as `alt+w`.
85	toolbar. The only difference between the two commands: with the current sidebar and more than one
86	project, `chat.new` opens a project chooser first.
87		66
88	Background submission from a new thread is the exception. `mod+enter` starts that thread and opens	67	Many defaults include `!terminalFocus` so they do not intercept terminal input.
89	another new thread with the same workspace mode and base branch. New worktree remains selected,	68	Keep that condition when remapping them if you want the same behavior.
90	but the new thread does not reuse the worktree created for the thread that just started.
91		69
92	## Desktop quit shortcut	70	## Desktop quit shortcut
93		71
94	Use `Cmd+Q` on macOS or `Ctrl+Q` on Windows and Linux. In the default Hold mode, hold the	72	Use `Cmd+Q` on macOS or `Ctrl+Q` on Windows and Linux. In the default Hold mode,
95	shortcut for 1.2 seconds or press it twice within 500 milliseconds. The second press quits	73	hold for 1.2 seconds or press twice within 500 milliseconds. Holding requires
96	immediately. You can keep Command or Control held between presses, or release both keys.	74	keyboard repeat; if repeat is disabled, use two presses or the application menu.
97
98	Hold mode needs keyboard repeat. If holding does not quit, use two quick presses or choose
99	Quit from the application menu.
100
101	Change Quit shortcut in Settings → General → Confirmations. Direct quits on
102	the first press. Double press requires two quick presses and does not accept a hold. The
103	application menu's Quit action always quits immediately.
104
105	## `when` Conditions
106
107	A `when` expression is evaluated against context keys describing the current UI state. The keys
108	the app supplies today are `terminalFocus`, `terminalOpen`, `previewFocus`, `previewOpen`, and
109	`modelPickerOpen`. The set is open and grows over time, so treat that as the current list rather
110	than a fixed one. Any key the running app does not supply evaluates to `false`.
111
112	Operators: `!` (not), `&&` (and), `\|\|` (or), and parentheses.
113
114	Examples:
115
116	- `"when": "terminalFocus"`
117	- `"when": "terminalOpen && !terminalFocus"`
118	- `"when": "!terminalFocus"`
119
120	## Precedence
121		75
122	- Rules are evaluated in array order.	76	Change Settings → General → Confirmations → Quit shortcut to Direct for a
123	- For a key event, the last rule where both `key` matches and `when` evaluates to `true` wins.	77	single press or Double press for two presses only. Choosing Quit from the
124	- Precedence is across commands, not only within the same command. A later rule for a different	78	application menu always quits immediately.
125	command can take a key away from an earlier one.

docs/user/mobile-appearance.md deleted-21

...	@@ -1,21 +0,0 @@
1	# Mobile appearance
2
3	T3 Code Mobile includes the T3 Code, T3 Chat, Grove, Ocean, Ember, and Iris themes. Each theme has
4	light and dark colors that apply throughout the app, including code reviews, file previews, the
5	terminal, native headers, and sheets.
6
7	On supported iOS versions, the new-task and thread composers, working timer, and scroll-to-end
8	button use the system glass material. Other platforms use a themed background.
9
10	To change themes:
11
12	1. Open Settings.
13	2. Select Appearance.
14	3. Choose a theme.
15	4. Select System, Light, or Dark.
16
17	Tap a theme card to use it for both light and dark appearance. To mix themes, tap the light or dark
18	preview circle inside a card to change only that appearance.
19
20	System follows the device appearance automatically. Theme, text, code, and terminal appearance
21	preferences are stored on the device.

docs/user/permission-modes.md+21-50

...	@@ -1,60 +1,31 @@	...	@@ -1,60 +1,31 @@
1	# Permission Modes	1	# Permission modes
2		2
3	A permission mode controls how much the agent does on its own and when it stops to ask you.	3	Permission modes control when an agent needs your approval to act. Choose a mode in the message
		4	composer; it applies to that thread.
4		5
5	The mode is set per thread, from the mode control in the message composer. Changing it in one	6	New threads start in Full access unless you choose another mode before sending. A thread
6	thread does not change any other thread. A thread created from inside another thread keeps that	7	created from another thread inherits its mode.
7	thread's mode; otherwise new threads start in Full access unless you pick something else
8	before sending.
9		8
10	## The Modes	9	\| Mode \| Behavior \|
		10	\| --------------------- \| ------------------------------------------------------------------------------------- \|
		11	\| Supervised \| Requests approval for commands and file changes. \|
		12	\| Auto-accept edits \| Approves file edits automatically; other actions can still require approval. \|
		13	\| Auto \| Uses the provider's automatic review to approve routine actions and ask about others. \|
		14	\| Full access \| Allows commands and edits without approval prompts. \|
11		15
12	Supervised: ask before commands and file changes. The agent pauses and shows you what it	16	Approve or reject requests in the conversation to let the agent continue. Permission modes do
13	wants to run or edit, and waits for approval. Work outside the workspace is restricted.	17	not prevent the agent from asking questions about the task.
14		18
15	Auto-accept edits: auto-approve edits, ask before other actions. File changes go through	19	## Provider differences
16	without prompting; commands and anything else still stop for approval.
17		20
18	Auto: routine actions proceed without you; risky ones still ask. How this is enforced depends	21	Providers enforce permissions differently. Some read-only actions can proceed in Supervised.
19	on the provider: Codex delegates routine approvals to an AI reviewer, Claude uses its own auto	22	Auto uses automatic review on Codex, Claude, and Cursor; providers without an equivalent,
20	permission mode, Cursor uses Smart Auto review, and providers without an equivalent (such as	23	including OpenCode and Antigravity, fall back to asking.
21	OpenCode and Antigravity) fall back to asking, like Supervised.
22
23	Full access: allow commands and edits without prompts. The default. The agent runs
24	unattended until it finishes or asks a question of its own.
25
26	Approvals appear inline in the conversation. Approve or reject one and the agent continues from
27	there.
28		24
29	For Grok, Always allow this session remembers the matching command or tool input. Other	25	For Grok, Always allow this session remembers the matching command or tool input. Other
30	actions still ask for approval. It does not change the thread to Full access.	26	actions still require approval.
31
32	Antigravity uses its own permission policy for each mode. T3 Code still shows any approval or
33	question the official agent sends in Full access. A remembered approval is available only
34	when the agent offers it for that action. Fixed-choice questions require one of the offered
35	answers and do not accept custom text.
36
37	## Choosing a Mode
38
39	Use Full access for work in a worktree or a sandbox you can throw away.
40
41	Use Supervised on a repository where an unwanted command is expensive, or the first time you
42	run an unfamiliar task.
43
44	Auto-accept edits suits refactors where the edits are the point and you only care about the
45	shell commands.
46
47	## Provider Behavior
48
49	Each provider maps these modes onto its own approval and sandbox settings. Codex, for example,
50	translates the mode into its approval policy and sandbox level, so Supervised runs the CLI
51	with prompting enabled and a restricted workspace while Full access disables both. Grok
52	threads do the same: Supervised starts Grok in ask mode even if your Grok CLI config is
53	set to always-approve, and Full access starts Grok with always-approve. The labels above
54	describe what you get; the exact per-provider translation is internal and may change.
55		27
56	Mobile offers the same four modes with the same labels and descriptions.	28	Antigravity can still send native approval requests in Full access. It only offers remembered
		29	approvals for actions that support them.
57		30
58	Antigravity's native `/plan` command requests a plan. It does not change the permission mode.	31	See the [provider guides](./install.md#providers) for setup and provider-specific limits.
59	T3 Code's separate Plan mode control is not available for Antigravity. See
60	[Antigravity](./providers-antigravity.md) for setup and thread limits.

docs/user/project-settings.md+11-25

...	@@ -1,32 +1,18 @@	...	@@ -1,32 +1,18 @@
1	# Customize a project icon	1	# Project settings
2		2
3	T3 Code selects a project icon automatically. It checks `t3.json`, common favicon and app icon	3	Open Settings → Projects and select a project to change its preferences.
4	paths, and icon links in project HTML files. If it does not find an image, it chooses a built-in
5	icon from the saved project name. In web and desktop, this icon stays the same when the sidebar
6	shows a repository label such as `owner/repo`.
7		4
8	To choose a different icon or emoji:	5	## Project icons
9		6
10	1. Open Settings and select Projects.	7	Choose an icon, emoji, or image from the project to make it easier to recognize. The choice applies
11	2. Select the project.	8	to every checkout in the project group and appears on connected clients. Choose Automatic to
12	3. Next to Project icon, select Choose icon.	9	let T3 Code detect an icon again.
13	4. Search the full Lucide icon set and choose a color, or switch to Emoji and choose or paste
14	an emoji.
15
16	To use an image from the project instead, select Choose file, search for an image, and select
17	it.
18
19	T3 Code supports SVG, PNG, ICO, JPEG, GIF, AVIF, and WebP files. The selected path applies to
20	each checkout in the project group and appears on your connected clients.
21
22	To use automatic detection again, select Automatic.
23		10
24	## Keep the default branch current	11	## Keep the default branch current
25		12
26	Turn on Automatically pull in a project's settings to keep its default-branch checkout current.	13	Enable Automatically pull to keep the default-branch checkout up to date with its configured
27	T3 Code checks in the background and when the server starts. It uses the branch's configured	14	upstream.
28	upstream and only performs a fast-forward pull when the checkout has no working-tree changes,
29	untracked files, or local commits.
30		15
31	The pull is skipped if the checkout is on another branch, has no upstream, or contains local work.	16	T3 Code only pulls when it can fast-forward and the checkout has no changed files, untracked files,
32	Pull failures do not prevent the server from starting.	17	or local commits. It skips checkouts on another branch or without an upstream. If a checkout has
		18	local work, resolve it yourself before automatic pulls can resume.

docs/user/providers-antigravity.md+89-152

...	@@ -1,198 +1,135 @@	...	@@ -1,198 +1,135 @@
1	# Antigravity	1	# Antigravity
2		2
3	T3 Code runs Google's official Antigravity ACP agent. By default it signs in with your personal	3	T3 Code runs Google's official Antigravity ACP agent on your selected environment.
4	Google account and uses that account's Antigravity access, including access provided by a	4	It has its own sign-in, separate from the Antigravity IDE or CLI. Google controls
5	Google AI subscription. It never falls back to a different sign-in method than the one you	5	which models and account access are available through this agent.
6	select.
7
8	The agent, files, conversation state, and Google credentials stay on the selected environment.
9	Your browser or phone controls that environment. Signing in to the Antigravity IDE or CLI does
10	not sign in this T3 Code provider.
11		6
12	## Set up Antigravity	7	## Set up Antigravity
13		8
14	On web or desktop, open Settings > Providers, select the device that runs your project,	9	On web or desktop, open Settings > Providers, choose the environment that runs
15	then select Antigravity. Provider setup is not available in the mobile app.	10	your project, and enable Antigravity. Install its runtime there, then choose
16		11	Sign in with Google and complete the browser sign-in. Wait for T3 Code to confirm
17	1. Choose Enable Antigravity. Antigravity is off by default.	12	account access and load models before starting a thread. Provider setup is not
18	2. Choose Install Antigravity. T3 Code downloads the official runtime from Google to that	13	available in the mobile app.
19	environment. Installation continues if you leave the page or reconnect.
20	3. Choose Sign in with Google.
21	4. Choose Open sign-in page. You can use Copy sign-in link to open it in another browser.
22	5. Complete Google sign-in. Use the account you use for Antigravity.
23	6. Wait for T3 Code to confirm sign-in and load the model choices. Select an Antigravity model
24	in the thread's model picker.
25		14
26	Setup requires a connection with permission to operate the environment. If setup is unavailable	15	Installation continues if you leave settings or reconnect. Setup requires
27	on an older server, update that environment first.	16	permission to operate the environment; update an older server if it does not offer
		17	Antigravity setup.
28		18
29	### Sign in from a remote device	19	### Sign in from a remote device
30		20
31	Google returns to a `127.0.0.1` address on the device running your browser. If that is the same	21	Google returns to a `127.0.0.1` address. It can finish directly when your browser is
32	machine as the T3 Code environment, sign-in can finish directly.	22	on the environment's machine. From another device, the final page will usually
		23	fail to load because the sign-in listener is on the environment.
33		24
34	On a phone or another computer, the final page will usually fail to load. This is expected.	25	Copy the full return address, including everything after `?`, into the return URL
35	Copy the full address from the browser, including everything after `?`, and paste it into the	26	field in the web or desktop client where you started setup, then choose
36	return URL field in the web or desktop client where you started setup. Choose Continue. Do not	27	Continue. Keep the original address; do not replace it with the server's
37	change the address to your server's hostname.	28	hostname. Only that T3 Code sign-in session can finish the attempt. If it expires,
		29	retry sign-in and use the new link.
38		30
39	Return to the same T3 Code client and environment where you started sign-in. Another client	31	The return URL contains a temporary sign-in code. Paste it only into the setup
40	can see that sign-in is in progress, but cannot complete that attempt. The setup screen shows	32	field. A successful callback page alone does not confirm account access; wait for
41	the expiry time. If it expires, choose Retry Google sign-in and use the new link.	33	T3 Code's confirmation.
42
43	The return URL contains a temporary sign-in code. Paste it only into the setup field, not into
44	a thread or bug report. T3 Code waits for Google's agent to confirm sign-in. A successful
45	callback page alone does not prove account access.
46		34
47	### Other sign-in methods	35	### Other sign-in methods
48		36
49	Sign-in method in the Antigravity provider settings on web or desktop selects how the	37	Choose Sign-in method in the Antigravity provider settings:
50	agent authenticates.
51
52	\| Method \| What you enter \| How it signs in \|
53	\| -------------------------- \| ---------------------------------------- \| ------------------------------- \|
54	\| Google account \| Nothing \| Google sign-in page \|
55	\| Gemini Enterprise \| GCP project and GCP location \| Google sign-in page \|
56	\| Gemini API key \| API key \| Choose Connect. No browser. \|
57	\| Agent Platform (Vertex AI) \| API key, or GCP project and GCP location \| Choose Connect. No browser. \|
58		38
59	Gemini Enterprise resolves your license for the project and location you enter. Agent Platform	39	\| Method \| Credentials \|
60	with a project and location uses Application Default Credentials on the environment. API keys	40	\| -------------------------- \| -------------------------------------------------------------------------------------------- \|
61	are stored in plain text in T3 Code settings on that environment and are passed only to the	41	\| Google account \| Personal Google sign-in in the browser \|
62	Antigravity agent process. Ambient `GEMINI_API_KEY` or `GOOGLE_*` variables on the environment	42	\| Gemini Enterprise \| Browser sign-in, GCP project, and GCP location \|
63	are ignored.	43	\| Gemini API key \| API key; choose Connect without a browser \|
		44	\| Agent Platform / Vertex AI \| API key, or GCP project and location with Application Default Credentials on the environment \|
64		45
65	Changing the method stops the instance's sessions. Sign out or disconnect before you switch	46	The Antigravity API key field is stored in plain text in settings on the
66	accounts.	47	environment. The agent uses the method and credentials selected for this instance;
		48	ambient `GEMINI_API_KEY` and Google credential variables do not override them.
		49	Changing the method stops the instance's sessions. Sign out before replacing an
		50	account.
67		51
68	## Runtime installation	52	## Runtime installation
69		53
70	Managed downloads are available for these environment hosts:	54	Managed installation supports Apple Silicon macOS, Linux x64 or ARM64, and Windows
71		55	x64 or ARM64. Intel Macs can connect to a supported remote environment. Allow
72	\| Host \| Architecture \|	56	several GB of free disk space, especially on Linux.
73	\| ------- \| ------------- \|
74	\| macOS \| Apple Silicon \|
75	\| Linux \| x64 or ARM64 \|
76	\| Windows \| x64 or ARM64 \|
77
78	Google does not publish a local Intel Mac runtime. Use an Intel Mac as a client connected to
79	a supported remote environment.
80
81	The current Linux x64 runtime downloads about 682 MB and uses about 2.01 GB after extraction.
82	Allow at least 3 GB free for installation. An update keeps the previous runtime too.
83	T3 Code does not download it until you choose to install it.
84
85	On web or desktop, Update Antigravity appears when T3 Code has a newer managed release.
86	Running sessions keep their current runtime. New sessions use the installed update.
87		57
88	### Use a manual installation	58	### Use a manual installation
89		59
90	Download the correct archive from the [official ACP Registry][registry] and extract both the	60	Download the archive for your environment from the [official ACP Registry][registry].
91	ACP executable and its `localharness_external` helper into the same directory. Keep both files	61	Extract the ACP executable and its `localharness_external` helper into the same
92	at the same version and make them executable on macOS or Linux. Windows uses `.exe` files.	62	directory, at the same version. Make both executable on macOS or Linux; Windows
		63	uses `.exe` files.
93		64
94	On web or desktop, set Binary path in the Antigravity provider settings to the ACP	65	Set Binary path to the ACP executable on the environment and update it yourself.
95	executable on the selected environment. Do not point it at the helper or the Antigravity IDE.	66	Leave the field blank to use the managed runtime, or a compatible executable on
96		67	`PATH` if no managed runtime is installed.
97	A nonempty Binary path takes priority. With the field empty, T3 Code uses its managed
98	runtime, then an installation on the environment's `PATH`. An invalid explicit path reports
99	an error instead of selecting another installation. T3 Code does not update or remove manual
100	installations. Clear Binary path to use managed installation controls.
101		68
102	## Models and threads	69	## Models and threads
103		70
104	The current official ACP exposes Gemini models only. T3 Code uses the model IDs and names	71	The model list comes from your Antigravity account and can differ from other
105	returned for your account, including any model choices with different thinking levels. Models	72	Antigravity apps. A resumed thread keeps its selected model. If access to that
106	available in other Antigravity apps might not be available through this agent.	73	model ends, select another available model before continuing.
107	The model picker updates when a running session reports new model choices.
108
109	New threads use Gemini 3.8 Flash (High) when your account offers it. Older Gemini generations
110	stay available under Legacy models in the picker.
111
112	Threads keep their selected model when you resume them. If that model is no longer available,
113	T3 Code asks you to select an available model instead of silently changing it.
114
115	Use Antigravity's native `/plan` command to request a plan. T3 Code's separate Plan mode control
116	is not available for this provider.
117		74
118	Project skills should use `.agents/skills`. T3 Code also discovers `.gemini/skills` and the legacy	75	Use Antigravity's native `/plan` command for planning. T3 Code's separate Plan mode
119	`.agent/skills` location. When multiple locations define the same skill name, `.gemini/skills`	76	is unavailable. Tool approvals follow [Permission modes](./permission-modes.md).
120	takes precedence, followed by `.agents/skills` and then `.agent/skills`.	77	Questions with fixed choices still need one of the offered answers, even in
		78	Full access.
121		79
122	Antigravity reads and edits workspace files through T3 Code. Each write shows up as a file	80	T3 Code keeps conversation history and file diffs, but Antigravity cannot rewind
123	change approval with the content, so Supervised and Auto-accept edits behave the same way	81	its conversation. Reverting a thread or editing and resubmitting an earlier turn
124	they do for other providers. Attach images, PDFs, text files, or audio clips to a message and	82	is unavailable. Continue with a follow-up message or start a new thread.
125	the agent receives them directly.
126		83
127	When the agent offers Allow for this thread on a shell or web tool, T3 Code shows Google's	84	### Skills and attachments
128	prompt injection warning next to that choice. Untrusted content could re-run the same action
129	without asking again.
130		85
131	Antigravity can ask you to choose from a fixed set of answers. Select one of the offered	86	Put project skills in `.agents/skills`. T3 Code also reads `.gemini/skills` and the
132	choices. These questions do not accept custom text and still appear in Full access mode.	87	legacy `.agent/skills` directory. Among these project locations, the first copy
133	See [Permission modes](./permission-modes.md) for tool approvals.	88	wins in this order: `.gemini/skills`, `.agents/skills`, `.agent/skills`. See
		89	[commands and skills](./composer.md#commands-and-skills) for invoking them.
134		90
135	T3 Code keeps thread history and file diffs. Antigravity does not support conversation rewind,	91	Antigravity accepts images, PDFs, text files, and supported audio formats directly.
136	so reverting a thread or editing and resubmitting an earlier turn is unavailable. Send a	92	Its limits are 1 MiB per text file, 10 MiB per image, 20 MiB per audio clip, and
137	follow-up message or start a new thread instead.	93	50 MiB total attachments per message. Unsupported formats are rejected. These
		94	limits can be lower than the general upload limit; uploading a file does not
		95	mean this provider can use it.
138		96
139	### Subagents	97	### Subagents
140		98
141	Subagent launches appear as Antigravity subagent batch in Agents on web and desktop,	99	Antigravity groups subagent activity into batches. You cannot open or control
142	and in the work log on mobile. One launch can start several agents. The batch stays active	100	individual subagents, and an idle batch does not confirm that every child
143	after launch while the parent turn runs. When that turn ends, the entry becomes idle and	101	succeeded. See [agent work](./thread-sidebar.md#inspect-agent-work) for where to
144	states that individual agent status is unavailable. Launch errors remain visible.	102	inspect activity.
145	The conversation summary counts launches as batches and shows idle or stopped batches
146	without a completion checkmark.
147
148	The official ACP agent does not send individual child status, names, models, token usage,
149	or reply ownership. T3 Code cannot show separate child entries or separate child replies
150	from the parent conversation. The launch description is not a child result. Batch entries
151	cannot be opened or controlled as separate threads.
152		103
153	## Accounts and removal	104	## Accounts and removal
154		105
155	Each Antigravity provider instance has its own Google sign-in on its environment. Use	106	Add an Antigravity provider instance for each Google account in
156	Add provider in web or desktop provider settings to create a separate instance for another	107	Settings > Providers on web or desktop. Each has its own sign-in; downloaded
157	account. To replace an instance's account, sign out first, then sign in again.	108	runtimes are shared on the environment.
158
159	\| Action \| Result \|
160	\| ------------------------- \| ----------------------------------------------------------------------------------------------------------------------------- \|
161	\| Disable Antigravity \| Stops the instance's sessions. Keeps Google sign-in, thread history, and files. \|
162	\| Sign out of Google \| Stops the instance's sessions and removes its saved Google credentials. Keeps thread history and files. \|
163	\| Remove downloaded runtime \| Removes the runtime shared by Antigravity instances on that environment. Keeps Google credentials, thread history, and files. \|
164
165	Send `/logout` by itself in an Antigravity thread to sign out that provider instance. This has
166	the same effect as Sign out of Google, including stopping its other sessions.
167
168	Before removing a managed runtime, disable the instances that use it and cancel any active
169	installation. T3 Code refuses removal while the runtime is in use. An explicit Binary path
170	that points into the managed runtime must be cleared first.
171		109
172	## Account access and errors	110	\| Action \| Effect \|
		111	\| ------------------------- \| ----------------------------------------------------------------- \|
		112	\| Disable \| Stops the instance's sessions and keeps its Google sign-in. \|
		113	\| Sign out of Google \| Stops the instance's sessions and removes its saved Google login. \|
		114	\| Remove downloaded runtime \| Removes the shared installation and keeps Google credentials. \|
173		115
174	Google controls account eligibility, models, and usage limits. T3 Code does not report your	116	All three keep thread history and workspace files. Sending `/logout` by itself in
175	paid-plan tier or remaining subscription quota. See Google's [Antigravity plans][plans] and	117	a thread signs out its instance, including stopping that instance's other sessions.
176	[personal Google sign-in guide][google-setup].	118	Sign out, then sign in again to replace an account.
177		119
178	After an environment restarts, Google sign-in can show as not checked until an authenticated	120	Before removing a managed runtime, disable its instances and cancel any active
179	session succeeds. You can continue an existing thread. Antigravity checks saved Google sign-in	121	installation. Clear any explicit binary path pointing into that runtime. Removal
180	when the session starts. An unchecked status does not require signing in again.	122	is refused while the runtime is in use.
181		123
182	To check account access and reload models on web or desktop, open Settings > Providers	124	## Check access and troubleshoot
183	and select the circular arrow beside Checked at the top of the page. Its tooltip says
184	Refresh provider status. On mobile, use Refresh models in the model picker.
185	Refresh uses saved Google sign-in and does not open a login page. If sign-in is required,
186	use the provider's setup controls on web or desktop. Automatic status checks verify the
187	installation only.
188		125
189	The packaged runtime can be slow to start, especially on Windows. Health checks, model refresh,	126	To check access and reload models, use Refresh provider status in web or desktop
190	and sign-out each allow up to 90 seconds before reporting a timeout.	127	provider settings, or Refresh models in mobile thread settings. If asked to
		128	sign in again, use setup on web or desktop.
191		129
192	If Google reports `SUBSCRIPTION_REQUIRED`, an account restriction, or a usage limit, read the	130	If Google reports `SUBSCRIPTION_REQUIRED`, an account restriction, or a usage limit,
193	provider's message. A finished turn can contain an upstream error instead of completed work.	131	follow the provider's message and any retry time. See [Google's account plans][plans]
194	Use any retry time Google supplies. T3 Code does not switch to an API key to get past the limit.	132	for eligibility.
195		133
196	[registry]: https://github.com/agentclientprotocol/registry/blob/main/antigravity-acp/agent.json	134	[registry]: https://github.com/agentclientprotocol/registry/blob/main/antigravity-acp/agent.json
197	[plans]: https://antigravity.google/docs/plans	135	[plans]: https://antigravity.google/docs/plans
198	[google-setup]: https://antigravity.google/docs/ide/extensions/zed

docs/user/providers-claude.md+63-210

...	@@ -1,236 +1,89 @@	...	@@ -1,236 +1,89 @@
1	# Claude	1	# Claude
2		2
3	This guide is for people who want to use more than one Claude setup in T3 Code. For Codex, see	3	T3 Code uses Claude Code's login and configuration. Start with the default provider
4	[Codex](./providers-codex.md). For first-time setup, see [Install T3 Code](./install.md).	4	for one account; [provider setup](./install.md#providers) covers installation and
		5	shared provider settings.
5		6
6	Common reasons:	7	## Separate accounts or configurations
7		8
8	- use separate work and personal Claude accounts	9	Use a separate Claude config directory for each account. This also works for named
9	- try a different Claude Code configuration without disturbing your main setup	10	presets that need different Claude settings or a router connection.
10	- run Claude through a router such as Claude Code Router
11	- use external providers exposed through a Claude-compatible workflow
12		11
13	## I Only Use One Claude Account	12	Keep your existing account in the default directory. On the environment's machine,
14		13	create the second login:
15	Use the default provider.
16
17	Log in with Claude Code normally:
18
19	```bash
20	claude auth login
21	```
22
23	In T3 Code Settings, your Claude provider can stay like this:
24
25	```text
26	Display name: Claude
27	Binary path: claude
28	CLAUDE_CONFIG_DIR path: empty
29	```
30
31	An empty `CLAUDE_CONFIG_DIR path` means T3 Code uses Claude Code's normal config directory.
32
33	When you set this field, T3 Code points Claude Code at that directory with the
34	`CLAUDE_CONFIG_DIR` environment variable. It does not change `HOME`, so your system keychain and
35	the rest of your environment stay as they are.
36
37	## Reduce Context Usage
38
39	In Settings, open your Claude provider and set Auto-compact after to a token count between
40	`100000` and `1000000`. For example, `300000` compacts the conversation into a summary once it
41	reaches about 300,000 tokens, without changing the model's context window. Leave the field
42	empty to keep Claude Code's default behavior.
43
44	On web and desktop, when you return to an older Claude thread with a large context, T3 Code
45	offers to compact the conversation before you continue. You can also select Compact context
46	from the context meter. On every client, you can enter `/compact` in the message composer, and
47	Claude can show its own resume prompt when you continue an old session.
48
49	## Where Claude Skills Are Loaded
50
51	T3 Code looks for Claude skills in the Claude config directory's `skills` folder and
52	`<workspace>/.claude/skills`, the two places Claude Code loads them from.
53
54	If the same skill name exists in more than one folder, the one in the Claude config directory
55	wins, the same way Claude Code resolves it.
56
57	A skill set to `off` in Claude Code's `skillOverrides` is left out of both composer menus. A skill
58	marked `disable-model-invocation` still appears, because you start it yourself when you pick it.
59	Claude Code runs one skill per message; when a message names several, the last one runs directly and
60	Claude starts the others through its Skill tool, which refuses skills marked
61	`disable-model-invocation`.
62
63	## I Want Work And Personal Claude Accounts
64
65	Use a different Claude config directory for each account.
66
67	Example:
68
69	```text
70	default config dir work account
71	~/.claude_personal_home personal account
72	```
73
74	### Set Up The First Account
75
76	Log in normally:
77
78	```bash
79	claude auth login
80	```
81
82	In T3 Code Settings:
83
84	```text
85	Display name: Claude Work
86	Binary path: claude
87	CLAUDE_CONFIG_DIR path: empty
88	```
89
90	### Set Up The Second Account
91
92	Log in with a separate config directory:
93
94	```bash
95	mkdir -p ~/.claude_personal_home
96	CLAUDE_CONFIG_DIR=~/.claude_personal_home claude auth login
97	```
98
99	Use `CLAUDE_CONFIG_DIR`, not `HOME`. Setting `HOME` writes the login to
100	`~/.claude_personal_home/.claude`, which is not where T3 Code looks.
101
102	Then add another Claude provider in T3 Code:
103
104	```text
105	Display name: Claude Personal
106	Binary path: claude
107	CLAUDE_CONFIG_DIR path: ~/.claude_personal_home
108	```
109
110	Use the email shown in Settings to confirm each provider is using the intended account. Emails are
111	blurred by default; click the blurred email to reveal it.
112
113	## Can I Switch Claude Accounts In An Existing Thread?
114
115	Usually, no.
116
117	T3 Code only offers Claude providers that use the same config directory for an existing thread. A
118	different config directory is treated as a different Claude environment.
119
120	This is different from the recommended Codex setup. Claude Code keeps account and local state across
121	multiple files under its config directory, so T3 Code keeps separate config directories isolated
122	instead of trying to share part of the state.
123
124	## I Want To Use OpenRouter
125
126	Use this when you want Claude Code to talk to OpenRouter directly, without running a local router.
127	This is the simplest external-provider setup.
128
129	OpenRouter provides a Claude Code integration through Claude's Anthropic-compatible environment
130	variables.
131
132	### Configure A Claude OpenRouter Provider
133
134	Add or edit a Claude provider in T3 Code Settings:
135
136	```text
137	Display name: Claude OpenRouter
138	Binary path: claude
139	CLAUDE_CONFIG_DIR path: ~/.claude_openrouter_home
140	```
141
142	In that provider's Environment variables section, add:
143
144	```text
145	ANTHROPIC_BASE_URL https://openrouter.ai/api
146	ANTHROPIC_AUTH_TOKEN sk-or-... Sensitive
147	ANTHROPIC_API_KEY Empty value
148	```
149
150	Mark `ANTHROPIC_AUTH_TOKEN` as sensitive. T3 Code stores the value as a server secret and does not
151	send it back to the app after saving.
152
153	If you want this setup isolated from your normal Claude account, create that home first:
154		14
155	```bash	15	```bash
156	mkdir -p ~/.claude_openrouter_home	16	mkdir -p ~/.claude_personal
		17	CLAUDE_CONFIG_DIR=~/.claude_personal claude auth login
157	```	18	```
158		19
159	If you previously used the same Claude home with a normal Anthropic login, run `/logout` in a Claude	20	Add another Claude instance in Settings > Providers:
160	Code session for that home before using OpenRouter. Otherwise Claude Code may keep using cached
161	Anthropic credentials instead of the OpenRouter token.
162		21
163	### Pick OpenRouter Models	22	\| Instance \| Binary path \| CLAUDE_CONFIG_DIR path \|
		23	\| --------------- \| ----------- \| ---------------------- \|
		24	\| Claude Work \| `claude` \| Leave empty \|
		25	\| Claude Personal \| `claude` \| `~/.claude_personal` \|
164		26
165	OpenRouter can route Claude Code's default model roles to OpenRouter model IDs.	27	An empty config-directory setting uses Claude Code's normal configuration. The
		28	custom setting changes `CLAUDE_CONFIG_DIR`, leaving `HOME` and the system keychain
		29	location intact. Use the same variable for the login command. Setting `HOME`
		30	instead can put credentials where this provider will not find them.
166		31
167	Example:	32	Check the account reported in provider settings after signing in. Existing
		33	threads can switch only between Claude instances with the same config directory.
		34	Separate account directories stay isolated, including their local conversation
		35	state. Claude does not have Codex's shared-home and shadow-home arrangement.
168		36
169	```text	37	For presets that differ only in API keys or endpoints, use the instance's
170	ANTHROPIC_DEFAULT_OPUS_MODEL anthropic/claude-opus-4.6	38	Environment variables. Variable assignments do not belong in Launch arguments.
171	ANTHROPIC_DEFAULT_SONNET_MODEL anthropic/claude-sonnet-4.6
172	ANTHROPIC_DEFAULT_HAIKU_MODEL anthropic/claude-haiku-4.5
173	CLAUDE_CODE_SUBAGENT_MODEL anthropic/claude-sonnet-4.6
174	```
175
176	Add those to the same provider's Environment variables section if you want stable model choices.
177		39
178	### Verify OpenRouter Is Being Used	40	## Compact long conversations
179		41
180	Open a Claude session and run:	42	Set Auto-compact after in the Claude provider settings to an integer between
		43	`100000` and `1000000`. For example, `300000` asks Claude to summarize at about
		44	300,000 tokens. This changes when compaction happens, not the model's context
		45	window. Leave it empty for Claude Code's default.
181		46
182	```text	47	You can also send `/compact` in an existing conversation. Web and desktop offer
183	/status	48	Compact context from the context meter and may suggest it when you return to
184	```	49	a large older thread. See [commands and skills](./composer.md#commands-and-skills)
		50	for using composer commands.
185		51
186	You should see the Anthropic base URL set to:	52	## Skills
187		53
188	```text	54	Claude skills come from the config directory's `skills` folder and the project's
189	https://openrouter.ai/api	55	`.claude/skills` folder. If both define the same name, the config-directory copy
190	```	56	wins. Skills disabled in Claude's settings do not appear in the composer.
191		57
192	You can also check the OpenRouter activity dashboard for requests from your API key.	58	Use `$` in the composer to select a skill. Skills marked `disable-model-invocation`
193		59	can still be started by you. Invoke those one per message: Claude directly runs
194	### Common OpenRouter Mistakes	60	only the last named skill and may try to start earlier ones through its Skill
195		61	tool, which refuses skills reserved for manual invocation.
196	- Use `https://openrouter.ai/api`, not `https://openrouter.ai/api/v1`, for Claude Code.
197	- Set `ANTHROPIC_AUTH_TOKEN` to your OpenRouter API key.
198	- Set `ANTHROPIC_API_KEY` to an empty string so Claude Code does not try to use an Anthropic login.
199	- Put these variables on the Claude provider instance, not in global shell startup files.
200
201	OpenRouter's setup can change over time. Use its upstream Claude Code guide for the current details:
202	<https://openrouter.ai/docs/guides/guides/claude-code-integration>.
203
204	## I Want To Use Claude Code Router
205
206	Claude Code Router is useful when you want a local routing layer with more control than a direct
207	OpenRouter setup.
208
209	T3 Code does not need a special Claude Code Router provider. Treat the router as a Claude
210	environment: give a Claude provider its own `CLAUDE_CONFIG_DIR path`, and put whatever variables
211	the router tells you to export into that provider's Environment variables section. Mark tokens
212	and API keys as sensitive.
213
214	```text
215	Display name: Claude Router
216	Binary path: claude
217	CLAUDE_CONFIG_DIR path: ~/.claude_router_home
218	```
219		62
220	Follow the upstream project's README for the router's own install, startup, and configuration	63	## OpenRouter
221	steps: <https://github.com/musistudio/claude-code-router>.
222		64
223	## I Want Different Claude Settings, Not A Different Account	65	Create a Claude instance with its own config directory, such as
		66	`~/.claude_openrouter`, and keep Binary path set to `claude`. In that instance's
		67	Environment variables, use:
224		68
225	Create another Claude provider with the same account if you want a named preset.	69	\| Variable \| Value \|
		70	\| ---------------------- \| ----------------------------------------- \|
		71	\| `ANTHROPIC_BASE_URL` \| `https://openrouter.ai/api` \|
		72	\| `ANTHROPIC_AUTH_TOKEN` \| Your OpenRouter API key, marked Sensitive \|
		73	\| `ANTHROPIC_API_KEY` \| An explicitly empty value \|
226		74
227	Examples:	75	If that Claude config directory has a cached Anthropic login, run `/logout` in a
		76	Claude Code session using that directory before starting the router setup. Cached
		77	login credentials can conflict with the router token.
228		78
229	- "Claude Default"	79	Verify requests in OpenRouter's activity dashboard. For model-role overrides and
230	- "Claude Router"	80	current compatibility requirements, use the
231	- "Claude Experimental"	81	[OpenRouter Claude Code guide](https://openrouter.ai/docs/cookbook/coding-agents/claude-code-integration).
232		82
233	If the preset needs different Claude files, give it a different `CLAUDE_CONFIG_DIR path`. If it needs	83	## Other routers
234	different API keys, base URLs, or router settings, use Environment variables.
235		84
236	Do not put environment variable assignments in `Launch arguments`.	85	A local router uses an ordinary Claude provider instance. Give it a separate
		86	config directory and put the router's endpoint and credential variables in that
		87	instance's Environment variables. The router must run where the environment
		88	can reach it. Follow the [Claude Code Router instructions](https://github.com/musistudio/claude-code-router)
		89	for its installation and routing configuration.

docs/user/providers-codex.md+49-157

...	@@ -1,179 +1,71 @@	...	@@ -1,179 +1,71 @@
1	# Codex	1	# Codex
2		2
3	This guide is for people who want to use more than one Codex account in T3 Code. For Claude, see	3	For one account, use the default Codex provider with your normal Codex login.
4	[Claude](./providers-claude.md). For first-time setup, see [Install T3 Code](./install.md).	4	[Provider setup](./install.md#providers) covers installation, Settings > Providers,
		5	and custom binaries or environment variables.
5		6
6	Common reasons:	7	## Use multiple accounts
7		8
8	- use a work account for work projects	9	A shared Codex home with a shadow home lets work and personal accounts continue
9	- use a personal account for personal projects	10	the same threads. The accounts share Codex sessions and configuration while keeping
10	- switch to another account when one account hits limits	11	their own login and available models.
11	- keep one shared Codex history instead of maintaining two separate Codex setups
12		12
13	## I Only Use One Codex Account	13	Keep your first account in `~/.codex`. On the environment's machine, sign the
14		14	second account into a fresh directory:
15	Use the default provider.
16
17	In Settings, your Codex provider can stay like this:
18
19	```text
20	Display name: Codex
21	CODEX_HOME path: ~/.codex
22	Shadow home path: empty
23	```
24
25	Log in with Codex normally:
26
27	```bash
28	codex login
29	```
30
31	## Send feedback to OpenAI
32
33	In an existing Codex thread, send `/feedback` or `/feedback` followed by a description of the
34	issue. T3 Code uploads the thread and Codex logs to OpenAI and shows a thread ID that you can copy
35	and share with OpenAI employees.
36
37	## Answer questions while Codex works
38
39	Codex can ask questions without stopping its work. Choose a suggested answer or enter your own
40	in the question panel. Questions without suggested answers accept text.
41
42	Your answers are sent as a new message. They reach the current turn while Codex is working, or
43	start a new turn if it has finished. Unanswered questions stay available after you reconnect.
44	This works in the web, desktop, and mobile apps. Codex must support async questions.
45
46	## Sub-agent models
47
48	The web and desktop Agents panel shows each sub-agent's model and reasoning effort when Codex
49	reports them. If Codex does not report either value, T3 Code leaves it out instead of using the
50	parent agent's settings.
51
52	## Browser and computer activity
53
54	Browser and Computer Use calls show their user-facing task title when Codex provides one. Expanded
55	activity groups show an icon for every call. Website calls use the active page's favicon when it is
56	available, and desktop app calls use the app's native icon on macOS when available. Other hosts use
57	a generic fallback glyph.
58
59	Collapsed activity groups are summarized by source, such as `Used Chrome integration`, instead of
60	showing the underlying tool name. Website favicons and native app icons keep their original colors;
61	integrations that provide separate light and dark logos use the logo for the current appearance.
62
63	## Approve access to other apps
64
65	When a Codex tool needs access to an app such as Safari, T3 Code shows the app name and asks for
66	approval. You can approve, decline, or cancel the request from the desktop app, web app, or mobile
67	app. Some tools also offer approval for the current session or permanent approval.
68
69	## I Want Work And Personal Codex Accounts
70
71	Use one real Codex home and one shadow home.
72
73	Recommended setup:
74
75	```text
76	~/.codex shared Codex home
77	~/.codex_p second account auth
78	```
79
80	The idea is:
81
82	- both accounts can see the same T3/Codex sessions
83	- each account keeps its own login
84	- existing threads can continue with either account
85
86	### Set Up The First Account
87
88	Log in normally:
89
90	```bash
91	codex login
92	```
93
94	This is the account used by `~/.codex`.
95
96	In T3 Code Settings, name it something obvious:
97
98	```text
99	Display name: Codex Work
100	CODEX_HOME path: ~/.codex
101	Shadow home path: empty
102	```
103
104	### Set Up The Second Account
105
106	Log in with a separate Codex home:
107		15
108	```bash	16	```bash
109	mkdir -p ~/.codex_p	17	mkdir -p ~/.codex_personal
110	CODEX_HOME=~/.codex_p codex login	18	CODEX_HOME=~/.codex_personal codex login
111	```
112
113	In T3 Code Settings, add another Codex provider:
114
115	```text
116	Display name: Codex Personal
117	CODEX_HOME path: ~/.codex
118	Shadow home path: ~/.codex_p
119	```	19	```
120		20
121	The important part is that both providers use the same `CODEX_HOME path`, but only the second one	21	Then add a second Codex instance in Settings > Providers:
122	has a `Shadow home path`.
123
124	## Which Account Am I Using?
125
126	Open Settings and look at the provider row.
127
128	T3 Code shows the authenticated email for providers that report one. Emails are blurred by default;
129	click the blurred email to reveal it.
130
131	Use display names and accent colors to make accounts easy to tell apart in the model picker.
132
133	## I Need A Different API Key Or Endpoint
134
135	Use the provider's Environment variables section in Settings.
136		22
137	This is useful when a Codex-compatible setup needs account-specific variables. Add the variables to	23	\| Instance \| CODEX_HOME path \| Shadow home path \|
138	the provider instance that should receive them, and mark API keys or tokens as sensitive. Sensitive	24	\| -------------- \| --------------- \| ------------------- \|
139	values are stored as server secrets and are not sent back to the app after saving.	25	\| Codex Work \| `~/.codex` \| Leave empty \|
		26	\| Codex Personal \| `~/.codex` \| `~/.codex_personal` \|
140		27
141	## Can I Switch Accounts In An Existing Thread?	28	Both instances must use the same CODEX_HOME path. T3 Code prepares the shared
		29	state in the shadow directory; do not populate it by copying your whole Codex
		30	home.
142		31
143	Yes, when both Codex providers share the same `CODEX_HOME path`.	32	The shadow account needs its own `auth.json` file. If Codex uses an OS credential
		33	store, configure file storage for this setup. See
		34	[OpenAI's credential storage guide](https://learn.chatgpt.com/docs/auth#credential-storage).
144		35
145	For example:	36	Use a completely separate CODEX_HOME path, with no shadow home, when you want
		37	separate Codex sessions and configuration. That instance cannot continue threads
		38	from the other home.
146		39
147	```text	40	## Switch accounts in an existing thread
148	Codex Work CODEX_HOME path: ~/.codex
149	Codex Personal CODEX_HOME path: ~/.codex, Shadow home path: ~/.codex_p
150	```
151		41
152	Those two providers are considered compatible for continuation, so the locked model picker can show	42	Choose the other account from the thread's model picker. T3 Code offers compatible
153	both.	43	Codex instances that share the thread's CODEX_HOME path. Changing accounts does
		44	not move the conversation into a separate Codex home.
154		45
155	If you add a third Codex provider with a completely different `CODEX_HOME path`, T3 Code treats it	46	If the account is missing from the picker, compare the home paths in provider
156	as a different workspace. It will not be offered for existing threads created under `~/.codex`.	47	settings. If two instances show the same unexpected account or models, check their
		48	reported accounts, refresh provider status, and confirm the second instance has
		49	its own shadow path and login. A shadow-home conflict usually means the directory
		50	contains a copied Codex setup. Use a fresh shadow directory and sign in again.
157		51
158	## If Both Accounts Look The Same	52	## Answer questions while Codex works
159		53
160	If two Codex providers show the same account or the same unexpected model list:	54	Codex can ask a question and keep working. Answer it in the thread's question
		55	panel. The answer becomes a new message: it reaches the active turn, or starts
		56	another turn if Codex has finished. Unanswered questions survive reconnects.
		57	This requires a Codex version that supports async questions.
161		58
162	1. Check the email in Settings.	59	## Approve app access
163	2. Refresh provider status.
164	3. Confirm the second provider has `Shadow home path` set.
165	4. Confirm the shadow directory has its own `auth.json`.
166	5. If you copied `~/.codex` into the shadow directory, remove everything except `auth.json`.
167		60
168	Example cleanup:	61	Codex tools can request access to another app. Respond to the named app's request
		62	in the thread on web, desktop, or mobile. Some tools offer access for one request,
		63	the current session, or permanently. See [Permission modes](./permission-modes.md)
		64	for command and file approvals.
169		65
170	```bash	66	## Send feedback to OpenAI
171	find ~/.codex_p -mindepth 1 ! -name auth.json -exec rm -rf {} +
172	```
173
174	## When To Use A Separate CODEX_HOME
175
176	Use a totally separate `CODEX_HOME path` only when you want a separate Codex workspace.
177		67
178	That means separate sessions and less account switching inside old threads. Most dual-account users	68	In an existing Codex thread, send `/feedback` with an optional description, for
179	should use the shared-home plus shadow-home setup instead.	69	example `/feedback The agent stopped before finishing the tests`. This uploads
		70	the conversation and Codex logs to OpenAI. The returned thread ID can be shared
		71	with OpenAI support.

docs/user/providers-opencode.md+35-79

...	@@ -1,93 +1,49 @@	...	@@ -1,93 +1,49 @@
1	# OpenCode	1	# OpenCode
2		2
3	T3 Code uses the OpenCode setup on the connected environment. With a remote environment, its	3	Install and authenticate OpenCode on the machine running your environment, then
4	OpenCode login and configuration apply, not the setup on your desktop or phone.	4	enable it in Settings > Providers. See [provider setup](./install.md#providers).
		5	T3 Code requires OpenCode 1.14.19 or newer, including when you connect an existing
		6	OpenCode server.
5		7
6	T3 Code requires OpenCode 1.14.19 or newer. It checks the server version before it loads models or	8	## Local or external server
7	starts work. If the check fails, update OpenCode or fix the server URL and password, then refresh
8	the provider status. Reconnecting the client also runs the check again.
9		9
10	## Server authentication	10	Leave Server URL empty to let T3 Code start OpenCode locally. A password in
		11	provider settings applies to both that server and T3 Code's connection. With no
		12	password setting, the local server uses `OPENCODE_SERVER_PASSWORD` from its
		13	environment.
11		14
12	Without a server URL, T3 Code starts a local OpenCode server. The process inherits	15	To use an existing OpenCode server, set Server URL and its password in provider
13	`OPENCODE_SERVER_PASSWORD` from the environment. A password in the provider settings overrides	16	settings. T3 Code uses only that configured password for an external server; it
14	that environment value for both the local process and T3 Code.	17	does not forward a local `OPENCODE_SERVER_PASSWORD`. If connection or version checks
		18	fail, check the URL, credentials, and OpenCode version, then refresh provider status.
15		19
16	With a server URL, T3 Code connects to that external server and uses only the password in the	20	After a lost connection, send another prompt to reconnect to the same OpenCode
17	provider settings. It does not send a local `OPENCODE_SERVER_PASSWORD` to an external server.	21	session.
18	OpenCode uses this password for HTTP Basic authentication.
19		22
20	## Approvals	23	## Approvals
21		24
22	In Supervised and Auto modes, OpenCode can read normal project files, search files, load	25	OpenCode follows the shared [permission modes](./permission-modes.md). Auto has
23	skills, and update its task list without approval. Files such as `.env` and `.env.local` still	26	the same rules as Supervised because OpenCode has no AI approval reviewer.
24	require approval. `.env.example` does not. OpenCode does not have an AI approval reviewer, so	27	Environment files such as `.env` and `.env.local` need approval in restricted
25	Auto uses the same permission rules as Supervised.	28	modes even though normal file reads do not; `.env.example` is allowed.
26		29
27	OpenCode asks before it runs commands, edits files, accesses the web, or accesses directories	30	Allow for workspace applies to matching requests in other OpenCode sessions
28	outside the workspace. Auto-accept edits also permits file edits without approval.	31	using the same workspace. It is broader than the current thread, especially on a
29	Full access permits all these actions. Questions that need your answer can still appear.	32	shared external server. Use Allow once for a single request. Denying an action
		33	does not stop the whole turn.
30		34
31	An Approval badge means OpenCode needs a decision. Open the thread to see the action and	35	## Refresh models, commands, and skills
32	choose one of these options:
33		36
34	- Allow once permits this request.	37	After changing an OpenCode login or configuration, use Refresh provider status
35	- Allow for workspace permits matching requests in other OpenCode sessions in the same	38	in Settings > Providers for that environment. On mobile, use Refresh models
36	workspace. It is not limited to the current thread.	39	in the thread settings. Reconnecting also refreshes the catalog; periodic provider
37	- Deny rejects this request. Use Stop to stop the whole turn.	40	health checks do not.
38		41
39	If a connection error prevents the reply, the approval stays available so you can try again.	42	Credential changes are read on refresh. Native OpenCode configuration can remain
		43	cached while the local helper is running. Let it sit for 30 seconds without model
		44	refreshes or text-generation work, then refresh again to reload the files. Repeated
		45	refreshes keep the helper alive. An external server may need its own reload or
		46	restart before T3 Code can see configuration changes.
40		47
41	## Progress	48	Existing threads keep their selected model and options even when it disappears
42		49	from the catalog. If OpenCode rejects that model, select an available one and retry.
43	T3 Code shows OpenCode's response text and tool results while work runs. The web and desktop apps
44	also show its task-list progress. A task-list update does not require approval.
45
46	If the OpenCode connection closes unexpectedly, T3 Code shows an error. Send another prompt to
47	reconnect to the same OpenCode session.
48
49	## Stop a turn
50
51	When you select Stop, T3 Code stops the main OpenCode session and all nested child sessions.
52	T3 Code waits for this cleanup before it marks the turn as stopped or sends the next prompt. It
53	does not stop unrelated OpenCode sessions. After Stop succeeds, pending approvals and questions
54	are cleared.
55
56	Stop reports an error if OpenCode cannot stop the main session or list or stop a child session.
57	When T3 Code closes an OpenCode session, it also tries to stop the child sessions, but this
58	teardown is best effort.
59
60	## Refresh the model list
61
62	T3 Code loads the model list when an enabled OpenCode provider starts and keeps the list in its
63	cache. Reconnecting a client or using a refresh control asks OpenCode for the list again. The
64	periodic provider health setting does not refresh OpenCode's catalog.
65
66	After changing an OpenCode login or configuration outside T3 Code, open Settings > Providers,
67	select the environment, and choose Refresh provider status. Changing the provider's
68	configuration in T3 Code also replaces that provider connection.
69
70	On mobile, open the thread settings and select Refresh models. The control stays disabled while
71	the refresh runs and shows an error if the refresh fails.
72
73	OpenCode reads credential changes on each model-list request. Native OpenCode configuration files
74	can stay cached while the local helper is running. The helper closes after 30 seconds with no
75	model-list or text-generation work. Refresh after that idle period to start a new helper and read
76	the file changes. Repeated refreshes or active helper work can extend this wait.
77
78	T3 Code does not own an external OpenCode server. Native configuration changes on that server can
79	require its own reload or restart before a refresh returns the new list.
80
81	If a refresh fails, T3 Code keeps the last known models, slash commands, and skills. Fix the
82	connection, then refresh again. A successful refresh can remove entries that OpenCode no longer
83	offers.
84
85	## Continue an existing thread
86
87	An existing thread keeps its selected model and options when that model is temporarily absent
88	from the catalog. The web picker shows an Unavailable row and keeps saved option values visible
89	until the model metadata returns. T3 Code does not switch the thread to the first model in the
90	list.
91
92	The stored selection does not guarantee that OpenCode can still run the model. If the provider
93	rejects it, select an available model before trying again.

docs/user/remote-access.md+109-236

...	@@ -1,290 +1,163 @@	...	@@ -1,290 +1,163 @@
1	# Remote Access	1	# Remote access
2		2
3	Use this when you want to connect to a T3 Code server from another device such as a phone, tablet, or separate desktop app.	3	Connect a phone, browser, or another desktop app to T3 Code running on a different
		4	machine. That machine must stay running and reachable while you work.
4		5
5	## T3 Connect troubleshooting	6	## T3 Connect
6
7	Run `t3 connect` on the server machine to authorize it and optionally install the background service.
8	The authorization message means your sign-in was saved. The server must then start and establish its
9	relay link before the machine is reachable.
10
11	`t3 connect status` reports saved authorization and link configuration, not a live reachability
12	check. If the machine appears offline, run `t3 service status` on it and read the displayed log.
13	On Linux, a service that works while SSH is open but stops after logout usually has lingering
14	disabled. See [background service troubleshooting](./background-service.md#troubleshooting).
15
16	Relay errors include the returned reason and trace ID when available:
17
18	\| Error \| Next step \|
19	\| ---------------------------------------------------------------- \| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- \|
20	\| `environment_link_limit_exceeded` / managed tunnel limit reached \| Unlink an unused environment in T3 Connect, then restart T3 Code on this machine. \|
21	\| `auth_invalid` / `invalid_bearer` \| Run `t3 connect login`. If the stored credential was revoked, run `t3 connect logout`, then `t3 connect` and restart the server. \|
22	\| Expired or invalid link proof \| Check the server's date and time, update T3 Code, and restart it. Include the reason and trace ID if it still fails. \|
23	\| HTTP 403 without a recognized error response \| Check relay access and any proxy or firewall restrictions. Include the Cloudflare Ray ID if one was returned; an HTTP status alone does not identify the cause. \|
24	\| HTTP 408, 429, or 5xx \| The server retries temporary failures during startup for up to ten minutes. Check network and relay availability; include the trace ID when reporting a persistent failure. \|
25		7
26	Authorization and other permanent 4xx rejections stop the startup link attempt immediately.	8	T3 Connect makes an environment available to your other devices without setting
27	After correcting them, restart the server. For the Linux background service, use	9	up router forwarding. In the desktop app on the host, open **Settings →
28	`systemctl --user restart t3code.service`; for a foreground server, stop it and run `t3 serve` again.	10	Connections, sign in, and enable T3 Connect** for that environment.
29	Keep the diagnostic message and trace ID when reporting a problem. Do not post authorization codes,
30	pairing URLs, or the contents of the secrets directory.
31		11
32	## Quick Pairing for a Running Server	12	For a command-line host, run:
33
34	If a server is already running on this machine, mint a fresh pairing token and QR code without restarting anything:
35		13
36	```bash	14	```bash
37	npx t3 pair	15	npx t3@latest connect
38	```	16	```
39		17
40	`t3 pair` finds the running server (the shared `~/.t3` install, or the current worktree's dev server when run inside one), issues a one-time pairing token, and prints the pairing URL as a QR code you can scan from your phone.	18	Follow the sign-in instructions. Setup offers a
41		19	[background service](./background-service.md); if you decline it, start the
42	If the server is only bound to loopback, the printed URL is not reachable from another device. Pair over your tailnet instead:	20	server with `npx t3 serve`. Saving your sign-in alone does not make the machine
43		21	reachable.
44	```bash
45	npx t3 pair --tailscale
46	```
47
48	This publishes the server over Tailscale Serve HTTPS (configuring the mapping if needed — it persists until you run `tailscale serve --https=443 off`) and pairs through the `https://machine.tailnet.ts.net/` URL. Use `--tailscale-serve-port` for a different HTTPS port, `--ttl` to change the token lifetime, and `--base-dir` to target a specific data directory.
49
50	If no server is running, `t3 pair` says so and points you at `npx t3 serve` or `npx t3 connect`.
51
52	## Recommended Setup
53
54	Use a trusted private network that meshes your devices together, such as a tailnet.
55
56	That gives you:
57
58	- a stable address to connect to
59	- transport security at the network layer
60	- less exposure than opening the server to the public internet
61
62	## Enabling Network Access
63		22
64	There are three ways to reach your server from another device: expose the desktop app's backend,	23	On your other device, sign in to the same T3 Connect account and choose the
65	run a headless server from the CLI, or have the desktop app launch T3 Code over SSH.	24	environment. Over SSH, the CLI prints a browser link and accepts the returned
		25	authorization code, so you do not need to forward an OAuth callback port.
66		26
67	### Option 1: Desktop App	27	## Pair over a LAN or private network
68		28
69	If you are already running the desktop app and want to make it reachable from other devices:	29	Use direct pairing when the other device can reach the host's network address.
70		30
71	1. Open Settings → Connections.	31	On a desktop host, open Settings → Connections, enable Network access,
72	2. Under This environment, toggle Network access on. This will restart the app and run the backend on all network interfaces.	32	then create a pairing link using an address the other device can reach. Changing
73	3. The settings panel will show the default reachable endpoint, with a `+N` control when more endpoints are available. Expand it to inspect alternatives such as loopback, LAN, private-network, or HTTPS endpoints.	33	network access restarts the desktop app. You can turn it off in the same place.
74	4. Use Create Link to generate a pairing link you can share with another device.
75		34
76	Pairing codes and share links are available only in the client that created them,	35	For a command-line host, replace `<private-ip>` with the host's LAN or tailnet
77	while its Connections page remains open. After you leave the page or reload it,	36	address:
78	create a new link to share. Other clients can see the active link's name, scopes,
79	and expiry, and can revoke it if they have access management permission.
80
81	The default endpoint controls the QR code and primary copy action for pairing links. You can change it from the expanded endpoint list. The preference is stored by endpoint type, so choosing the local LAN endpoint survives normal IP address changes when you move between networks.
82
83	After an app restart, the desktop app replaces its previous
84	local credential. Old local desktop entries are removed from Authorized clients
85	automatically. Paired phones, browsers, and remote desktop clients keep their access.
86
87	When no user default is saved, the app uses the built-in LAN endpoint for pairing links when
88	available. You can set another endpoint as the default from the expanded endpoint list.
89
90	- HTTPS/WSS-compatible endpoints work from `https://app.t3.codes`, but are not made the default
91	automatically.
92	- Non-loopback HTTP endpoints are useful for direct LAN pairing.
93	- Loopback-only endpoints are not useful for another device unless that device is the same machine.
94
95	If the copied link points directly at `http://192.168.x.y:3773`, open it from a client that can reach that LAN address. If it points at `https://app.t3.codes/pair?...`, the hosted web app will save the environment and connect directly to the backend URL in the link.
96
97	In the mobile app's Add Environment form, a numeric IP address without a scheme uses HTTP. Include `https://` explicitly when the backend is served over HTTPS.
98
99	### Tailscale Endpoints
100
101	When the desktop app can detect Tailscale, it adds Tailnet endpoints to the reachable endpoint list.
102
103	Depending on your Tailscale setup, this may include:
104
105	- the machine's `100.x.y.z` Tailnet IP
106	- a MagicDNS name
107	- an HTTPS MagicDNS endpoint when Tailscale Serve is configured for this backend
108
109	The Tailscale HTTPS endpoint uses the clean MagicDNS URL, such as
110	`https://machine.tailnet.ts.net/`, and is off until you opt in. Turn on Enable Tailscale HTTPS
111	on the Tailscale HTTPS row in Settings → Connections. The desktop app restarts the
112	backend with the same server-side behavior as `t3 serve --tailscale-serve`, then the server asks
113	Tailscale Serve to proxy HTTPS traffic to the local backend. Turn the same switch off to stop it.
114
115	The Tailscale support is an endpoint provider add-on. The core remote model still works without Tailscale: LAN HTTP endpoints, custom HTTPS endpoints, future tunnels, and SSH-launched environments all use the same saved environment and pairing flow.
116
117	For `https://app.t3.codes`, prefer an HTTPS Tailnet or other HTTPS endpoint. A plain `http://100.x.y.z:3773` endpoint can still work from a desktop client or another browser page served over HTTP, but it will not work from the hosted HTTPS app because of browser mixed-content rules.
118
119	### Option 2: Headless Server (CLI)
120
121	Use this when you want to run the server without a GUI, for example on a remote machine over SSH.
122
123	Run the server with `t3 serve`.
124		37
125	```bash	38	```bash
126	npx t3 serve --host "$(tailscale ip -4)"	39	npx t3 serve --host <private-ip>
127	```	40	```
128		41
129	`t3 serve` starts the server without opening a browser and prints:	42	If a server is already running, generate a fresh link without restarting it:
130
131	- a connection string
132	- a pairing token
133	- a pairing URL
134	- a QR code for the pairing URL
135
136	From there, connect from another device in either of these ways:
137
138	- scan the QR code on your phone
139	- in the desktop app, enter the full pairing URL
140	- in the desktop app, enter the host and token separately
141	- in the hosted web app, open a hosted pairing URL when the backend is reachable over HTTPS
142
143	Use `t3 serve --help` for the full flag reference. It supports the same general startup options as the normal server command, including an optional `cwd` argument.
144
145	For hosted web pairing over Tailscale HTTPS, opt in to Tailscale Serve:
146		43
147	```bash	44	```bash
148	npx t3 serve --tailscale-serve	45	npx t3 pair
149	```
150
151	By default this configures Tailscale Serve on HTTPS port 443 and advertises
152	`https://machine.tailnet.ts.net/`. Advanced users can choose a different HTTPS port:
153
154	```bash
155	npx t3 serve --tailscale-serve --tailscale-serve-port 8443
156	```	46	```
157		47
158	Once paired, add projects normally: open the Command Palette and choose Add Project, then pick	48	Scan the QR code on your phone or paste the pairing URL into Add environment
159	the environment the project lives on. Every saved environment is offered, not only the local one.	49	in the receiving app. Connection settings are under Settings → Connections
		50	on web and desktop and Settings → Environments on mobile. A loopback address
		51	such as `127.0.0.1` reaches only the device opening the link.
160		52
161	### Option 3: Desktop-Managed SSH Launch	53	Pairing authorizes that device for future connections. Use a fresh one-time link
		54	for each new device; you do not need the original token to reconnect. Links
		55	created in Settings can only be copied from the client that created them while
		56	its Connections page stays open. If you leave or reload that page, create
		57	another link to share.
162		58
163	Use this when you want the desktop app to start or reuse T3 Code on another machine over SSH.	59	### Tailscale HTTPS
164		60
165	1. Open Settings → Connections.	61	Join both devices to the same tailnet. In the desktop app, enable **Tailscale
166	2. Under Remote Environments, choose Add environment.	62	HTTPS in Settings → Connections**. Turn it off there to remove that route.
167	3. Select the SSH launch flow.
168	4. Enter the SSH target, such as `user@example.com`.
169	5. Confirm the launch. The desktop app probes the host, starts or reuses a remote T3 server, opens a local port forward, and saves the environment.
170		63
171	After setup, the renderer connects to a local forwarded HTTP/WebSocket endpoint. The remote host still owns the actual T3 server, projects, files, git state, terminals, and provider sessions.	64	To start a command-line server with Tailscale HTTPS:
172		65
173	SSH launch is a desktop feature because it needs local process and SSH access. Once the environment is paired and saved, it uses the same environment list and connection model as direct LAN, Tailscale, HTTPS, or future tunnel-backed environments.	66	```bash
174		67	npx t3 serve --tailscale-serve
175	#### SSH Launch Troubleshooting
176
177	The desktop SSH launcher connects with a non-interactive `sh` session, writes a small launcher script under `~/.t3/ssh-launch/<host-key>/`, starts or reuses a remote T3 server, and forwards the remote loopback port back to your desktop.
178
179	The remote host must have a compatible Node.js runtime. T3 Code uses the server package's `engines.node` requirement:
180
181	```text
182	^22.16 \|\| ^23.11 \|\| >=24.10
183	```	68	```
184		69
185	During SSH launch, T3 Code first checks whether `node` is on `PATH`. If it is missing, the launcher	70	For an already-running server:
186	looks in the usual install directories and tries to activate a version manager if it finds one
187	(Volta, asdf, mise, fnm, nodenv, nvm). That covers most setups, but a version manager that only
188	initializes from an interactive shell profile will not be picked up.
189
190	If launch fails with `node: command not found`, a port-scan failure, or a message that the remote Node version does not satisfy the required range, SSH into the host and check the same non-interactive shell path T3 Code uses:
191		71
192	```bash	72	```bash
193	ssh user@example.com 'sh -lc "command -v node && node --version"'	73	npx t3 pair --tailscale
194	```	74	```
195		75
196	If that does not print a compatible Node version, configure your version manager for non-interactive shells or install a compatible Node binary in one of the searched locations. For example, with nvm you may need a default alias:	76	The pairing link uses an address such as `https://machine.tailnet.ts.net/`.
		77	The mapping created by `pair --tailscale` persists across restarts. Remove its
		78	default-port mapping with:
197		79
198	```bash	80	```bash
199	nvm alias default 24	81	tailscale serve --https=443 off
200	```	82	```
201		83
202	With mise, asdf, fnm, or nodenv, make sure the tool's shim directory is installed and resolves to a Node version satisfying the range above without an interactive shell.	84	If that port is already in use, choose another with
		85	`--tailscale-serve-port`. See `npx t3 pair --help` for other pairing options.
203		86
204	If reconnecting after an app update fails, retry the SSH launch once. The launcher now compares its generated runner script, stops stale launcher-managed remote servers, clears the SSH launch PID/port state, and starts a fresh remote server. You should not normally need to delete `~/.t3/ssh-launch` or kill `t3` processes manually.	87	### Hosted web app
205		88
206	## Antigravity Google sign-in	89	[app.t3.codes](https://app.t3.codes) needs an HTTPS endpoint. It connects directly
		90	to your server; a hosted pairing link does not make an unreachable backend
		91	reachable or convert HTTP to HTTPS.
207		92
208	Antigravity runs and saves its Google credentials on the selected environment. You can install	93	For a plain HTTP LAN endpoint, use the direct pairing URL in a browser that can
209	it and sign in from a remote web or desktop client without an SSH login.	94	open it, or pair from the desktop app. On mobile, an IP address entered without a
		95	scheme uses HTTP, so include `https://` when your server uses HTTPS.
210		96
211	Start in Settings > Providers, select the environment, then choose Antigravity.	97	## Desktop-managed SSH
212	Provider setup is not available in the mobile app.
213		98
214	After Google sign-in, a remote browser usually reaches a `127.0.0.1` page that cannot load.	99	In the desktop app, open Settings → Connections → Add environment, choose
215	Copy that full address into the return URL field in the same T3 Code client and choose	100	SSH, and enter a host or SSH alias such as `user@example.com`. T3 Code starts
216	Continue. Keep the address unchanged. Do not paste the return URL into a thread or bug report.	101	or reuses a server there and opens the port forward for you. Projects, provider
		102	credentials, and agent work stay on the remote machine.
217		103
218	See [Antigravity setup](./providers-antigravity.md) for installation, expiry, and account changes.	104	The remote host needs a compatible [Node.js installation](./install.md#requirements)
		105	and [provider setup](./install.md#providers). If launch cannot find Node or reports
		106	an incompatible version, check it through a non-interactive SSH session:
219		107
220	## Updating a Remote Server	108	```bash
221		109	ssh user@example.com 'sh -lc "command -v node && node --version"'
222	When the T3 Code web or desktop app and a remote server use different versions, a warning appears in
223	the conversation and in Settings → Connections. Follow the action shown there: T3 Code may
224	be able to update and reconnect the server for you, or it may ask you to update the desktop app or
225	run a copied command on the server machine.
226
227	If T3 Connect cannot connect, check the date and time on both devices, then try again.
228
229	Finish active work before updating because the server restarts briefly. For step-by-step guidance,
230	see [Keeping T3 Code in Sync](./updating.md).
231
232	On a Linux host, you can keep the server running after logout and manage it independently of the
233	connection method. See [Running T3 Code in the Background](./background-service.md).
234
235	## How Pairing Works
236
237	The remote device does not need a long-lived secret up front.
238
239	Instead:
240
241	1. `t3 serve` issues a one-time owner pairing token.
242	2. The remote device exchanges that token with the server.
243	3. The server creates an authenticated session for that device.
244
245	After pairing, future access is session-based. You do not need to keep reusing the original token unless you are pairing a new device.
246
247	## Hosted Web App Pairing
248
249	The hosted web app at `https://app.t3.codes` can save a remote backend in browser local storage from a URL like:
250
251	```text
252	https://app.t3.codes/pair?host=https://backend.example.com:3773#token=PAIRCODE
253	```	110	```
254		111
255	Use hosted pairing when the backend is reachable from the browser over HTTPS/WSS. This includes a backend behind a trusted HTTPS tunnel or another HTTPS endpoint you operate.	112	Configure your version manager for non-interactive shells if this differs from
		113	your normal terminal. With nvm, setting a compatible default, such as
		114	`nvm alias default 24`, can resolve the problem.
256		115
257	Do not use hosted pairing for plain HTTP LAN URLs such as `http://192.168.x.y:3773`. Browsers block an HTTPS page from connecting to an insecure HTTP or WS backend. For those endpoints, use the direct pairing URL shown by the desktop app or CLI from a client that can open that HTTP URL directly.	116	If SSH reconnecting fails after an app update, retry the launch once. Removing
		117	the connection stops a server that T3 Code launched; a server that was already
		118	running is left alone.
258		119
259	Hosted pairing does not proxy traffic through T3 Code. The browser still connects directly to the backend URL in the pairing link.	120	For Antigravity's Google callback on a remote host, see
		121	[remote sign-in](./providers-antigravity.md#sign-in-from-a-remote-device).
260		122
261	## Managing Access Later	123	## Manage or revoke access
262		124
263	Use `t3 auth` to manage access after the initial pairing flow.	125	On the host, Settings → Connections lets authorized administrators create
		126	pairing links and revoke client sessions. Revoking an unused link prevents new
		127	pairings; revoke a device's session to remove its existing access. Command-line
		128	management is available through `npx t3 auth --help`.
264		129
265	Typical uses:	130	To remove an environment from T3 Connect, open your account menu's T3 Connect
		131	page, or Settings → T3 Connect on mobile, and choose Deregister. This
		132	revokes its cloud access and frees its host space even when the environment is
		133	offline or has been wiped.
266		134
267	- issue additional pairing credentials	135	On a command-line host, `t3 connect unlink` disables exposure while retaining
268	- inspect active sessions	136	your login; `t3 connect logout` also clears that login. Background-service
269	- revoke old pairing links or sessions	137	[removal](./background-service.md#manage-the-service) is separate.
270		138
271	Use `t3 auth --help` and the nested subcommand help pages for the full reference.	139	Treat pairing URLs and authorization codes as passwords. Do not include them in
		140	screenshots, logs, or bug reports.
272		141
273	### Deregister a T3 Connect Environment	142	## T3 Connect troubleshooting
274
275	Open your account menu and choose T3 Connect to see every environment registered to your
276	account. On mobile, open Settings → T3 Connect. Choose Deregister to revoke an
277	environment's T3 Connect access, remove any managed tunnel, and free its host space.
278
279	Deregistration is an account action and does not need a connection to the environment, so it also
280	works for a server that was wiped or is no longer reachable. Device-local connect and disconnect
281	controls remain in Settings → Connections on web and desktop or Settings →
282	Environments on mobile.
283
284	## Security Notes
285		143
286	- Treat pairing URLs and pairing tokens like passwords.	144	Run `t3 connect status` on the host to inspect saved authorization and link
287	- Prefer binding `--host` to a trusted private address, such as a Tailnet IP, instead of exposing the server broadly.	145	configuration. It is not a live reachability check. If the environment appears
288	- Anyone with a valid pairing credential can create a session until that credential expires or is revoked.	146	offline, run `t3 service status` and read the displayed log. If it disappears
289	- Hosted pairing links keep the credential in the URL hash so it is not sent to the hosted app server, but it can still be exposed through browser history, screenshots, logs, or copy/paste.	147	when SSH closes, see [background-service troubleshooting](./background-service.md#troubleshooting).
290	- Use `t3 auth` to revoke credentials or sessions you no longer trust.	148
		149	\| Error \| Recovery \|
		150	\| --------------------------------------------------------- \| ------------------------------------------------------------------------------------------------------------------------------------------- \|
		151	\| `environment_link_limit_exceeded` or managed tunnel limit \| Deregister an unused environment, then restart T3 Code on the host. \|
		152	\| `auth_invalid` or `invalid_bearer` \| Run `t3 connect login`. If credentials were revoked, run `t3 connect logout`, then `t3 connect` again. Restart the server after signing in. \|
		153	\| Expired or invalid link proof \| Check the host's date and time, update T3 Code, then restart it. \|
		154	\| HTTP 403 without a recognized error \| Check relay access, proxies, and firewall rules. Keep any Cloudflare Ray ID for a bug report. \|
		155	\| HTTP 408, 429, or 5xx \| Check network and relay availability. Startup retries temporary failures for up to ten minutes. \|
		156
		157	After fixing a permanent rejection, restart the host's server. On Linux, use
		158	`systemctl --user restart t3code.service` for the background service. For a
		159	foreground server, stop it and run `t3 serve` again with your usual options.
		160	Include the diagnostic message and trace ID when reporting a persistent failure.
		161
		162	For a connection that still fails after linking, check the date and time on both
		163	devices. For server version warnings, follow [Updating T3 Code](./updating.md).

docs/user/source-control.md+72-160

...	@@ -1,181 +1,93 @@	...	@@ -1,181 +1,93 @@
1	# Source Control Integrations	1	# Source control
2		2
3	T3 Code connects to your Git hosting provider so you can create pull requests, review code, and manage repositories without leaving the app.	3	T3 Code integrates with GitHub, GitLab, Bitbucket, and Azure DevOps to clone and publish
4		4	repositories, create pull requests, and review changes.
5	## Supported Providers	5
6		6	## Connect an account
7	T3 Code works with the platforms your team already uses:	7
8		8	Install Git and configure authentication on the machine running your T3 Code server. For a remote
9	- GitHub – Pull requests, repository creation, and clone integration	9	environment, do this on the remote machine. After signing in, open Settings → Source Control
10	- GitLab – Merge requests, repository publishing, and hosted clones	10	and choose Rescan.
11	- Bitbucket – Pull request workflows (via API token authentication)	11
12	- Azure DevOps – Pull request support for Microsoft-hosted repositories	12	### GitHub
13		13
14	## What You Can Do	14	Install [GitHub CLI](https://cli.github.com/) 2.81.0 or newer, then sign in:
15		15
16	### Start Projects from Anywhere	16	```bash
17		17	gh auth login
18	Clone repositories directly	18	```
19		19
20	- Open the Command Palette (`Cmd/Ctrl + K`) → Add Project	20	### GitLab
21	- Choose GitHub repository, GitLab repository, Bitbucket repository, Azure DevOps repository, or paste any Git URL	21
22	- Enter the repository path (`owner/repo`, `group/project`, `workspace/repository`, or `project/repository`) or a full Git URL, pick a destination, and start coding	22	Install [GitLab CLI](https://gitlab.com/gitlab-org/cli), then sign in:
23		23
24	Publish local projects to the cloud	24	```bash
25		25	glab auth login
26	- Have a local Git repository without a remote?	26	```
27	- Use the Publish Repository action to create a new hosted repository (GitHub, GitLab, Bitbucket, or Azure DevOps), add it as your origin remote, and push, in one flow	27
28	- If the local repository has no commits yet, publishing creates the remote and wires it up but does not push. Make a commit, then push normally.	28	### Bitbucket
29		29
30	### Manage Code Reviews Without Context Switching	30	Set an access token in the server's environment:
31
32	Create pull requests while you work
33
34	- Push a branch and create a pull request from the Git actions controls in the toolbar
35	- T3 Code can suggest titles and descriptions based on your commits
36	- With Repository conventions selected, generated source control text follows the project's
37	`AGENTS.md` along with recent commit subjects. Claude writers also follow `CLAUDE.md`
38	- Supports GitHub Pull Requests, GitLab Merge Requests, Bitbucket Pull Requests, and Azure DevOps Pull Requests
39
40	Stay on top of open reviews
41
42	- See if your current branch already has an open PR/MR
43	- When an agent finishes a turn on your thread's branch, T3 Code checks for a newly opened
44	PR/MR if background activity is enabled for that repository. Known reviews keep their normal
45	refresh schedule.
46	- Open several reviews from the Pull requests page as tabs in the right panel
47	- Your authored reviews stay at the top and use the selected sort within their group. By default,
48	see passing and approved reviews first, passing reviews awaiting approval next, and conflicting
49	reviews last. Smaller changes come first within each readiness group, and finished reviews follow
50	open work when all states are visible.
51	- Filter the list by author or labels, rank authors by merges in the loaded results, see label and
52	change-size context on each row, and sort the results currently shown by readiness, update time,
53	creation time, or change size. Your filters, search, scope, and sort are restored when you return.
54	- Merge now, or on GitHub, GitLab, and Azure DevOps, leave an auto-merge instruction with a chosen
55	strategy while checks are outstanding; see the completed state in the same control after the
56	pull request merges
57	- On GitHub, approve fork workflows that are waiting to run and open a revert pull request for a
58	merged change
59	- Timeline line counts stay hidden on merge commits, where GitHub's totals include upstream changes
60	brought in from the base branch
61	- While working in a thread, open linked reviews in the same compact right-panel tabs without
62	leaving the conversation
63	- Show a file tree next to a review's Code tab, or a thread's Diff panel, to browse the
64	changed files as folders and jump straight to any of them. The toolbar toggle remembers your
65	choice.
66	- Enable Settings → General → Proactive panels to open a newly linked review automatically and
67	switch to the completed turn's diff when agent work changes files. An open review stays in front
68	- Open the review directly in your browser with one click
69	- If T3 Code cannot load a GitHub pull request, including when GitHub rate limits requests, use
70	Open on GitHub in the error view
71	- Command-click (Control-click on Windows and Linux) a pull request number in the sidebar to open it in your browser instead of in T3 Code
72	- Check out a teammate's branch to review code locally
73
74	Fix what you wrote, in place
75
76	- Comment while closing an open pull request or reopening a closed one when the host offers that
77	action
78	- Rewrite a pull request's title and description from the review itself, in Markdown, with a
79	preview before you save
80	- Rewrite your own comments the same way, wherever they are shown
81	- Works on GitHub, GitLab, and Bitbucket. Azure DevOps takes a new title and description; its
82	comments stay read-only here, as they already were
83	- On GitHub, put a label on a pull request or take one off from the Labels row of the review.
84	Changing labels needs triage access or better on the repository
85
86	### Know Your Setup at a Glance
87
88	The Source Control settings page shows you exactly what's connected:
89
90	- ✅ Which providers are authenticated and ready
91	- ⚠️ What's missing and how to fix it
92	- 👤 Which account is signed in (when available)
93
94	Run a quick Rescan after setting up a new machine or changing credentials.
95
96	## Getting Started
97
98	### For GitHub (Recommended for most users)
99
100	1. Install the GitHub CLI (version 2.81.0 or newer) on the machine running T3 Code:
101	```bash
102	brew install gh
103	```
104	2. Sign in:
105	```bash
106	gh auth login
107	```
108	3. Open Settings → Source Control in T3 Code and verify GitHub shows as authenticated
109
110	You can now clone, publish, and create pull requests.
111
112	### For GitLab
113
114	1. Install the GitLab CLI:
115	```bash
116	brew install glab
117	```
118	2. Authenticate:
119	```bash
120	glab auth login
121	```
122	3. Check Settings → Source Control to confirm the connection
123
124	### For Bitbucket
125
126	Bitbucket uses tokens instead of a CLI tool. Two options, both set as environment variables on the
127	machine running T3 Code.
128
129	Recommended, a Bitbucket access token:
130		31
131	```bash	32	```bash
132	export T3CODE_BITBUCKET_ACCESS_TOKEN="your-access-token"	33	export T3CODE_BITBUCKET_ACCESS_TOKEN="your-access-token"
133	```	34	```
134		35
135	Or an Atlassian account email plus API token, with read/write access to pull requests and	36	Or use an Atlassian account email and API token with read/write access to repositories and pull
136	repositories, plus read access to your user account (`read:user:bitbucket`, used to verify the	37	requests, plus user read access (`read:user:bitbucket`):
137	connection):
138		38
139	```bash	39	```bash
140	export T3CODE_BITBUCKET_EMAIL="you@example.com"	40	export T3CODE_BITBUCKET_EMAIL="you@example.com"
141	export T3CODE_BITBUCKET_API_TOKEN="your-token"	41	export T3CODE_BITBUCKET_API_TOKEN="your-token"
142	```	42	```
143		43
144	If both are set, the access token wins. Restart T3 Code and verify the connection in **Source	44	The access token takes precedence if both are configured. Restart the server after changing these
145	Control settings**.	45	variables.
		46
		47	### Azure DevOps
		48
		49	Install [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/), add the DevOps extension, and sign in:
		50
		51	```bash
		52	az extension add --name azure-devops
		53	az login
		54	```
		55
		56	## Clone or publish a project
		57
		58	Use Add Project in the command palette (`Cmd/Ctrl+K`) to clone a repository. Choose a hosting
		59	provider or paste a Git URL, then choose where to save it.
146		60
147	### For Azure DevOps	61	For a local Git repository without a remote, Publish Repository creates a hosted repository,
		62	adds it as `origin`, and pushes your commits. If there are no commits yet, it creates the remote;
		63	make your first commit before pushing.
148		64
149	1. Install Azure CLI:	65	## Create a pull request
150	```bash
151	brew install azure-cli
152	```
153	2. Add the DevOps extension:
154	```bash
155	az extension add --name azure-devops
156	```
157	3. Sign in:
158	```bash
159	az login
160	```
161		66
162	---	67	Use a thread's Git actions to commit, push, and create a pull request. T3 Code can generate commit
		68	messages, review titles, and descriptions from your changes.
163		69
164	## Requirements & Troubleshooting	70	Choose the writing style and model in Settings → Source Control. Repository conventions
		71	uses the project's instructions and recent commit subjects.
165		72
166	Git is required – T3 Code uses Git for all local operations. Ensure `git` is installed on your server.	73	## Review and merge
167		74
168	Server-side setup – Authentication happens on the machine running T3 Code (the server), not your local browser. If you're using a hosted or team instance, your administrator may have already configured providers.	75	Open Pull requests to review changes and comments, request reviewers, check out a branch,
		76	or merge. You can edit review titles and descriptions and your own comments where the host allows it.
		77	GitLab calls these merge requests.
169		78
170	Common issues:	79	GitHub, GitLab, and Azure DevOps support auto-merge while checks are outstanding. GitHub also
		80	supports approving waiting fork workflows and opening a revert pull request for a merged change.
171		81
172	- Provider shows "Not authenticated" – Run the login command for that provider (e.g., `gh auth login`) in a terminal on the server, then rescan in Settings	82	For Azure DevOps, use the host website to view diffs or change comments. Bitbucket does not support
173	- GitHub says it could not verify sign-in status – T3 Code needs GitHub CLI 2.81.0 or newer to check sign-in status. Update `gh` (e.g., `brew upgrade gh`), then rescan	83	reopening a declined pull request.
174	- Bitbucket not connecting – Double-check your environment variables are set in the correct shell profile and the server was restarted
175	- Can't push to a remote – Verify your Git remote URL matches the provider you've authenticated with (SSH vs HTTPS remotes may need different credentials)
176		84
177	Need more help? Check your provider's CLI documentation:	85	## Troubleshooting
178		86
179	- [GitHub CLI](https://cli.github.com/)	87	- Not authenticated: run the provider's login command on the server, then rescan. For Bitbucket,
180	- [GitLab CLI](https://gitlab.com/gitlab-org/cli)	88	confirm the running server received the environment variables.
181	- [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/)	89	- GitHub sign-in cannot be verified: update GitHub CLI to at least 2.81.0.
		90	- Push fails despite a connected account: check the Git remote's credentials. SSH and HTTPS
		91	remotes can require separate setup from the hosting provider's API access.
		92	- A review cannot load: open it on the host website while resolving connectivity, permissions,
		93	or rate limits.

docs/user/telemetry.md+8-12

...	@@ -1,15 +1,11 @@	...	@@ -1,15 +1,11 @@
1	# Anonymous usage data	1	# Product usage data
2		2
3	The T3 server sends anonymous product events to PostHog. These events include	3	The T3 Code server sends product usage events to PostHog, associated with a hashed account or
4	the provider, model, reasoning effort, permission mode, turn result, duration,	4	installation identifier. Events include the provider, model, reasoning effort, permission mode,
5	and normalized main-agent token totals when the provider reports them.	5	turn result, duration, and main-agent token totals when available.
6		6
7	T3 Code does not send prompts, responses, file contents, raw provider events,	7	Events do not include prompts, responses, file contents, authentication tokens, conversation IDs,
8	thread IDs, turn IDs, provider instance IDs, authentication tokens, or child	8	raw provider events, or child-agent output. Child-agent token use is excluded from the totals.
9	agent output. Token totals can be complete, partial, or unavailable. Child
10	agent token use is not included.
11		9
12	Set `T3CODE_TELEMETRY_ENABLED=false` before you start the T3 server to stop	10	To disable collection, set `T3CODE_TELEMETRY_ENABLED=false` in the server's environment before
13	product events from being recorded or sent. The server still derives an	11	starting it. This stops product events from being recorded or sent.
14	anonymous identifier during startup and can create its local fallback
15	identifier file.

docs/user/thread-sidebar.md+73-88

...	@@ -1,88 +1,73 @@	...	@@ -1,88 +1,73 @@
1	# Organizing threads	1	# Working with threads
2		2
3	Pin a thread from its context menu to keep it in the pinned section above your active work.	3	Use a new thread for a separate task. Choose New worktree when its code changes
4	`mod+shift+p` pins or unpins the thread you have open. Pinned threads are shown independently of	4	need a separate branch and working directory.
5	their project, including when you connect to more than one environment.	5
6		6	## Start a thread
7	To require confirmation before unpinning, enable Settings → General → Unpin confirmation. The	7
8	confirmation applies to the sidebar controls, thread menus, and the `mod+shift+p` shortcut.	8	On web and desktop, a new thread keeps the current project and carries your model
9		9	and mode selections, unless the destination project has its own model default.
10	Pinned threads still move to Settled when they become inactive. They also move when their pull	10	Its branch and workspace mode come from your configured defaults. To continue in
11	request merges if Auto-settle merged threads is enabled.	11	an existing worktree, use New thread in this worktree from the branch toolbar.
12		12
13	Each server stores its own copy of the automatic settlement settings and checks them even when no	13	When you change a new thread's project, T3 Code stays in the current environment
14	web, desktop, or mobile client is connected. By default, it settles threads after three days without	14	if that project exists there. Otherwise it selects an environment that has it.
15	activity and when their pull request merges. An eligible idle thread also settles when its pull	15
16	request closes. An open pull request does not block inactivity settlement. Active work, pending	16	### Start in the background
17	input, and live background work keep the thread active. T3 Code settles from a closed or merged	17
18	pull request only when its timestamp is not older than the user's latest activity. If that timestamp	18	In a desktop browser or the desktop app, press `Cmd+Enter` on macOS or `Ctrl+Enter`
19	is not available, the inactivity rule still applies. A manual un-settle also keeps the thread active.	19	on Windows and Linux to start a new thread and immediately open another draft. The
20		20	next draft keeps the workspace mode and base branch you selected. With **New
21	Settled lists threads by when their work finished, newest first. A thread you settle yourself	21	worktree**, each background submission creates its own worktree.
22	sorts by the moment you settled it. A thread that settled on its own sorts by its last message or	22
23	turn, not by when the server noticed it was inactive.	23	## Pin and reorder threads
24		24
25	Change these rules in Settings > General. The change is written to every connected environment	25	Pin a thread from its menu to keep it above your active work. Drag pinned threads
26	whose server supports shared settings. An environment that is offline or needs a server update	26	to reorder them on web and desktop, or use Move up and Move down on mobile.
27	keeps its old value and does not appear in mismatch warnings. When a connected environment whose	27	The order syncs across devices.
28	server supports shared settings holds a different value, Settings > General shows a warning	28
29	that names it. Choose Apply to all to write your current values to the environments named in	29	Pinning does not prevent automatic settlement. Settling a thread removes its pin.
30	the warning. The same applies to the new-thread workspace mode and the source control writing	30
31	style.	31	## Settle finished work
32		32
33	A settings change affects future settlement and does not reopen a settled thread. Settings saved	33	Choose Settle thread from its menu to move finished work out of the active list
34	by older clients on one device no longer control this behavior.	34	without deleting the conversation. Un-settle thread restores it to active work
35		35	and prevents automatic settlement until new activity resumes the usual rules.
36	When you un-settle a thread, it returns to the top of the active list so you can find it right	36
37	away. Its timestamps do not change. Other threads keep their positions.	37	By default, environments settle inactive threads after three days and settle
38		38	threads whose pull request merged. A closed pull request can also settle an idle
39	A thread whose composer holds unsent text or attachments shows an amber tint and a pen icon in the	39	thread. Work in progress, pending questions or approvals, and live background work
40	sidebar, the same marks a new-thread draft uses. On web and desktop, hover the row and choose the	40	prevent automatic settlement. An open pull request does not prevent inactivity
41	X to discard that draft without opening the thread.	41	settlement, but an old closed or merged pull request does not settle work you
42		42	resumed after it closed.
43	Right-click a pull request link in a thread and choose Link to thread to show that pull request	43
44	in the sidebar. The thread settles when the linked pull request merges if **Auto-settle merged	44	Change these rules in Settings → General. They continue to run when your apps
45	threads is enabled. Right-click the same link and choose Unlink from thread** to remove it.	45	are closed. Changes apply to connected environments that support shared settings;
46		46	offline environments and older servers keep their previous values. If connected
47	On web and desktop, drag a pinned thread to change its position. On mobile, open the thread's menu	47	environments disagree, Apply to all copies your current settings to those named
48	and choose Move up or Move down. The order is stored by the server and appears on your	48	in the warning. Changing a rule does not reopen already settled threads.
49	other connected devices.	49
50		50	## Link a pull request
51	If reordering is unavailable for one environment, update the T3 Code server running in that	51
52	environment. Older servers can still pin and unpin threads, but do not understand synced ordering;	52	On web and desktop, right-click a pull request link in a thread and choose
53	their pinned threads keep the default newest-first order below the ones you have arranged.	53	Link to thread. Use Unlink from thread on the same link to remove it.
54		54	The linked pull request participates in automatic settlement.
55	## Panel motion	55
56		56	## Find and reference work
57	The main sidebar, right panel, and terminal drawer open and close immediately by default. Under	57
58	Settings → Appearance → Motion, move the Panel animations slider above 0 ms to add motion.	58	On web and desktop, open the command palette with `Cmd/Ctrl+K` to search threads
59	The duration can be set up to 400 ms. Clicking the preview replays all three panel transitions; at	59	across connected environments. Message search starts after two characters and
60	0 ms, it snaps between the same open and closed states.	60	includes your messages and final agent responses.
61		61
62	## Environment icons	62	Use Settings → Keybindings to find or customize shortcuts for searching files
63		63	and copying a thread reference. A copied reference uses the thread's pull request
64	When you are connected to more than one environment, every thread that lives somewhere other than	64	link when available, otherwise its thread ID. See [keybindings](./keybindings.md)
65	the machine you are on wears a small icon for that machine at the end of its row: a server, a cloud	65	for custom configuration.
66	VM, a desktop, a laptop, a Mac mini, or a Mac Studio. In the hosted web app and the mobile app,	66
67	where every environment is remote, each row wears its machine so you can tell them apart at a	67	## Inspect agent work
68	glance. The same icon appears wherever an environment is named: the thread tooltip, the command	68
69	palette, the "Run on" picker, the pull request server filter, the provider settings device tabs,	69	On web and desktop, use Agents to follow work delegated to subagents.
70	and the environment lists under Settings → Connections. On mobile it appears in the thread	70
71	lists, the archive, the new-task environment picker, and the Environments and storage settings.	71	Expand a tool call in the conversation to see its full command and output.
72		72	Summaries shorten shell wrappers and can still describe the latest call after it
73	Servers pick the icon themselves from the hardware they run on. A Mac reports its model, a Linux	73	finishes; the call's own result shows its status.
74	machine reports its chassis type and whether it is a virtual machine, and anything without a usable
75	signal shows a generic server. To override it, open Settings → Connections and choose an icon
76	for that environment; Automatic goes back to what the server detected. The choice is stored on
77	that server, so every device that connects to it sees the same icon.
78
79	## Environment artwork
80
81	Dev and Nightly environments can identify themselves with artwork at the top of the sidebar and in
82	the send button. Choose Artwork, Version pill, or None in Settings under environment
83	identification. Artwork is recolored to match each built-in theme. Custom themes use the **Version
84	pill** fallback because their colors are not controlled by T3 Code.
85
86	To generate a fresh title from the conversation, open a thread's context menu and choose
87	Regenerate title. While T3 Code is generating it, the action reads Regenerating… and cannot
88	be selected again. The option is hidden when the connected environment needs a server update.

docs/user/tool-activity.md deleted-25

...	@@ -1,25 +0,0 @@
1	# Tool activity
2
3	Open a tool-group summary in the conversation to see its individual calls. Each row has an icon;
4	select a row to inspect its details. Select the group summary again to collapse it.
5
6	Long groups scroll inside a bounded area without expanding the whole conversation. Faded edges
7	indicate more calls above or below. Short groups use only the space they need.
8	Collapsing and reopening a group preserves your reading position and any open call details.
9
10	Recognized T3 tools use descriptive labels in both the running summary and individual rows.
11	The latest live activity stays in the present tense while the turn continues, such as
12	"Running vp" or "Clicking in the preview browser", even after that call has completed.
13	Expanded rows follow the call's own state, such as "Clicked" after success.
14	When a call has not reported a state yet, the label stays in the present tense.
15	Failed, declined, and stopped calls say what happened without implying success.
16	Failed calls keep their tool icon with a muted red tint, so a failed command still
17	looks like a command. App logos and other multicolor icons keep their artwork and
18	show a small muted red failure mark beside the row. Expand the call to inspect its
19	output. Runtime errors and warnings keep their stronger styling.
20	Preview browser actions use a globe icon. Other T3 tools keep the T3 mark.
21	Group summaries count browser actions separately, such as "Used browser 18 times" or
22	"Ran 4 commands and used browser 15 times". Browser-only groups also use a globe icon.
23
24	Command summaries show the program inside a shell wrapper, such as "Running vp" for
25	`/bin/zsh -lc 'vp test run'`. Expanded rows keep the full command.

docs/user/updating.md+38-75

...	@@ -1,95 +1,58 @@	...	@@ -1,95 +1,58 @@
1	# Keeping T3 Code in Sync	1	# Updating T3 Code
2		2
3	The T3 Code web or desktop app and the server it connects to work best when they use the same	3	The app you use and the server running your agents can be on different machines.
4	version. If they do not match, T3 Code shows a warning with the right update option for that server.	4	When a server is behind your web or desktop app, an update notice appears in the
		5	conversation and Settings → Connections. Update the machine named in that
		6	notice.
5		7
6	## Where to Find the Update	8	## Before you update
7		9
8	You may see the warning in either of these places:	10	Server updates restart the connection and can interrupt active agents and
		11	terminal commands. Saved threads, settings, and project files remain.
9		12
10	- above the message box in the current conversation	13	Settings → General → Continue threads after server updates is off by default.
11	- Settings → Connections, beside the affected connection	14	Enable it to resume supported active threads once the replacement server is
		15	ready. Terminal commands may still be interrupted.
12		16
13	Dismissing the conversation warning only hides that reminder for those two versions. It does not	17	## Update a connected server
14	update the server, and the version difference remains visible in Connections.
15		18
16	## Before You Update	19	The offered action depends on how the server runs:
17		20
18	Updating restarts the server, so the connection will disappear briefly. Settings → General	21	\| Action \| What to do \|
19	has a Continue threads after server updates preference. It is off by default. When enabled, the	22	\| -------------------------- \| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- \|
20	update buttons automatically resume supported provider threads after the replacement server is	23	\| Update server \| Keep the client open while it installs and reconnects. Supported background services update remotely. For a desktop-hosted server, this also closes and relaunches the desktop app on the host. \|
21	ready. Providers with native promptless continuation use it; other providers receive a short	24	\| Update the desktop app \| Update the desktop app on the machine running the server, then reopen it if needed. \|
22	instruction to continue where they left off. Terminal commands and other running work may still be	25	\| Copy update command \| Stop the command-line server on its host and relaunch with the copied command, keeping your usual startup options. \|
23	interrupted during the update.
24		26
25	The update does not remove saved threads, settings, or project files.	27	For a background service, run the matching version's CLI on the host:
26
27	## Choose the Action You See
28
29	\| Action \| What to do \|
30	\| -------------------------- \| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- \|
31	\| Update server \| Available for the T3 Code Linux background service and for servers run by a current T3 Code desktop app. Select the button and leave T3 Code open while it downloads, installs, restarts, and reconnects. For desktop-app servers this closes and relaunches the desktop app on that machine. If installation fails, the desktop app stays open and reconnects to its server. \|
32	\| Update the desktop app \| Shown for desktop apps that predate remote updates. Open the T3 Code desktop app on the machine that runs the server and install the app update there. Reopen it if needed. \|
33	\| Copy update command \| Copy the command, open a terminal on the server machine, stop the current T3 Code server, and relaunch it with the copied command and any startup options you normally use. \|
34
35	The available action depends on how that server was started. T3 Code does not update connected
36	servers silently in the background.
37
38	An older background-service launcher may ask you to run the exact
39	`npx t3@<version> service update` command on the server machine. That one local update installs the
40	rollback support needed for later remote updates, including versions that change the database.
41
42	After selecting Update, the notice becomes a live status line: Downloading… while the new
43	version is fetched and verified, then Restarting… while the server restarts into it. The same
44	status appears in the conversation and in Connections, so navigating between them does not lose the
45	update. A failure remains visible with its error and an option to retry.
46
47	Copy update command gives you `npx t3@<client-version>`, which relaunches the server directly
48	at the matching version. Add whatever startup options you normally use.
49
50	If the server instead runs as the T3 Code background service, update the service on the host and
51	pin the same version:
52		28
53	```sh	29	```sh
54	npx t3@<client-version> service update	30	npx t3@<client-version> service update
55	```	31	```
56		32
57	`service update` installs the version of the CLI that invoked it, so `npx t3@latest service update`	33	Replace `<client-version>` with the version shown in the notice. Using
58	only resolves the skew when your client happens to be on the latest release. The exact version from	34	`@latest` only resolves the mismatch if your client is on that release. An older
59	the warning always works.	35	service launcher may require this local update before it supports remote updates
60		36	and rollback.
61	See [Running T3 Code in the Background](./background-service.md) for install, status, and removal
62	commands.
63
64	## Nightly desktop release notes
65		37
66	The desktop app shows a compact release-notes preview when a nightly update is available. Changes	38	For a foreground server, the copied command is `npx t3@<client-version>`. Add
67	appear newest first within each release. Each release links to its exact page on GitHub, even when	39	`serve` if you normally run without a browser, and preserve options such as
68	all changes fit in the preview.	40	`--host` or `--tailscale-serve`. See
		41	[background services](./background-service.md) for service management.
69		42
70	The preview shows up to eight changes from each of six releases. When it leaves out changes or older	43	## If an update fails
71	releases, it shows the exact number and links to the rest. Contributor credits do not count as
72	changes.
73		44
74	## After the Update	45	Keep the client open until it reconnects or reports a failure. A failed service
75		46	update can roll back to the previous version. If the update still fails:
76	Keep the web or desktop app open while the server restarts. The update completes only after the
77	service launcher reports that exact update committed and the replacement server is ready to accept
78	commands. A rollback is reported immediately instead of waiting for a generic reconnect timeout.
79
80	If a step fails:
81		47
82	1. Retry the offered action once.	48	1. Retry the offered action once.
83	2. Make sure you updated the machine named in the warning, not only the device you are using.	49	2. Check that you updated the server's machine, not only the device you are using.
84	3. For a command-line server, relaunch it with `npx t3@<client-version>`, replacing	50	3. For a command-line server, stop it and relaunch the exact version shown in the notice.
85	`<client-version>` with the client version shown in the warning.
86
87	## The Mobile App
88		51
89	The mobile app keeps itself current on its own. When it finds a new version, it downloads it in the	52	## Mobile updates
90	background and installs it automatically the next time you leave the app. Unsent drafts and queued
91	messages are saved before the restart. Only if the app stays open long enough that the update never
92	gets that chance does it ask whether to install right away; choosing Later is safe and keeps the
93	automatic install armed.
94		53
95	For remote connection setup and access troubleshooting, see [Remote Access](./remote-access.md).	54	Install App Store or Google Play releases as usual. The mobile app can also
		55	download updates in the background and apply them when you next leave the app.
		56	It saves drafts and queued messages before restarting. If you keep the app open
		57	for a long time, it may ask to install immediately; choosing Later leaves the
		58	update queued for the next suitable moment.

docs/user/usage.md+31-35

...	@@ -1,35 +1,31 @@	...	@@ -1,35 +1,31 @@
1	# Review usage	1	# Usage and limits
2		2
3	The Usage page combines Codex, Claude Code, and Grok Build activity from your connected	3	## Understand your usage
4	environments. It reads the providers' local session history and shows API-equivalent token cost,	4
5	processed tokens, cache savings, provider shares, and model breakdowns. Subscription billing is	5	Usage combines Codex, Claude Code, and Grok Build session history from your connected
6	separate from the raw token cost shown here.	6	environments. It shows token use, cache savings, model breakdowns, and estimated API-equivalent
7		7	cost. These estimates are not your subscription bill.
8	Grok Build totals come from persisted session updates. Interactive turns that never wrote a	8
9	completed-turn record will not appear.	9	Totals depend on the history available on each server. Grok turns without a saved completed-turn
10		10	record are missing from the totals.
11	The Limits view shows how much of each subscription window you have used on Codex and Claude	11
12	Code, per connected environment: the session and weekly windows, plus a per-model weekly window	12	If recent work is missing or a new model shows no cost, refresh to rescan session history and
13	such as Fable when your plan has one. Each window is a bar from the moment it opened to its reset,	13	update model pricing.
14	filled by the share of quota spent; a thin line marks how far into the window you are, which is	14
15	also where even spending would have put the fill, and the icon beside the label says whether you	15	## Track subscription limits
16	are ahead of, on, or under that pace. Hover a bar for the exact reset time. Limits refresh on the	16
17	provider health-check interval and update live while a turn runs. API-key accounts have no	17	Usage → Limits shows quota use and reset times for Codex and Claude subscriptions. It also
18	subscription windows and say so; that includes a Claude Code that reaches Anthropic through a proxy	18	compares quota consumed with time elapsed in each window, so you can judge your pace before the
19	via `ANTHROPIC_AUTH_TOKEN`, since the CLI then treats itself as an API-key client.	19	next reset.
20		20
21	If you pool accounts behind a CLIProxyAPI hub, open Settings → Providers → Usage providers	21	API-key accounts may not report subscription limits. This also applies to Claude connections
22	and choose Add hub. Select the device that should connect to the hub; its accounts appear on	22	using a proxy through `ANTHROPIC_AUTH_TOKEN`.
23	the Limits view. Remove hubs from the same settings section. Each limits row shows its provider	23
24	and instance name, or a small _CLI Proxy_ label for	24	## Connect a CLIProxyAPI hub
25	hub accounts. When a connected provider reports limits for the same provider and email, its row	25
26	replaces the hub copy, keeping details such as banked reset credits. The hub copy remains visible	26	To see pooled accounts, open Settings → Providers → Usage providers → Add hub. Choose the
27	if the connected provider cannot report limits. Enter the hub's URL and management key; the key	27	environment that will connect to the hub and enter its URL and management key.
28	is stored on the server and never sent back to a client. Emails are blurred until clicked, as in	28
29	provider settings.	29	The accounts appear under Usage → Limits. This connection supplies usage information; configure
30		30	the provider separately to send agent requests through the hub. Remove the hub from the same
31	Use Past 24h for an hourly chart covering the exact rolling 24-hour period. The 7 days,	31	settings section when you no longer need it.
32	30 days, and 90 days ranges use daily resolution. Cost and token toggles update both the
33	headline and chart. Refreshing rescans every connected environment and refetches model pricing on
34	each of them, so a newly released model that showed $0.00 gets a price without waiting for the daily
35	pricing update.