# Common Platform — Windsurf / Codeium Rules
# Read AGENTS.md for full context. These are the critical rules.

Project: @bytelyst/* shared packages + @lysnrai/* microservices
Stack: TypeScript, ESM, pnpm workspace, Fastify 5, Vitest, Azure Cosmos DB

## Architecture Rules
- @bytelyst/* = shared packages (packages/), @lysnrai/* = product services (services/)
- Product-agnostic: every Cosmos document MUST include productId field
- Services re-export @bytelyst/* in src/lib/ files for clean internal imports
- Services use self-contained Zod config schemas (not from shared packages)
- Package manager: pnpm — NEVER use npm

## Key Paths
- Packages: packages/ (@bytelyst/errors, cosmos, config, auth, api-client, fastify-core, react-auth, logger, testing, blob, extraction, monitoring, design-tokens)
- Services: services/ (platform-service 4003, extraction-service 4005)
- Base TS config: tsconfig.base.json (ES2022, NodeNext, strict)
- Workspace: pnpm-workspace.yaml

## Conventions
- ESM everywhere ("type": "module", .js extensions in imports)
- Fastify module pattern: types.ts → repository.ts → routes.ts
- Heavy deps in peerDependencies, workspace deps as "workspace:*"
- Use req.log / app.log — never console.log
- Commits: feat(scope): description / fix(scope): description

## Consumers
- Dashboards in ../learning_voice_ai_agent/ consume packages via file: refs
- Prerequisite: pnpm build before consumer npm install

## Build Verification
- pnpm build && pnpm test && pnpm typecheck