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	79	- [Install and first run](./docs/user/install.md)
80	80	- [Permission modes](./docs/user/permission-modes.md)
81	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	83	- [Remote access from a phone or another machine](./docs/user/remote-access.md)
84	84	- [Keeping app and server in sync](./docs/user/updating.md)
85	85	- [Source control integrations](./docs/user/source-control.md)
86	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	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 @@
2	2
3	3	## Using T3 Code
4	4
5		- [Install and first run](./user/install.md)
	5	- [Install T3 Code](./user/install.md)
	6	- [Messages and context](./user/composer.md)
	7	- [Working with threads](./user/thread-sidebar.md)
6	8	- [Permission modes](./user/permission-modes.md)
	9	- [Terminal history](./user/terminal.md)
	10	- [Source control](./user/source-control.md)
	11	- [Project settings](./user/project-settings.md)
	12	- [Appearance and themes](./user/appearance.md)
7	13	- [Keyboard shortcuts](./user/keybindings.md)
8		- [Organizing threads](./user/thread-sidebar.md)
9		- [Review usage](./user/usage.md)
10		- [Anonymous usage data](./user/telemetry.md)
11		- [Customize a project icon](./user/project-settings.md)
12		- [Mobile appearance](./user/mobile-appearance.md)
13		- [Environment themes](./user/environment-theme.md)
	14	- [Import browser sessions](./user/browser-import.md)
	15	- [Usage and limits](./user/usage.md)
	16	- [Product usage data](./user/telemetry.md)
14	17	- [Remote access](./user/remote-access.md)
15		- [Keeping app and server in sync](./user/updating.md)
16		- [Source control integrations](./user/source-control.md)
17		- [Background service (Linux)](./user/background-service.md)
18		- Providers: [Codex](./user/providers-codex.md) · [Claude](./user/providers-claude.md) · [OpenCode](./user/providers-opencode.md)
19
20		Mobile app: [apps/mobile/README.md](../apps/mobile/README.md)
	18	- [Running in the background](./user/background-service.md)
	19	- [Updating T3 Code](./user/updating.md)
	20	- Provider guides: [Codex](./user/providers-codex.md) · [Claude](./user/providers-claude.md) · [OpenCode](./user/providers-opencode.md) · [Antigravity](./user/providers-antigravity.md)
21	21
22	22	---
23	23

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		# 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
4		keeping a terminal open.
	3	On Linux and macOS, T3 Code can run as a service for your user so you do not need
	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
11		npx t3@latest service install
12		```
13
14		Check whether it is installed. On Linux this also checks whether the service is running, enabled
15		at startup, and allowed to keep running after logout:
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`:
	10	\| Task \| Command \|
	11	\| ------------------------------- \| --------------------------------- \|
	12	\| Install and start \| `npx t3@latest service install` \|
	13	\| Inspect status and log location \| `npx t3@latest service status` \|
	14	\| Update or repair \| `npx t3@latest service update` \|
	15	\| Stop and remove from startup \| `npx t3@latest service uninstall` \|
