docs: add CLAUDE.md for Claude Code onboarding

[aicoder2009]

Summary

• Adds a concise CLAUDE.md that gives Claude Code (and other AI coding assistants) immediate context about the repo
• Covers monorepo structure, essential commands, tech stack, architecture patterns, Tailwind v4 differences, git workflow, and code style
• ~130 lines — focused on non-obvious information that requires reading multiple files to discover

Test plan

• Verify the file renders correctly on GitHub
• Spot-check commands and paths mentioned are accurate

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds a CLAUDE.md onboarding/context file intended to give AI coding assistants (and contributors) a quick, repo-specific orientation.

Changes:

• Documented monorepo layout (apps/packages), key commands, and local dev setup
• Summarized frontend/backend tech stack and key architectural patterns
• Added notes on repo workflow and Tailwind v4 CSS-first configuration

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The statement that the mail frontend is “NOT Next.js” conflicts with existing repo docs (e.g., README.md:33 and AGENT.md:8 both describe the frontend as Next.js). To avoid onboarding confusion, either update those documents as part of this change or add a short note here acknowledging that older docs are outdated.

Suggested change

	- `apps/mail/` — Frontend: React Router v7 + Vite (NOT Next.js), deployed to Cloudflare Workers
	- `apps/mail/` — Frontend: React Router v7 + Vite, deployed to Cloudflare Workers (older repo docs may still refer to Next.js; those references are outdated)

[Copilot]

pnpm docker:db:down runs docker compose ... down, which stops and removes the containers/network (not just “Stop containers”). Consider rewording to avoid misleading folks who expect the containers to remain created (that’s closer to docker:db:stop).

Suggested change

	pnpm docker:db:down # Stop containers
	pnpm docker:db:clean # Stop and remove volumes
	pnpm docker:db:down # Stop and remove DB containers + network
	pnpm docker:db:clean # Stop and remove DB containers, network, and volumes

[Copilot]

This says Drizzle Studio auto-starts with pnpm dev, but pnpm dev maps to turbo run dev (mail: react-router dev, server: wrangler dev) and doesn’t start drizzle-kit studio. Suggest removing this line or replacing it with instructions to run pnpm db:studio when needed.

Suggested change

	Frontend runs on localhost:3000, backend on localhost:8787. Drizzle Studio auto-starts with `pnpm dev`.
	Frontend runs on localhost:3000, backend on localhost:8787. Run `pnpm db:studio` when you need the Drizzle Studio UI.

[Copilot]

The lint command notes oxlint @latest is “also the pre-commit hook”, but .husky/pre-commit pins oxlint@1.9.0. Recommend aligning these (either pin the suggested command to 1.9.0, or update the hook) so contributors get consistent results.

Suggested change

	pnpm dlx oxlint@latest --deny-warnings # Lint (also the pre-commit hook)
	pnpm dlx oxlint@1.9.0 --deny-warnings # Lint (also the pre-commit hook)

[Copilot]

The pnpm test, pnpm test:watch, and pnpm test:coverage commands are documented as a Vitest suite via @zero/testing, but packages/testing/package.json does not define test, test:watch, or test:coverage scripts (it currently only has Playwright test:e2e*). Either update this section to the actual commands (e.g. pnpm --filter=@zero/testing test:e2e) or add the missing scripts so the documented commands work.

Suggested change

	pnpm test # Vitest suite (via @zero/testing package)
	pnpm test:watch # Watch mode
	pnpm test:coverage # Coverage report
	pnpm test:ai # AI evaluation tests (apps/server)
	pnpm eval # Run evalite evaluation suite
	pnpm --filter=@zero/testing test:e2e # Playwright test suite
	pnpm --filter=@zero/testing test:e2e:ui # Playwright UI mode
	pnpm --filter=@zero/testing test:e2e:debug # Playwright debug mode
	pnpm test:ai # AI evaluation tests (apps/server)
	pnpm eval # Run evalite evaluation suite