# AGENTS.md — YetAnotherSuite

## Project state

This is a **greenfield project** — no code exists yet. The implementation plan (`yetanothersuite_implementation_plan.md` / `.json`) defines everything: architecture, data model, tech stack, phases, conventions, and API design. Read it first before writing any code.

## Tech stack (from the plan)

- **Monorepo**: Turborepo + pnpm workspaces
- **Frontend**: React 18+ / TypeScript strict mode, Vite, Tailwind CSS + shadcn/ui + Radix primitives
- **State**: Zustand (global), TanStack Query (server state), Jotai (local UI)
- **Editor**: TipTap / ProseMirror (block-based)
- **Backend**: Node.js + Fastify, PostgreSQL 15+ (Prisma ORM), Redis, Zod validation
- **Realtime**: Yjs (CRDT) + WebSocket (Redis adapter)
- **Search**: Meilisearch (full-text) + pgvector (semantic)
- **Queue**: BullMQ (Redis-backed)
- **Desktop**: Tauri; **Mobile**: React Native (Expo)
- **Testing**: Vitest + React Testing Library + Playwright + MSW

## Key conventions (from the plan)

- **TypeScript strict mode** — no `any` types except in test mocks
- **Functional components with hooks** — no class components
- **Zod** for all runtime validation — never trust client input
- **Optimistic UI updates** — rollback on error with toast notification
- **Loading + error states** on every async operation — no silent failures
- **i18n from day one** — i18n keys for all user-facing strings
- **Accessible components** — ARIA labels, keyboard navigation, focus management
- **Conventional commits**: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`
- **Branch naming**: `feature/xxx`, `fix/xxx`, `refactor/xxx`, `docs/xxx`

## Development workflow

1. **Phase-by-phase execution** — complete each phase fully before moving to the next
2. **TDD** — write tests before implementation, maintain >80% coverage on critical paths
3. **Pre-commit hooks** (Husky): lint → type-check → test affected
4. **Lint**: ESLint + Prettier (strict config, no warnings allowed)
5. **Every merged PR must be deployable** — use feature flags for incomplete work
6. **Profile after every major feature** — no performance regressions

## Phases (from the plan)

| Phase | Timeline | What |
|-------|----------|------|
| 1 | Weeks 1-4 | Foundation: monorepo, auth, DB schema, API, offline sync |
| 2 | Weeks 5-8 | Notes MVP: block editor, CRUD, search, bidirectional linking |
| 3 | Weeks 9-14 | Tasks + Calendar: task management, calendar engine, NL input, reminders |
| 4 | Weeks 15-18 | AI: semantic search, writing assistant, knowledge graph, smart scheduling |
| 5 | Weeks 19-22 | Collaboration: real-time editing, workspaces, sharing, templates |
| 6 | Weeks 23-28 | Platform: public API, plugins, desktop/mobile apps, SSO, self-hosting |