38	16
39		```sh
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.
	17	Uninstalling the service leaves your projects, threads, and settings intact.
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
61		when the machine boots and keeps running after you log out (lingering is enabled during install).
62		Setup checks the systemd user manager and enables lingering before installing a runtime or stopping
63		an existing service. If that requires administrator permission, setup stops with a recovery command.
	24	Updating restarts the server. Finish active work first, and wait for any remote
	25	update already in progress. To match a remote client's version, follow
	26	[Updating T3 Code](./updating.md).
64	27
65		macOS uses a launch agent at `~/Library/LaunchAgents/com.t3tools.t3code.service.plist`. It
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.
	28	## Platform support
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.
74		Without that, the install command reports an error at the final start step, but the agent is
75		fully installed and starts at the next login.
76		- macOS may show privacy prompts for protected folders such as Desktop, Documents, or Downloads,
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.
	34	macOS starts the service when you log in and stops it when you log out. Keep the
	35	Mac logged in and awake for unattended remote access. Installing over SSH while
	36	nobody is logged in at the Mac's screen can fail at the final start step; the
	37	service is still installed and will start at the next login.
83	38
84		Windows is not supported yet.
	39	Windows background services are not supported.
85	40
86		## Using It with T3 Connect
87
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.
	41	T3 Connect can offer service installation during setup, but the two are managed
	42	separately. Signing out of T3 Connect does not stop or uninstall the service.
93	43
94	44	## Troubleshooting
95	45
96		Run `t3 service status` on the server machine. An installed version alone does not mean the service
97		is running or will survive logout. Linux status reports these problems:
	46	Start with `t3 service status` on the host. It prints the log path and, on Linux,
	47	checks whether the installed service is running, enabled, and allowed to survive
	48	logout.
98	49
99		\| Code \| What it means \| Recovery \|
100		\| -------------------------- \| -------------------------------------------------------------------------------- \| ------------------------------------------------------------------------------------------------------------------------------------------ \|
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:
	50	If it stops when your SSH session closes, check for `linger-disabled`. An
	51	administrator can enable lingering with:
109	52
110	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
115		Connect identity for root. If an administrator is unavailable, run `t3 serve` in a terminal and
116		keep that session open.
	57	Over SSH, allow sudo to prompt:
117	58
118		The repair command shown by status uses the CLI version, or the installed service version if that
119		is newer. An older stable CLI therefore does not recommend downgrading a nightly installation.
120		Setup leaves an existing service running if the user-manager or lingering check fails.
	59	```sh
	60	ssh -t your-server 'sudo loginctl enable-linger "$(id -un)"'
	61	```
121	62
122		`t3 service status` prints the log path. The adjacent `server.trace.ndjson` file contains detailed
123		server traces. For failures after authorization, see [T3 Connect troubleshooting](./remote-access.md#t3-connect-troubleshooting).
	63	Then retry service setup as your normal user. Run only the `loginctl` command
	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		# Import browser logins
	1	# Import browser sessions
2	2
3		In the desktop app, open Settings → Integrations → Browser profiles → Add profile
4		and choose a browser under Import from. The import copies cookies into a T3 Code browser
5		profile so you can use existing logins in the preview browser. Changes made afterward stay
6		separate from the source browser.
	3	The desktop app can import cookies from another browser so you can reuse its signed-in sessions
	4	in the preview browser.
7	5
8		Linux discovery includes Helium and both native and Snap installations of Firefox. Windows
9		discovery includes Firefox and Helium builds that still use Windows' standard profile
10		encryption. Other Chromium-based browsers on Windows use app-bound cookie encryption and cannot
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.
	6	Open Settings → Integrations → Browser profiles → Add profile, then choose a browser under
	7	Import from. Close the source browser before importing, and allow an operating-system keyring
	8	unlock prompt if one appears.
13	9
14		On Linux, Chromium-based browsers use your desktop keyring to protect their cookies. T3 Code
15		includes the keyring reader; no separate command-line tool is needed. Allow the desktop unlock
16		prompt if one appears. If the keyring cannot be accessed, T3 Code reports that failure when no
17		cookies can be imported. Partitioned cookies are skipped.
	10	This is a one-time copy. Later login changes stay separate between the two browsers, and some
	11	sites may still require you to sign in again.
	12
	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		# Message composer
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.
	1	# Messages and context
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
75		selection for new threads. A model configured in a project's settings overrides the remembered
76		selection for that project; resetting the project setting returns it to the remembered selection.
	6	Messages can contain up to 120,000 characters. Longer drafts stay in the composer
	7	so you can shorten them or split them into several messages.
77	8
78		Model options shown as provider defaults remain display values until you choose them in T3 Code.
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.
	9	## Attach files
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
85		menu that appears when you release the selection. This inserts an inline quote chip at your cursor
86		and opens an optional comment bubble beside the selected text; press `Enter` or choose Save to
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.
	15	Uploads begin when you add an attachment. All uploads must finish before the
	16	message can send. Retry or remove a failed upload. On web and desktop, reloading
	17	before an upload finishes requires you to attach that file again.
90	18
91		The chip shows your comment when it has one, or a short quote preview otherwise. Use the pencil
92		button to add or change the comment, and the remove button to delete the quote and its comment from
93		the draft. Copying, reloading, and restoring a [stashed prompt](#prompt-stash) keep each comment
94		with its quote, and sending tells the agent which words were quoted and which comment you wrote.
95		The quoted text and comment count toward the message limit.
	19	You can drag or paste images into the web or desktop composer. HEIC and HEIF
	20	photos are converted to JPEG there and when selected from the iOS photo library;
	21	the image limit applies after conversion. On mobile, you can also send files to
	22	T3 Code through another app's system share sheet.
96	23
97		Select a chip in the composer or a sent message to open the source thread, scroll to the response,
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.
	24	See [images and videos](#images-and-videos-in-messages) for previewing and saving media.
102	25
103		Mobile shows the full saved quote and its comment in sent messages. It does not offer
104		Cite in composer or navigation to a quote's source.
	26	## Queue messages offline on mobile
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.
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.
	33	## Model defaults
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
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.
	39	Leaving reasoning level or service tier unset uses the provider's own configuration.
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
161		source toggle in the viewer's header to switch an HTML file between the page and its markup; the
162		choice persists like the rendered-Markdown toggle. A link to a line always opens the source. HTML
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.
	43	On web and desktop, select text within one assistant response and choose
	44	Cite in composer. You can add a comment about the quote and write instructions
	45	around it.
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
169		project exists there. If it does not, T3 Code selects another environment that has the project.
	50	Mobile displays saved quotes and comments, but does not create citations or
	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
174		stash tab. Task progress appears above the composer, while the timeline's working timer shows
175		only elapsed time.
	55	On web and desktop, press `Cmd+S` on macOS or `Ctrl+S` on Windows and Linux to save
	56	the current prompt and its attachments for later. Wait for uploads to finish first.
	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
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.
	64	## Voice input on iPhone
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
187		prompt and its attachments after all file uploads finish. When the composer is empty and the stash
188		has one entry, press the shortcut again to restore it. The shortcut opens the stash menu if there
189		are multiple entries or the entry's images are still saving. You can also open the menu from the
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.
	70	The first use may download Apple's speech model and needs a network connection.
	71	Later transcription works offline for that language. Recordings can be up to five
	72	minutes long. Canceling, leaving the screen, or an audio interruption discards the
	73	recording and preserves your existing draft.
194	74
195		## Voice input on iPhone
196
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.
	75	Transcription runs on your device. T3 Code deletes the temporary audio after
	76	transcription or cancellation; only the message text is sent when you submit.
211	77
212	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,
215		such as System, Personal, Project, or App.
	80	Type `/` for commands or `$` to add a skill from the selected environment and
	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
218		use the skills and commands from the selected environment and provider.
	98	On web and desktop, right-click media to save it or copy its path or URL. On mobile,
	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
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.
	106	## Files outside the workspace
227	107
228		A skill token runs the skill wherever it sits in your message. T3 Code sends it to each provider in
229		the form that provider runs, so the text before and after the token is kept. Skills that only you may
230		start, and never the agent on its own, work the same way. A skill you switched off in the provider's
231		settings does not appear in either menu.
	108	Follow an agent's file link to read a report or other file outside the workspace.
	109	These files open read-only. An HTML file outside the workspace cannot load scripts,
	110	styles, or images from neighboring files.
	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
234		them only there. T3 Code's own commands, such as `/model` and `/plan`, and skills stay available on
235		any line.
	114	On web and desktop, HTML and PDF files open as rendered pages. Switch an HTML
	115	file to source view to read its markup; a link to a specific line opens source
	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
238		start it in the background. T3 Code opens another new thread and shows an Open action for the
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.
	118	On mobile, select a PDF attachment or link to open it. iOS uses the native viewer;
	119	Android opens the system chooser.

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	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	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
10		T3 Code settings. See [Providers](#providers) below.
	11	You need an installed, authenticated provider before starting a thread. You can
	12	launch T3 Code and configure providers afterwards.
11	13
12		## Run Without Installing
	14	## Run without installing
13	15
14	16	```bash
15	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
19		`npx t3@latest --help` for the full CLI reference.
	20	This starts the server and opens the local web app. Run
	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
