docs(web): add AGENTS.md — stack, commands, routing conventions, migration rules

[ashleeradka]

Prompt / plan

Add apps/web/AGENTS.md — a thin reference file that gives agents the essential context they need (stack, commands, routing conventions, migration rules) without duplicating the comprehensive CONVENTIONS.md and STYLE_GUIDE.md already on main.

What this adds

• Conventions pointers — directs agents to read CONVENTIONS.md and STYLE_GUIDE.md before making changes
• Stack summary — Vite, React 19, React Router v7 (data mode via createBrowserRouter), Zustand, TanStack Query, Tailwind CSS v4, Capacitor
• Routing conventions — documents the no-basename architecture: /account/* (auth pages, no app chrome) and /assistant/* (chat app with RootLayout → ChatLayout) as explicit top-level branches
• Dev commands — install, dev server, codegen, typecheck, lint, build, test
• Migration rules — faithful copy (not stubs), convention compliance on arrival, no marketing/admin pages

What this does NOT do

• Does not duplicate architectural conventions already in CONVENTIONS.md
• Does not duplicate style rules already in STYLE_GUIDE.md
• Does not conflict with the lib/ and cross-domain import conventions in those files

Dependency

Merge PR #31141 first. The routing section documents the post-#31141 architecture (no basename, /account/* and /assistant/* as explicit top-level branches). On main today, routes.tsx still uses basename: "/assistant".

Test plan

• Read-only documentation change
• Verified links point to correct files
• CI passes (lint, typecheck, build)

References

• React Router v7 data mode — documents the distinction between data mode (createBrowserRouter) and framework mode
• Vite dev server — build tool reference
• Capacitor — native platform bridge

Link to Devin session: https://app.devin.ai/sessions/5c400920d2b745bc84401cd020820f22
Requested by: @ashleeradka

---

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 04975e3e69

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.

[vex-assistant-bot]

✦ APPROVE

Value: Gives agents the minimal-but-precise context they need to work in apps/web/ without re-reading CONVENTIONS.md in full. Stack, commands, route architecture, and the migration contract in 47 lines. The pointer-based design (defer to CONVENTIONS.md / STYLE_GUIDE.md for depth) is the right call.

Content check:

• Stack entries accurate — Vite, React 19, React Router v7 data mode, Zustand, TanStack Query, HeyAPI plugin, Tailwind v4, Capacitor. ✅
• Commands correct — bun install, bun run dev, bun run openapi-ts, bunx tsc --noEmit, bun test. Port 3001 documented. ✅
• Routing section matches post-#31141 architecture: no basename, /account/* auth pages, /assistant/* app. ✅
• Migration contract is tight — "faithful copy, not simplification", Capacitor paths preserved, convention compliance on arrival, no marketing/admin. ✅

On Codex P2 (basename mismatch): Valid as a snapshot observation but not an error. This file documents the target state after PR #31141 (which I approved at 13:17) merges. Devin called it correctly. The dependency is merge order: #31141 must land first. Once it does, this file is accurate and there's no longer a mismatch.

CI: 3/3 green. ✅

One optional improvement (not blocking): Could add a one-liner under Routing pointing to src/lib/account/login-flow.ts as the source of PROVIDER_CALLBACK_URL and OAuth redirect constants — that's the file agents are most likely to touch during auth work and the one that caused the most churn in #31141. Easy to add in a follow-up if it surfaces as a gap.