docs(mobile): record agent conventions for tests, variants, and file modules

[juliusmarminge]

The problem

apps/mobile has no AGENTS.md (the repository root has the only one, and CLAUDE.md is just @AGENTS.md), so agents relearn the same small mobile conventions from scratch: the Node-environment test setup and vi.mock pattern, the @effect/vitest / vite-plus/test split, Platform.OS vs file-variant divergence, naming, relative imports, and the pnpm file: module reinstall gotcha.

The fix

A short, factual apps/mobile/AGENTS.md. This is now an ordinary single-commit PR against current main (68607c5); #13150 was closed unmerged, so all renderer/test-host guidance was removed and every statement was re-verified against origin/main:

• Tests: vp test run uses the repository-root Vitest config (test.environment: "node"; focused runs report environment 0ms). On main, 33 files under src import @effect/vitest (13 mixing it with vite-plus/test for vi), 160 use vite-plus/test, and only the standalone .mjs config-plugin test under plugins/ imports vitest. The vi.hoisted + vi.mock + import-under-test-after pattern matches existing files. The two .test.tsx files under src render via renderToStaticMarkup with react-native mocked — recorded as what exists, and the doc says to follow a local modules/* package's own setup there (e.g. react-dom/client + DOM shims in t3-markdown-text).
• Platform divergence: styling differences use Platform.OS className branches. Uniwind ios:/android: class variants are documented as must-not-use: unguarded in this repo's Metro pipeline (Android classes apply on iOS and vice versa); revert(mobile): git sheets back to Platform.OS ternaries (un-guarded uniwind variants broke both platforms) #13169 reverted refactor(mobile): git sheets use uniwind platform variants instead of className ternaries #13161 (ec28eefa0d0) for exactly this reason, and the ban stands until the pipeline is fixed/upgraded and platform isolation is proved on both devices. Verified on current main: the revert removed the git-sheet usages, but a few remain in src (settings rows/screens, NewTaskDraftScreen, worktree-setup-card); the doc states they still leak, need remediation, and no more should be added. Behavior differences branch on Platform.OS; file variants (.ios/.android/.native over the extensionless base, Name.shared.tsx re-export per AndroidHomeFab) for wholesale UI differences.
• Naming: 28 *RouteScreen.tsx files, PascalCase components vs kebab-case logic modules; hook files split roughly evenly between useCamelCase.ts and use-kebab-case.ts, so the doc says to match the surrounding directory.
• Imports: no @/ alias or baseUrl in apps/mobile/tsconfig.json (zero @/ imports in src); @t3tools/client-runtime has no root export and a root lint rule (RESTRICTED_IMPORT_PATHS in vite.config.ts) forces explicit subpaths.
• file: modules: restates the existing explanation in docs/internals/mobile-development.md (pnpm copies modules/*; edit → vp i before Metro sees it) instead of re-deriving it.

The earlier docs/internals/mobile-navigation.md audit item did not reproduce: all six links and the README.md#development anchor resolve on main, the three cited Swift media-presentation files exist under t3-native-controls/ios/ (which is where the AVKit/Quick Look implementations live; t3-markdown-text has no Swift at all), so that file is unchanged.

No runtime code touched. Screenshots n/a (docs only).

Verification

• vp test run src/features/home/thread-dismissal.test.ts → 4 passed (environment 0ms, confirming the documented Node environment)
• vp test run src/native/voiceTranscription.ios.test.ts → 4 passed (confirms the platform-variant test convention)
• Docs-only change; commit hooks ran vp fmt clean.

Model: callstack/Apex via pi (T3 Code).

---

Summary by CodeRabbit

• Documentation
  • Added mobile development guidance covering testing, native-module mocking, platform-specific styling, naming conventions, linting, typechecking, and local module reinstall requirements.

[macroscopeapp]

Approvability

Verdict: Approved at 8593dee

Macroscope's review found this PR approvable — This PR adds a single mobile-scoped agent-conventions document and does not modify executable code, configuration, product defaults, or static-analysis behavior. Its impact is limited to development guidance, with no direct production runtime or deployment risk.

^{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: 30d788bd-e114-443d-b96d-be82128095bd

📥 Commits

Reviewing files that changed from the base of the PR and between a493946 and 8593dee.

📒 Files selected for processing (1)

• apps/mobile/AGENTS.md

Included review availability: Your plan provides up to 10 included reviews per hour; 2 remain after this review.

---

📝 Walkthrough

Walkthrough

Added apps/mobile/AGENTS.md with guidance for mobile testing, platform-specific code, naming, imports, validation commands, and local file: module workflows.

Changes

Mobile Development Guidance

Layer / File(s)	Summary
Mobile development rules apps/mobile/AGENTS.md	Documents mobile test harnesses, native and Expo module mocking, component tests, platform variants, typechecking and linting, styling rules, naming conventions, import rules, and local module reinstall requirements.

Priority: ⬇️ Low

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

Change: Other

Merge Risk: ⚪ Minimal · up to 8593d

The PR adds mobile development guidance without changing runtime behavior, so it is mergeable.

🚥 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 mobile agent conventions for tests, platform variants, and file modules.
Description check	✅ Passed	The description explains the problem, the documentation changes, verification steps, and that no runtime code or UI changed. It does not use the template headings or include 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 0…
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 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	+3 B (+0.0%)	15.1 KiB	✅
Codex	Thread snapshot wire	7.0 KiB	7.1 KiB	+2 B (+0.0%)	7.3 KiB	✅
Codex	Live turn WebSocket wire	6.5 KiB	6.5 KiB	+1 B (+0.0%)	7.8 KiB	✅
Codex	Live turn WebSocket decoded	56.3 KiB	56.3 KiB	0 B (0.0%)	66.4 KiB	✅
Codex	Live turn messages	10	10	0 (0.0%)	21	✅
Claude	Total thread wire	13.5 KiB	13.5 KiB	+2 B (+0.0%)	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	+6 B (+0.1%)	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: a493946 · PR result: 8593dee · 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.