22		Reload to try again.
	23	## Desktop app
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
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.
	35	### Windows Subsystem for Linux
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
53		winget install T3Tools.T3Code
54		```
	42	### Open a project from a terminal
55	43
56		macOS:
	44	With the desktop app already running on the same machine:
57	45
58	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
67		yay -S t3code-bin
68		```
69
70		Nightly:
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.
	57	Install T3 Code from the
	58	[App Store](https://apps.apple.com/us/app/t3-code-remote-claude-more/id6787819824) or
	59	[Google Play](https://play.google.com/store/apps/details?id=com.t3tools.t3code).
	60	The phone connects to a server on another machine. Follow
	61	[remote access](./remote-access.md) to link it through T3 Connect or a pairing URL.
85	62
86	63	## Providers
87	64
88		T3 Code uses provider runtimes but does not bundle them. Install and authenticate each
89		provider's CLI, or use T3 Code's managed setup for Antigravity.
90
91		\| Provider \| CLI \| Default binary \| Log in with \|
92		\| ----------- \| ---------------------------------------------------------------------------------------------------------- \| ------------------ \| ---------------------------------- \|
93		\| Codex \| [Codex CLI](https://developers.openai.com/codex/cli) \| `codex` \| `codex login` \|
94		\| Claude \| [Claude Code](https://claude.com/product/claude-code) \| `claude` \| `claude auth login` \|
95		\| Cursor \| [Cursor CLI](https://cursor.com/cli) \| `cursor-agent` \| `agent login` \|
96		\| Grok Build \| [Grok Build CLI](https://x.ai/cli) \| `grok` \| `grok login` \|
97		\| OpenCode \| [OpenCode](https://opencode.ai) \| `opencode` \| `opencode auth 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 \|
99
100		Codex and Claude are on by default. Cursor, Grok Build, OpenCode, and Antigravity are off by
101		default. Turn them on in Settings > Providers when you want to use them.
102
103		For Antigravity, select the environment in provider settings, then install and sign in there.
104		The runtime and credentials stay on that environment, even when you use a phone or remote
105		browser. See [Antigravity setup](./providers-antigravity.md) for Google sign-in, remote callback
106		steps, and supported hosts.
107
108		Cursor is the one to watch: install Cursor CLI, which provides the `cursor-agent` binary that
109		T3 Code looks for, but authenticate with `agent login`, not `cursor-agent login`.
110
111		Grok models that support adjustable reasoning show a Reasoning control beside the model picker.
112		The available levels and default come from the installed Grok Build CLI, so they can vary by model
113		and CLI version.
114
115		Run CLI login commands on the machine running the T3 Code server, not on the device you browse
116		from. Antigravity uses its sign-in controls in T3 Code instead of a CLI login command.
117
118		### Binary Discovery
119
120		Each provider CLI must be on the server's `PATH`, or have an explicit binary path set in
121		Settings → the provider instance → Binary path. Use the explicit path when a version
122		manager or a non-standard install location keeps the CLI off the `PATH` of the shell that
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
	65	Open Settings → Providers in the web or desktop app, select the environment,
	66	and enable the provider you want. Installation, login, and configuration belong
	67	to that environment's machine, even when you connect from a phone or another
	68	computer.
	69
	70	\| Provider \| Install and authenticate \|
	71	\| ----------- \| -------------------------------------------------------------------------------------------- \|
	72	\| Codex \| Install [Codex CLI](https://developers.openai.com/codex/cli), then run `codex login`. \|
	73	\| Claude \| Install [Claude Code](https://claude.com/product/claude-code), then run `claude auth login`. \|
	74	\| Cursor \| Install [Cursor CLI](https://cursor.com/cli), then run `agent login`. \|
	75	\| Grok Build \| Install [Grok Build CLI](https://x.ai/cli), then run `grok login`. \|
	76	\| OpenCode \| Install [OpenCode](https://opencode.ai), then run `opencode auth login`. \|
	77	\| Antigravity \| Install and sign in with Google from T3 Code's provider settings. \|
	78
	79	Provider CLIs must be on the server's `PATH`. If T3 Code cannot find one, set its
	80	Binary path in provider settings, especially when using a version manager.
	81	Cursor's executable is `cursor-agent`, although its login command is
	82	`agent login`. Antigravity can use its managed runtime without a `PATH` entry.
	83
	84	Add another provider instance for a separate account or configuration. Each
	85	instance can have its own environment variables, such as API keys or a custom
	86	base URL. Mark secret values as sensitive; after saving, T3 Code does not display
	87	their original values.
	88
	89	For provider-specific setup and accounts, see [Codex](./providers-codex.md),
	90	[Claude](./providers-claude.md), [OpenCode](./providers-opencode.md), and
	91	[Antigravity](./providers-antigravity.md).
	92
	93	## Next steps
	94
	95	- [Working with threads](./thread-sidebar.md): start tasks and organize parallel work.
	96	- [Permission modes](./permission-modes.md): choose when agents ask before acting.
	97	- [Remote access](./remote-access.md): connect from another device.
	98	- [Running in the background](./background-service.md): keep a Linux or macOS host available.
	99	- [Updating T3 Code](./updating.md): update the app and connected servers.

docs/user/keybindings.md+46-93

...	...	@@ -1,14 +1,13 @@
1	1	# Keybindings
2	2
3		Edit keybindings from Settings → Keybindings. That page lists every command, its current
4		shortcut, whether it is a default or your own, and warns about conflicts.
	3	Customize shortcuts in Settings → Keybindings on web and desktop. That page
	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
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.
	6	## Edit the configuration file
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	12	```json
14	13	[
...	...	@@ -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`
25		- `command` (required): the command ID to run
26		- `when` (optional): boolean expression controlling when the shortcut is active
	26	Each rule requires a `key` shortcut and a `command` ID. An optional `when`
	27	expression restricts when it runs.
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		`alt` / `option`.
	31	## Key syntax
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
38		`chat.new`. Project scripts are addressable as `script.{id}.run`, for example `script.test.run`.
	39	Available context keys are `terminalFocus`, `terminalOpen`, `previewFocus`,
	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`.
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.
	42	Combine keys with `!` for not, `&&` for and, `\|\|` for or, and parentheses:
51	43
52		`rightPanel.toggleMaximized` maximizes or restores the open right panel. It has no default shortcut,
53		so add one in Settings → Keybindings if you want to use it.
54
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`.
	44	```json
	45	{ "key": "mod+j", "command": "terminal.toggle", "when": "terminalOpen && !terminalFocus" }
	46	```
60	47
61		`thread.copyReference` copies the active thread's pull request link, or its thread ID when no pull
62		request is available. Its default shortcut is `mod+shift+c`, and it does not replace terminal copy
63		while the terminal has focus.
	48	## Precedence
64	49
65		`thread.settle` settles the active thread or restores it when it is already settled. Its default
66		shortcut is `mod+shift+s`, and it does not run while the terminal has focus.
	50	The last rule whose key and condition both match wins, even if it belongs to a
	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
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.
	54	## Commands with special behavior
71	55
72		The command palette searches settings, active thread titles, projects, branches, user messages, and
73		final agent responses across connected environments. A setting result opens its exact control or
74		section. Message matches show one labeled excerpt while keeping the thread's project, branch, and
75		machine context visible. Message search begins after two characters and uses SQLite's ASCII
76		case-insensitive matching.
	56	`chat.new` may ask you to choose a project when there is more than one.
	57	`chat.newLocal` skips that chooser. Both use your
	58	[new-thread defaults](./thread-sidebar.md#start-a-thread).
77	59
78		The full command list and the current defaults are shown in Settings → Keybindings, which
79		always matches the build you are running. Use that rather than a copied list.
	60	## Reserved shortcuts
80	61
81		Note that `chat.new` and `chat.newLocal` both create a thread through the same path. A new thread
82		inherits the project you were in, along with model and mode selections. Branch, worktree, and
83		environment mode always come from your configured defaults, not from the thread you were looking
84		at. To keep a worktree, use the explicit "new thread in this worktree" action in the branch
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.
	62	In the desktop app, `mod+w` closes the focused terminal or the active right-panel
	63	tab. When nothing remains to close, it closes the window. In a browser, `mod+w`
	64	closes the browser tab; rebind `rightPanel.close` and `terminal.close` to an available
	65	shortcut such as `alt+w`.
87	66
88		Background submission from a new thread is the exception. `mod+enter` starts that thread and opens
89		another new thread with the same workspace mode and base branch. New worktree remains selected,
90		but the new thread does not reuse the worktree created for the thread that just started.
	67	Many defaults include `!terminalFocus` so they do not intercept terminal input.
	68	Keep that condition when remapping them if you want the same behavior.
91	69
92	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
95		shortcut for 1.2 seconds or press it twice within 500 milliseconds. The second press quits
96		immediately. You can keep Command or Control held between presses, or release both keys.
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
	72	Use `Cmd+Q` on macOS or `Ctrl+Q` on Windows and Linux. In the default Hold mode,
	73	hold for 1.2 seconds or press twice within 500 milliseconds. Holding requires
	74	keyboard repeat; if repeat is disabled, use two presses or the application menu.
121	75
122		- Rules are evaluated in array order.
123		- For a key event, the last rule where both `key` matches and `when` evaluates to `true` wins.
124		- Precedence is across commands, not only within the same command. A later rule for a different
125		command can take a key away from an earlier one.
	76	Change Settings → General → Confirmations → Quit shortcut to Direct for a
	77	single press or Double press for two presses only. Choosing Quit from the
	78	application menu always quits immediately.

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		# 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		thread does not change any other thread. A thread created from inside another thread keeps that
7		thread's mode; otherwise new threads start in Full access unless you pick something else
8		before sending.
	6	New threads start in Full access unless you choose another mode before sending. A thread
	7	created from another thread inherits its mode.
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
13		wants to run or edit, and waits for approval. Work outside the workspace is restricted.
	16	Approve or reject requests in the conversation to let the agent continue. Permission modes do
	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
16		without prompting; commands and anything else still stop for approval.
	19	## Provider differences
17	20
18		Auto: routine actions proceed without you; risky ones still ask. How this is enforced depends
19		on the provider: Codex delegates routine approvals to an AI reviewer, Claude uses its own auto
20		permission mode, Cursor uses Smart Auto review, and providers without an equivalent (such as
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.
	21	Providers enforce permissions differently. Some read-only actions can proceed in Supervised.
	22	Auto uses automatic review on Codex, Claude, and Cursor; providers without an equivalent,
	23	including OpenCode and Antigravity, fall back to asking.
28	24
29	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.
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.
	26	actions still require approval.
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.
59		T3 Code's separate Plan mode control is not available for Antigravity. See
60		[Antigravity](./providers-antigravity.md) for setup and thread limits.
	31	See the [provider guides](./install.md#providers) for setup and provider-specific limits.

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

...	...	@@ -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
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`.
	3	Open Settings → Projects and select a project to change its preferences.
7	4
8		To choose a different icon or emoji:
	5	## Project icons
9	6
10		1. Open Settings and select Projects.
11		2. Select the project.
12		3. Next to Project icon, select Choose icon.
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.
	7	Choose an icon, emoji, or image from the project to make it easier to recognize. The choice applies
	8	to every checkout in the project group and appears on connected clients. Choose Automatic to
	9	let T3 Code detect an icon again.
23	10
24	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.
27		T3 Code checks in the background and when the server starts. It uses the branch's configured
28		upstream and only performs a fast-forward pull when the checkout has no working-tree changes,
29		untracked files, or local commits.
	13	Enable Automatically pull to keep the default-branch checkout up to date with its configured
	14	upstream.
30	15
31		The pull is skipped if the checkout is on another branch, has no upstream, or contains local work.
32		Pull failures do not prevent the server from starting.
	16	T3 Code only pulls when it can fast-forward and the checkout has no changed files, untracked files,
	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	1	# Antigravity
2	2
3		T3 Code runs Google's official Antigravity ACP agent. By default it signs in with your personal
4		Google account and uses that account's Antigravity access, including access provided by a
5		Google AI subscription. It never falls back to a different sign-in method than the one you
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.
	3	T3 Code runs Google's official Antigravity ACP agent on your selected environment.
	4	It has its own sign-in, separate from the Antigravity IDE or CLI. Google controls
	5	which models and account access are available through this agent.
11	6
12	7	## Set up Antigravity
13	8
14		On web or desktop, open Settings > Providers, select the device that runs your project,
15		then select Antigravity. Provider setup is not available in the mobile app.
16
17		1. Choose Enable Antigravity. Antigravity is off by default.
18		2. Choose Install Antigravity. T3 Code downloads the official runtime from Google to that
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.
	9	On web or desktop, open Settings > Providers, choose the environment that runs
	10	your project, and enable Antigravity. Install its runtime there, then choose
	11	Sign in with Google and complete the browser sign-in. Wait for T3 Code to confirm
	12	account access and load models before starting a thread. Provider setup is not
	13	available in the mobile app.
25	14
26		Setup requires a connection with permission to operate the environment. If setup is unavailable
27		on an older server, update that environment first.
	15	Installation continues if you leave settings or reconnect. Setup requires
	16	permission to operate the environment; update an older server if it does not offer
	17	Antigravity setup.
28	18
29	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
32		machine as the T3 Code environment, sign-in can finish directly.
	21	Google returns to a `127.0.0.1` address. It can finish directly when your browser is
	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.
35		Copy the full address from the browser, including everything after `?`, and paste it into the
36		return URL field in the web or desktop client where you started setup. Choose Continue. Do not
37		change the address to your server's hostname.
	25	Copy the full return address, including everything after `?`, into the return URL
	26	field in the web or desktop client where you started setup, then choose
	27	Continue. Keep the original address; do not replace it with the server's
	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
40		can see that sign-in is in progress, but cannot complete that attempt. The setup screen shows
41		the expiry time. If it expires, choose Retry Google sign-in and use the new link.
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.
	31	The return URL contains a temporary sign-in code. Paste it only into the setup
	32	field. A successful callback page alone does not confirm account access; wait for
	33	T3 Code's confirmation.
46	34
47	35	### Other sign-in methods
48	36
49		Sign-in method in the Antigravity provider settings on web or desktop selects how the
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. \|
	37	Choose Sign-in method in the Antigravity provider settings:
58	38
59		Gemini Enterprise resolves your license for the project and location you enter. Agent Platform
60		with a project and location uses Application Default Credentials on the environment. API keys
61		are stored in plain text in T3 Code settings on that environment and are passed only to the
62		Antigravity agent process. Ambient `GEMINI_API_KEY` or `GOOGLE_*` variables on the environment
63		are ignored.
	39	\| Method \| Credentials \|
	40	\| -------------------------- \| -------------------------------------------------------------------------------------------- \|
	41	\| Google account \| Personal Google sign-in in the browser \|
	42	\| Gemini Enterprise \| Browser sign-in, GCP project, and GCP location \|
	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
66		accounts.
	46	The Antigravity API key field is stored in plain text in settings on the
	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	52	## Runtime installation
69	53
70		Managed downloads are available for these environment hosts:
71
72		\| Host \| Architecture \|
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.
	54	Managed installation supports Apple Silicon macOS, Linux x64 or ARM64, and Windows
	55	x64 or ARM64. Intel Macs can connect to a supported remote environment. Allow
	56	several GB of free disk space, especially on Linux.
87	57
88	58	### Use a manual installation
89	59
90		Download the correct archive from the [official ACP Registry][registry] and extract both the
91		ACP executable and its `localharness_external` helper into the same directory. Keep both files
92		at the same version and make them executable on macOS or Linux. Windows uses `.exe` files.
	60	Download the archive for your environment from the [official ACP Registry][registry].
	61	Extract the ACP executable and its `localharness_external` helper into the same
	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
95		executable on the selected environment. Do not point it at the helper or the Antigravity IDE.
96
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.
	65	Set Binary path to the ACP executable on the environment and update it yourself.
	66	Leave the field blank to use the managed runtime, or a compatible executable on
	67	`PATH` if no managed runtime is installed.
101	68
102	69	## Models and threads
103	70
104		The current official ACP exposes Gemini models only. T3 Code uses the model IDs and names
105		returned for your account, including any model choices with different thinking levels. Models
106		available in other Antigravity apps might not be available through this agent.
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.
	71	The model list comes from your Antigravity account and can differ from other
	72	Antigravity apps. A resumed thread keeps its selected model. If access to that
	73	model ends, select another available model before continuing.
117	74
118		Project skills should use `.agents/skills`. T3 Code also discovers `.gemini/skills` and the legacy
119		`.agent/skills` location. When multiple locations define the same skill name, `.gemini/skills`
120		takes precedence, followed by `.agents/skills` and then `.agent/skills`.
	75	Use Antigravity's native `/plan` command for planning. T3 Code's separate Plan mode
	76	is unavailable. Tool approvals follow [Permission modes](./permission-modes.md).
	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
123		change approval with the content, so Supervised and Auto-accept edits behave the same way
124		they do for other providers. Attach images, PDFs, text files, or audio clips to a message and
125		the agent receives them directly.
	80	T3 Code keeps conversation history and file diffs, but Antigravity cannot rewind
	81	its conversation. Reverting a thread or editing and resubmitting an earlier turn
	82	is unavailable. Continue with a follow-up message or start a new thread.
126	83
127		When the agent offers Allow for this thread on a shell or web tool, T3 Code shows Google's
128		prompt injection warning next to that choice. Untrusted content could re-run the same action
129		without asking again.
	84	### Skills and attachments
130	85
131		Antigravity can ask you to choose from a fixed set of answers. Select one of the offered
132		choices. These questions do not accept custom text and still appear in Full access mode.
133		See [Permission modes](./permission-modes.md) for tool approvals.
	86	Put project skills in `.agents/skills`. T3 Code also reads `.gemini/skills` and the
	87	legacy `.agent/skills` directory. Among these project locations, the first copy
	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,
136		so reverting a thread or editing and resubmitting an earlier turn is unavailable. Send a
137		follow-up message or start a new thread instead.
	91	Antigravity accepts images, PDFs, text files, and supported audio formats directly.
	92	Its limits are 1 MiB per text file, 10 MiB per image, 20 MiB per audio clip, and
	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	97	### Subagents
140	98
141		Subagent launches appear as Antigravity subagent batch in Agents on web and desktop,
142		and in the work log on mobile. One launch can start several agents. The batch stays active
143		after launch while the parent turn runs. When that turn ends, the entry becomes idle and
144		states that individual agent status is unavailable. Launch errors remain visible.
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.
	99	Antigravity groups subagent activity into batches. You cannot open or control
	100	individual subagents, and an idle batch does not confirm that every child
	101	succeeded. See [agent work](./thread-sidebar.md#inspect-agent-work) for where to
	102	inspect activity.
152	103
153	104	## Accounts and removal
154	105
155		Each Antigravity provider instance has its own Google sign-in on its environment. Use
156		Add provider in web or desktop provider settings to create a separate instance for another
157		account. To replace an instance's account, sign out first, then sign in again.
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.
	106	Add an Antigravity provider instance for each Google account in
	107	Settings > Providers on web or desktop. Each has its own sign-in; downloaded
	108	runtimes are shared on the environment.
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
175		paid-plan tier or remaining subscription quota. See Google's [Antigravity plans][plans] and
176		[personal Google sign-in guide][google-setup].
	116	All three keep thread history and workspace files. Sending `/logout` by itself in
	117	a thread signs out its instance, including stopping that instance's other sessions.
	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
179		session succeeds. You can continue an existing thread. Antigravity checks saved Google sign-in
180		when the session starts. An unchecked status does not require signing in again.
	120	Before removing a managed runtime, disable its instances and cancel any active
	121	installation. Clear any explicit binary path pointing into that runtime. Removal
	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
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.
	124	## Check access and troubleshoot
188	125
189		The packaged runtime can be slow to start, especially on Windows. Health checks, model refresh,
190		and sign-out each allow up to 90 seconds before reporting a timeout.
	126	To check access and reload models, use Refresh provider status in web or desktop
	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
193		provider's message. A finished turn can contain an upstream error instead of completed work.
194		Use any retry time Google supplies. T3 Code does not switch to an API key to get past the limit.
	130	If Google reports `SUBSCRIPTION_REQUIRED`, an account restriction, or a usage limit,
	131	follow the provider's message and any retry time. See [Google's account plans][plans]
	132	for eligibility.
195	133
196	134	[registry]: https://github.com/agentclientprotocol/registry/blob/main/antigravity-acp/agent.json
197	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	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
4		[Codex](./providers-codex.md). For first-time setup, see [Install T3 Code](./install.md).
	3	T3 Code uses Claude Code's login and configuration. Start with the default provider
	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		- try a different Claude Code configuration without disturbing your main setup
10		- run Claude through a router such as Claude Code Router
11		- use external providers exposed through a Claude-compatible workflow
	9	Use a separate Claude config directory for each account. This also works for named
	10	presets that need different Claude settings or a router connection.
12	11
13		## I Only Use One Claude Account
14
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:
	12	Keep your existing account in the default directory. On the environment's machine,
	13	create the second login:
154	14
155	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
160		Code session for that home before using OpenRouter. Otherwise Claude Code may keep using cached
161		Anthropic credentials instead of the OpenRouter token.
	20	Add another Claude instance in Settings > Providers:
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
170		ANTHROPIC_DEFAULT_OPUS_MODEL anthropic/claude-opus-4.6
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.
	37	For presets that differ only in API keys or endpoints, use the instance's
	38	Environment variables. Variable assignments do not belong in Launch arguments.
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
183		/status
184		```
	47	You can also send `/compact` in an existing conversation. Web and desktop offer
	48	Compact context from the context meter and may suggest it when you return to
	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
189		https://openrouter.ai/api
190		```
	54	Claude skills come from the config directory's `skills` folder and the project's
	55	`.claude/skills` folder. If both define the same name, the config-directory copy
	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.
193
194		### Common OpenRouter Mistakes
195
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		```
	58	Use `$` in the composer to select a skill. Skills marked `disable-model-invocation`
	59	can still be started by you. Invoke those one per message: Claude directly runs
	60	only the last named skill and may try to start earlier ones through its Skill
	61	tool, which refuses skills reserved for manual invocation.
219	62
220		Follow the upstream project's README for the router's own install, startup, and configuration
221		steps: <https://github.com/musistudio/claude-code-router>.
	63	## OpenRouter
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"
230		- "Claude Router"
231		- "Claude Experimental"
	79	Verify requests in OpenRouter's activity dashboard. For model-role overrides and
	80	current compatibility requirements, use the
	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
234		different API keys, base URLs, or router settings, use Environment variables.
	83	## Other routers
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	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
4		[Claude](./providers-claude.md). For first-time setup, see [Install T3 Code](./install.md).
	3	For one account, use the default Codex provider with your normal Codex login.
	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		- use a personal account for personal projects
10		- switch to another account when one account hits limits
11		- keep one shared Codex history instead of maintaining two separate Codex setups
	9	A shared Codex home with a shadow home lets work and personal accounts continue
	10	the same threads. The accounts share Codex sessions and configuration while keeping
	11	their own login and available models.
12	12
13		## I Only Use One Codex Account
14
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:
	13	Keep your first account in `~/.codex`. On the environment's machine, sign the
	14	second account into a fresh directory:
107	15
108	16	```bash
109		mkdir -p ~/.codex_p
110		CODEX_HOME=~/.codex_p 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
	17	mkdir -p ~/.codex_personal
	18	CODEX_HOME=~/.codex_personal codex login
119	19	```
120	20
121		The important part is that both providers use the same `CODEX_HOME path`, but only the second one
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.
	21	Then add a second Codex instance in Settings > Providers:
136	22
137		This is useful when a Codex-compatible setup needs account-specific variables. Add the variables to
138		the provider instance that should receive them, and mark API keys or tokens as sensitive. Sensitive
139		values are stored as server secrets and are not sent back to the app after saving.
	23	\| Instance \| CODEX_HOME path \| Shadow home path \|
	24	\| -------------- \| --------------- \| ------------------- \|
	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
148		Codex Work CODEX_HOME path: ~/.codex
149		Codex Personal CODEX_HOME path: ~/.codex, Shadow home path: ~/.codex_p
150		```
	40	## Switch accounts in an existing thread
151	41
152		Those two providers are considered compatible for continuation, so the locked model picker can show
153		both.
	42	Choose the other account from the thread's model picker. T3 Code offers compatible
	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
156		as a different workspace. It will not be offered for existing threads created under `~/.codex`.
	46	If the account is missing from the picker, compare the home paths in provider
	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.
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`.
	59	## Approve app access
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
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.
	66	## Send feedback to OpenAI
177	67
178		That means separate sessions and less account switching inside old threads. Most dual-account users
179		should use the shared-home plus shadow-home setup instead.
	68	In an existing Codex thread, send `/feedback` with an optional description, for
	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	1	# OpenCode
2	2
3		T3 Code uses the OpenCode setup on the connected environment. With a remote environment, its
4		OpenCode login and configuration apply, not the setup on your desktop or phone.
	3	Install and authenticate OpenCode on the machine running your environment, then
	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
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.
	8	## Local or external server
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
13		`OPENCODE_SERVER_PASSWORD` from the environment. A password in the provider settings overrides
14		that environment value for both the local process and T3 Code.
	15	To use an existing OpenCode server, set Server URL and its password in provider
	16	settings. T3 Code uses only that configured password for an external server; it
	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
17		provider settings. It does not send a local `OPENCODE_SERVER_PASSWORD` to an external server.
18		OpenCode uses this password for HTTP Basic authentication.
	20	After a lost connection, send another prompt to reconnect to the same OpenCode
	21	session.
19	22
20	23	## Approvals
21	24
22		In Supervised and Auto modes, OpenCode can read normal project files, search files, load
23		skills, and update its task list without approval. Files such as `.env` and `.env.local` still
24		require approval. `.env.example` does not. OpenCode does not have an AI approval reviewer, so
25		Auto uses the same permission rules as Supervised.
	25	OpenCode follows the shared [permission modes](./permission-modes.md). Auto has
	26	the same rules as Supervised because OpenCode has no AI approval reviewer.
	27	Environment files such as `.env` and `.env.local` need approval in restricted
	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
28		outside the workspace. Auto-accept edits also permits file edits without approval.
29		Full access permits all these actions. Questions that need your answer can still appear.
	30	Allow for workspace applies to matching requests in other OpenCode sessions
	31	using the same workspace. It is broader than the current thread, especially on a
	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
32		choose one of these options:
	35	## Refresh models, commands, and skills
33	36
34		- Allow once permits this request.
35		- Allow for workspace permits matching requests in other OpenCode sessions in the same
36		workspace. It is not limited to the current thread.
37		- Deny rejects this request. Use Stop to stop the whole turn.
	37	After changing an OpenCode login or configuration, use Refresh provider status
	38	in Settings > Providers for that environment. On mobile, use Refresh models
	39	in the thread settings. Reconnecting also refreshes the catalog; periodic provider
	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
42
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.
	48	Existing threads keep their selected model and options even when it disappears
	49	from the catalog. If OpenCode rejects that model, select an available one and retry.

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

...	...	@@ -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
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. \|
	6	## T3 Connect
25	7
26		Authorization and other permanent 4xx rejections stop the startup link attempt immediately.
27		After correcting them, restart the server. For the Linux background service, use
28		`systemctl --user restart t3code.service`; for a foreground server, stop it and run `t3 serve` again.
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.
	8	T3 Connect makes an environment available to your other devices without setting
	9	up router forwarding. In the desktop app on the host, open **Settings →
	10	Connections, sign in, and enable T3 Connect** for that environment.
31	11
32		## Quick Pairing for a Running Server
33
34		If a server is already running on this machine, mint a fresh pairing token and QR code without restarting anything:
	12	For a command-line host, run:
35	13
36	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.
41
42		If the server is only bound to loopback, the printed URL is not reachable from another device. Pair over your tailnet instead:
43
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
	18	Follow the sign-in instructions. Setup offers a
	19	[background service](./background-service.md); if you decline it, start the
	20	server with `npx t3 serve`. Saving your sign-in alone does not make the machine
	21	reachable.
63	22
64		There are three ways to reach your server from another device: expose the desktop app's backend,
65		run a headless server from the CLI, or have the desktop app launch T3 Code over SSH.
	23	On your other device, sign in to the same T3 Connect account and choose the
	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.
72		2. Under This environment, toggle Network access on. This will restart the app and run the backend on all network interfaces.
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.
74		4. Use Create Link to generate a pairing link you can share with another device.
	31	On a desktop host, open Settings → Connections, enable Network access,
	32	then create a pairing link using an address the other device can reach. Changing
	33	network access restarts the desktop app. You can turn it off in the same place.
75	34
76		Pairing codes and share links are available only in the client that created them,
77		while its Connections page remains open. After you leave the page or reload it,
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`.
	35	For a command-line host, replace `<private-ip>` with the host's LAN or tailnet
	36	address:
124	37
125	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:
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:
	42	If a server is already running, generate a fresh link without restarting it:
146	43
147	44	```bash
148		npx t3 serve --tailscale-serve
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
	45	npx t3 pair
156	46	```
157	47
158		Once paired, add projects normally: open the Command Palette and choose Add Project, then pick
159		the environment the project lives on. Every saved environment is offered, not only the local one.
	48	Scan the QR code on your phone or paste the pairing URL into Add environment
	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.
166		2. Under Remote Environments, choose Add environment.
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.
	61	Join both devices to the same tailnet. In the desktop app, enable **Tailscale
	62	HTTPS in Settings → Connections**. Turn it off there to remove that route.
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.
174
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
	66	```bash
	67	npx t3 serve --tailscale-serve
183	68	```
184	69
185		During SSH launch, T3 Code first checks whether `node` is on `PATH`. If it is missing, the launcher
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:
	70	For an already-running server:
191	71
192	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	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
209		it and sign in from a remote web or desktop client without an SSH login.
	93	For a plain HTTP LAN endpoint, use the direct pairing URL in a browser that can
	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.
212		Provider setup is not available in the mobile app.
	97	## Desktop-managed SSH
213	98
214		After Google sign-in, a remote browser usually reaches a `127.0.0.1` page that cannot load.
215		Copy that full address into the return URL field in the same T3 Code client and choose
216		Continue. Keep the address unchanged. Do not paste the return URL into a thread or bug report.
	99	In the desktop app, open Settings → Connections → Add environment, choose
	100	SSH, and enter a host or SSH alias such as `user@example.com`. T3 Code starts
	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
221
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
	108	```bash
	109	ssh user@example.com 'sh -lc "command -v node && node --version"'
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
268		- inspect active sessions
269		- revoke old pairing links or sessions
	135	On a command-line host, `t3 connect unlink` disables exposure while retaining
	136	your login; `t3 connect logout` also clears that login. Background-service
	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
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
	142	## T3 Connect troubleshooting
285	143
286		- Treat pairing URLs and pairing tokens like passwords.
287		- Prefer binding `--host` to a trusted private address, such as a Tailnet IP, instead of exposing the server broadly.
288		- Anyone with a valid pairing credential can create a session until that credential expires or is revoked.
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.
290		- Use `t3 auth` to revoke credentials or sessions you no longer trust.
	144	Run `t3 connect status` on the host to inspect saved authorization and link
	145	configuration. It is not a live reachability check. If the environment appears
	146	offline, run `t3 service status` and read the displayed log. If it disappears
	147	when SSH closes, see [background-service troubleshooting](./background-service.md#troubleshooting).
	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		# Source Control Integrations
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.
4
5		## Supported Providers
6
7		T3 Code works with the platforms your team already uses:
8
9		- GitHub – Pull requests, repository creation, and clone integration
10		- GitLab – Merge requests, repository publishing, and hosted clones
11		- Bitbucket – Pull request workflows (via API token authentication)
12		- Azure DevOps – Pull request support for Microsoft-hosted repositories
13
14		## What You Can Do
15
16		### Start Projects from Anywhere
17
18		Clone repositories directly
19
20		- Open the Command Palette (`Cmd/Ctrl + K`) → Add Project
21		- Choose GitHub repository, GitLab repository, Bitbucket repository, Azure DevOps repository, or paste any Git URL
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
23
24		Publish local projects to the cloud
25
26		- Have a local Git repository without a remote?
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
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.
29
30		### Manage Code Reviews Without Context Switching
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:
	1	# Source control
	2
	3	T3 Code integrates with GitHub, GitLab, Bitbucket, and Azure DevOps to clone and publish
	4	repositories, create pull requests, and review changes.
	5
	6	## Connect an account
	7
	8	Install Git and configure authentication on the machine running your T3 Code server. For a remote
	9	environment, do this on the remote machine. After signing in, open Settings → Source Control
	10	and choose Rescan.
	11
	12	### GitHub
	13
	14	Install [GitHub CLI](https://cli.github.com/) 2.81.0 or newer, then sign in:
	15
	16	```bash
	17	gh auth login
	18	```
	19
	20	### GitLab
	21
	22	Install [GitLab CLI](https://gitlab.com/gitlab-org/cli), then sign in:
	23
	24	```bash
	25	glab auth login
	26	```
	27
	28	### Bitbucket
	29
	30	Set an access token in the server's environment:
130	31
131	32	```bash
132	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
136		repositories, plus read access to your user account (`read:user:bitbucket`, used to verify the
137		connection):
	36	Or use an Atlassian account email and API token with read/write access to repositories and pull
	37	requests, plus user read access (`read:user:bitbucket`):
138	38
139	39	```bash
140	40	export T3CODE_BITBUCKET_EMAIL="you@example.com"
141	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
145		Control settings**.
	44	The access token takes precedence if both are configured. Restart the server after changing these
	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:
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		```
	65	## Create a pull request
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
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
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)
	82	For Azure DevOps, use the host website to view diffs or change comments. Bitbucket does not support
	83	reopening a declined pull request.
176	84
177		Need more help? Check your provider's CLI documentation:
	85	## Troubleshooting
178	86
179		- [GitHub CLI](https://cli.github.com/)
180		- [GitLab CLI](https://gitlab.com/gitlab-org/cli)
181		- [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/)
	87	- Not authenticated: run the provider's login command on the server, then rescan. For Bitbucket,
	88	confirm the running server received the environment variables.
	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		# Anonymous usage data
	1	# Product usage data
2	2
3		The T3 server sends anonymous product events to PostHog. These events include
4		the provider, model, reasoning effort, permission mode, turn result, duration,
5		and normalized main-agent token totals when the provider reports them.
	3	The T3 Code server sends product usage events to PostHog, associated with a hashed account or
	4	installation identifier. Events include the provider, model, reasoning effort, permission mode,
	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,
8		thread IDs, turn IDs, provider instance IDs, authentication tokens, or child
9		agent output. Token totals can be complete, partial, or unavailable. Child
10		agent token use is not included.
	7	Events do not include prompts, responses, file contents, authentication tokens, conversation IDs,
	8	raw provider events, or child-agent output. Child-agent token use is excluded from the totals.
11	9
12		Set `T3CODE_TELEMETRY_ENABLED=false` before you start the T3 server to stop
13		product events from being recorded or sent. The server still derives an
14		anonymous identifier during startup and can create its local fallback
15		identifier file.
	10	To disable collection, set `T3CODE_TELEMETRY_ENABLED=false` in the server's environment before
	11	starting it. This stops product events from being recorded or sent.

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

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

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		# 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
4		version. If they do not match, T3 Code shows a warning with the right update option for that server.
	3	The app you use and the server running your agents can be on different machines.
	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
11		- Settings → Connections, beside the affected connection
	13	Settings → General → Continue threads after server updates is off by default.
	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
14		update the server, and the version difference remains visible in Connections.
	17	## Update a connected server
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
19		has a Continue threads after server updates preference. It is off by default. When enabled, the
20		update buttons automatically resume supported provider threads after the replacement server is
21		ready. Providers with native promptless continuation use it; other providers receive a short
22		instruction to continue where they left off. Terminal commands and other running work may still be
23		interrupted during the update.
	21	\| Action \| What to do \|
	22	\| -------------------------- \| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- \|
	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. \|
	24	\| Update the desktop app \| Update the desktop app on the machine running the server, then reopen it if needed. \|
	25	\| Copy update command \| Stop the command-line server on its host and relaunch with the copied command, keeping your usual startup options. \|
24	26
25		The update does not remove saved threads, settings, or project files.
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:
	27	For a background service, run the matching version's CLI on the host:
52	28
53	29	```sh
54	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`
58		only resolves the skew when your client happens to be on the latest release. The exact version from
59		the warning always works.
60
61		See [Running T3 Code in the Background](./background-service.md) for install, status, and removal
62		commands.
63
64		## Nightly desktop release notes
	33	Replace `<client-version>` with the version shown in the notice. Using
	34	`@latest` only resolves the mismatch if your client is on that release. An older
	35	service launcher may require this local update before it supports remote updates
	36	and rollback.
65	37
66		The desktop app shows a compact release-notes preview when a nightly update is available. Changes
67		appear newest first within each release. Each release links to its exact page on GitHub, even when
68		all changes fit in the preview.
	38	For a foreground server, the copied command is `npx t3@<client-version>`. Add
	39	`serve` if you normally run without a browser, and preserve options such as
	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
71		releases, it shows the exact number and links to the rest. Contributor credits do not count as
72		changes.
	43	## If an update fails
73	44
74		## After the Update
75
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:
	45	Keep the client open until it reconnects or reports a failure. A failed service
	46	update can roll back to the previous version. If the update still fails:
81	47
82	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.
84		3. For a command-line server, relaunch it with `npx t3@<client-version>`, replacing
85		`<client-version>` with the client version shown in the warning.
86
87		## The Mobile App
	49	2. Check that you updated the server's machine, not only the device you are using.
	50	3. For a command-line server, stop it and relaunch the exact version shown in the notice.
88	51
89		The mobile app keeps itself current on its own. When it finds a new version, it downloads it in the
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.
	52	## Mobile updates
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		# Review usage
2
3		The Usage page combines Codex, Claude Code, and Grok Build activity from your connected
4		environments. It reads the providers' local session history and shows API-equivalent token cost,
5		processed tokens, cache savings, provider shares, and model breakdowns. Subscription billing is
6		separate from the raw token cost shown here.
7
8		Grok Build totals come from persisted session updates. Interactive turns that never wrote a
9		completed-turn record will not appear.
10
11		The Limits view shows how much of each subscription window you have used on Codex and Claude
12		Code, per connected environment: the session and weekly windows, plus a per-model weekly window
13		such as Fable when your plan has one. Each window is a bar from the moment it opened to its reset,
14		filled by the share of quota spent; a thin line marks how far into the window you are, which is
15		also where even spending would have put the fill, and the icon beside the label says whether you
16		are ahead of, on, or under that pace. Hover a bar for the exact reset time. Limits refresh on the
17		provider health-check interval and update live while a turn runs. API-key accounts have no
18		subscription windows and say so; that includes a Claude Code that reaches Anthropic through a proxy
19		via `ANTHROPIC_AUTH_TOKEN`, since the CLI then treats itself as an API-key client.
20
21		If you pool accounts behind a CLIProxyAPI hub, open Settings → Providers → Usage providers
22		and choose Add hub. Select the device that should connect to the hub; its accounts appear on
23		the Limits view. Remove hubs from the same settings section. Each limits row shows its provider
24		and instance name, or a small _CLI Proxy_ label for
25		hub accounts. When a connected provider reports limits for the same provider and email, its row
26		replaces the hub copy, keeping details such as banked reset credits. The hub copy remains visible
27		if the connected provider cannot report limits. Enter the hub's URL and management key; the key
28		is stored on the server and never sent back to a client. Emails are blurred until clicked, as in
29		provider settings.
30
31		Use Past 24h for an hourly chart covering the exact rolling 24-hour period. The 7 days,
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.
	1	# Usage and limits
	2
	3	## Understand your usage
	4
	5	Usage combines Codex, Claude Code, and Grok Build session history from your connected
	6	environments. It shows token use, cache savings, model breakdowns, and estimated API-equivalent
	7	cost. These estimates are not your subscription bill.
	8
	9	Totals depend on the history available on each server. Grok turns without a saved completed-turn
	10	record are missing from the totals.
	11
	12	If recent work is missing or a new model shows no cost, refresh to rescan session history and
	13	update model pricing.
	14
	15	## Track subscription limits
	16
	17	Usage → Limits shows quota use and reset times for Codex and Claude subscriptions. It also
	18	compares quota consumed with time elapsed in each window, so you can judge your pace before the
	19	next reset.
	20
	21	API-key accounts may not report subscription limits. This also applies to Claude connections
	22	using a proxy through `ANTHROPIC_AUTH_TOKEN`.
	23
	24	## Connect a CLIProxyAPI hub
	25
	26	To see pooled accounts, open Settings → Providers → Usage providers → Add hub. Choose the
	27	environment that will connect to the hub and enter its URL and management key.
	28
	29	The accounts appear under Usage → Limits. This connection supplies usage information; configure
	30	the provider separately to send agent requests through the hub. Remove the hub from the same
	31	settings section when you no longer need it.