Sign up
View stargazers13Sign up

docs: focus user guides on features and workflows#9756

merged2
trim-internal-documentation
trim-user-documentation
openedSep 4, 2026byJJulius Marminge
23 files changed
View on GitHubTwo-way sync enabledPR last imported 5d ago

User guides had accumulated descriptions of visible controls, layouts, and individual UI states. Rewrites them around major features, how to get started, and behavior that needs explanation.

Keeps practical provider setup, account switching, remote access, permissions, and troubleshooting. Combines the theme guides, folds tool activity into working with threads, and updates the guide index. User documentation shrinks from 18,084 to 8,570 words, a 53% reduction.

Builds on the documentation policy and internal-guide overhaul in #9755.

Verification:

  • Retained guidance checked against the implementation.
  • Checked 94 local links and anchors, all 19 guides in the index, and three JSON examples against this layer's tree.
  • Scoped formatting and whitespace checks passed.
  • Documentation only; no visual changes requiring screenshots.

Model: GPT-6. Harness: Codex.

Note

Rework user guides around features and workflows

Macroscope summarized d6d517b.

Note

Low Risk Markdown-only changes with no runtime impact; main risk is users missing formerly documented UI behaviors after the trim.

Overview Documentation-only overhaul of the user guide set: prose is shortened (~53%) and reorganized around tasks and workflows instead of control-by-control UI walkthroughs.

Index and navigation: docs/README.md gets a fuller user-guide TOC (composer, threads, appearance, browser import, Antigravity in provider list). Root README.md link labels are tweaked (e.g. project settings, background service on all platforms).

Merged or removed pages: environment-theme.md and mobile-appearance.md are replaced by appearance.md (custom themes, environment themes, t3 theme CLI). tool-activity.md is removed; inspecting tool output is covered briefly under Working with threads. composer.md is retitled Messages and context with shorter sections; detailed composer UI behavior is cut.

Guide rewrites: Install, remote access, background service, source control, keybindings, permission modes, updating, usage, telemetry, browser import, and project settings are condensed (more tables, fewer edge-case paragraphs). Provider guides (Codex, Claude, OpenCode, Antigravity) keep multi-account and setup flows but drop long UI narratives.

Telemetry copy now describes hashed account/installation identifiers and clarifies opt-out via T3CODE_TELEMETRY_ENABLED=false.

Reviewers should spot-check that intentionally dropped topics (e.g. sidebar draft indicators, panel motion, proactive PR panels) are acceptable omissions or documented elsewhere.

Reviewed by Cursor Bugbot for commit d6d517bc61e0fffee88bac041cbdb0f5a6716e75. Bugbot is set up for automated code reviews on this repo. Configure here.

Ggithub-actionsBotSep 4, 2026
Synced from GitHub

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

ℹ️ No successful main baseline artifact is available yet. This run establishes the initial measurement.

ProviderMetricMain baselineThis PRImpactPR ceiling
CodexTotal thread wire—13.6 KiB—15.1 KiB✅
CodexThread snapshot wire—7.0 KiB—7.3 KiB✅
CodexLive turn WebSocket wire—6.5 KiB—7.8 KiB✅
CodexLive turn WebSocket decoded—57.0 KiB—66.4 KiB✅
CodexLive turn messages—9—21✅
ClaudeTotal thread wire—13.6 KiB—15.1 KiB✅
ClaudeThread snapshot wire—7.0 KiB—7.3 KiB✅
ClaudeLive turn WebSocket wire—6.5 KiB—7.8 KiB✅
ClaudeLive turn WebSocket decoded—57.8 KiB—66.4 KiB✅
ClaudeLive turn messages—9—21✅

Baseline: unavailable · PR result: d6d517b · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

  • Codex decoded thread snapshot: 113.8 KiB
  • Claude decoded thread snapshot: 114.5 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.

docs/user/providers-antigravity.mdlines 65–67Outdated · b55ac69Open thread
……@@ -1,198 +1,135 @@
100-installations. Clear **Binary path** to use managed installation controls.
65+Set **Binary path** to the ACP executable on the environment. This overrides
66+managed installation, so update the manual installation yourself. Clear the path
67+to return to managed installation.
MmacroscopeappBoton lines 65–67Sep 4, 2026

🟡 Medium user/providers-antigravity.md:65

Clearing Binary path does not always return to the managed installation: when no managed release is installed, resolution falls through to a matching executable on PATH, so users can silently run an unmanaged runtime. Document this fallback so clearing the field does not imply the managed runtime will be used.

✅ Resolved in 43a6ecf8d92200dd65b3fd1bfcfa52980f865389

JJulius MarmingeSep 4, 2026

Fixed in 43a6ecf. Leaving Binary path blank now explicitly uses the managed runtime when installed, or a compatible executable on PATH otherwise. Verified against AntigravityInstallation.resolve and its existing path-resolution test.

docs/user/keybindings.mdlines 20–21Outdated · b55ac69Open thread
……@@ -17,109 +16,63 @@ The file is a JSON array of rules.
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 or take a shortcut already
21+used in the same context.
MmacroscopeappBoton lines 20–21Sep 4, 2026

🟡 Medium user/keybindings.md:20

A newly added default can override a user's existing shortcut after an upgrade when their when expressions overlap but are not textually identical. Conflict detection compares raw when strings, so a user rule for mod+x without when and a later default for mod+x with when: "!terminalFocus" both apply when the terminal is unfocused, and the default wins. Document this limitation instead of claiming such shortcuts are never taken.

suggestion
1New defaults do not replace commands you customized, but overlapping `when` expressions can still let a later default take a shortcut in some contexts.
🚀 Reply "fix it for me" or copy this AI Prompt for your agent:
text
1In file @docs/user/keybindings.md around lines 20-21:
2
3A newly added default can override a user's existing shortcut after an upgrade when their `when` expressions overlap but are not textually identical. Conflict detection compares raw `when` strings, so a user rule for `mod+x` without `when` and a later default for `mod+x` with `when: "!terminalFocus"` both apply when the terminal is unfocused, and the default wins. Document this limitation instead of claiming such shortcuts are never taken.
JJulius MarmingeSep 4, 2026

Fixed in 43a6ecf. The guide now explains that new defaults can overlap custom shortcuts and links to rule precedence. Verified the startup append order and last-matching-rule resolution.

MmacroscopeappBotSep 4, 2026
Synced from GitHub

Approvability

Verdict: Approved at d6d517b

Macroscope's review found this PR approvable — This PR only reorganizes, condenses, adds, and removes Markdown user guides; it does not modify application code, configuration, product defaults, or deployment behavior. Its broad diff is documentation content rather than runtime complexity or risk.

You can add or adjust custom eligibility rules. Learn more.

Added 2 commits

  • docs: focus user guides on features and workflows8ec6a67
  • docs: clarify runtime and shortcut behaviord6d517b