docs(mobile): document the two mobile routes that intentionally skip deep links

[juliusmarminge]

Problem

A route-coverage audit in apps/mobile found SettingsUsageAccount and ThreadSettingsSheet as the only two static screens (of 57) with no linking: path in Stack.tsx. Every other screen has one, and the root NotFound wildcard (linking: "*") sends any unknown deep link there — so the omission read as an oversight. After inspecting the actual navigation for both, the omissions are correct and adding paths would create fake, broken links. This PR records the decision at the call sites.

Why each route should not have a deep-link path

ThreadSettingsSheet (ExistingThreadSettingsRouteScreen) — the route carries zero params; its entire content is a session object (staged model selection, provider groups, and live update callbacks like onSelectModel → props.onUpdateModelSelection) that the active ThreadComposer presents into ExistingThreadSettingsRouteProvider immediately before pushing the route (ThreadComposer.tsx: settingsRoutePresentation.present(settingsRouteSession) then StackActions.push("ThreadSettingsSheet")). None of that is URL-constructible. Reached without a presented session, the screen's own code path is navigation.goBack() — a hypothetical deep link would flash and self-dismiss. It is also listed in WORKSPACE_OVERLAY_ROUTES, so it must never describe a workspace location. Thread deep links land on threads/:environmentId/:threadId, where the sheet is one tap away. This differs from the new-task flow's draft/settings sheet, whose state comes from NewTaskFlowProvider mounted in that navigator's own layout and is therefore reachable from navigation state.

SettingsUsageAccount (UsageLimitAccountScreen) — its params are a tap-time snapshot of live usage state, not a stable resource address: now is the wall-clock of the tap, environmentIds is the usage screen's local filter selection (nullable array), and windowId/windowKind identify freshly aggregated pools (PoolWindowCard.openAccount in UsageLimitsPooled.tsx). React Navigation round-trips non-path params through the URL as query strings (getPathFromState/getStateFromPath in @react-navigation/core 7.21.13, with no type parsing wired into the static config), so any declared path would bake a permanently stale timestamp and filter into a "stable" URL — and the screen's own "This account is no longer reporting limits…" fallback would become the normal landing. Nothing produces such a link: the only deep-link producers are notification payloads (/threads/...), app shortcuts, and incoming shares. The linkable surface is the list at settings/usage, which already exists and rebuilds this state fresh.

Change

Comments on the two createNativeStackScreen entries in apps/mobile/src/Stack.tsx documenting the invariant: these are the two routes that intentionally omit linking:, and why. No behavior, contract, or path-config change — a fake path is worse than NotFound because it silently lands on a screen that either dismisses itself or renders with stale snapshot params.

Verification

• tsc --noEmit in apps/mobile: clean.
• vp lint apps/mobile/src/Stack.tsx: clean.
• No visual or behavioral change, so before/after screenshots are not applicable; the evidence is the source reasoning above. No tests added — the change adds no behavior, and the repo guidelines call for tests of meaningful logic, not comment mirrors.

Created with callstack/Apex in the Pi harness.

---

Summary by CodeRabbit

• Documentation
  • Clarified that certain settings screens cannot be opened directly through deep links.
  • Deep links continue to target the corresponding parent usage or thread screens instead.

[macroscopeapp]

Approvability

Verdict: Approved at fab6a44

Macroscope's review found this PR approvable — Only explanatory comments were added to the existing mobile route definitions. No executable code, navigation behavior, defaults, or configuration changed.

^{You can add or adjust custom eligibility rules. Learn more.}

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository: pingdotgg/t3code/.coderabbit.yaml

Review profile: CHILL

Plan: Team

Run ID: b5063e23-cec4-40a4-9080-86566a8bc76c

📥 Commits

Reviewing files that changed from the base of the PR and between 242816a and fab6a44.

📒 Files selected for processing (1)

• apps/mobile/src/Stack.tsx

Limit details: You’ve used all 10 included reviews currently available.

---

📝 Walkthrough

Walkthrough

Changes

Mobile linking documentation

Layer / File(s)	Summary
Non-deep-linkable route documentation apps/mobile/src/Stack.tsx	Documents why SettingsUsageAccount and ThreadSettingsSheet have no linking paths, and identifies their supported parent or thread deep links.

Priority: ⬇️ Low

Estimated code review effort: 1 (Trivial) | ~2 minutes

Change: Other

Suggested reviewers: chrisdeeming

Merge Risk: ⚪ Minimal · up to fab6a

No actionable merge risk remains; the documented deep-linking rationale is behavior-neutral.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: documenting the two mobile routes that intentionally omit deep-link paths.
Description check	✅ Passed	The description explains the problem, the rationale for both routes, the exact code change, and verification results. It does not use the template headings exactly and omits the checklist, but it prov…
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 1…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	13.5 KiB	13.5 KiB	−42 B (−0.3%)	15.1 KiB	✅
Codex	Thread snapshot wire	7.1 KiB	7.1 KiB	+6 B (+0.1%)	7.3 KiB	✅
Codex	Live turn WebSocket wire	6.5 KiB	6.4 KiB	−48 B (−0.7%)	7.8 KiB	✅
Codex	Live turn WebSocket decoded	56.3 KiB	56.2 KiB	−44 B (−0.1%)	66.4 KiB	✅
Codex	Live turn messages	10	9	−1 (−10.0%)	21	✅
Claude	Total thread wire	13.5 KiB	13.5 KiB	+7 B (+0.1%)	15.1 KiB	✅
Claude	Thread snapshot wire	7.1 KiB	7.1 KiB	+4 B (+0.1%)	7.3 KiB	✅
Claude	Live turn WebSocket wire	6.4 KiB	6.4 KiB	+3 B (+0.0%)	7.8 KiB	✅
Claude	Live turn WebSocket decoded	57.0 KiB	57.0 KiB	0 B (0.0%)	66.4 KiB	✅
Claude	Live turn messages	9	9	0 (0.0%)	21	✅

Baseline: 242816a · PR result: fab6a44 · 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: 114.0 KiB
• Claude decoded thread snapshot: 114.6 KiB

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