# Cursor Rules — @bytelyst Common Platform

# For full agent instructions, read AGENTS.md at the repo root.

## Project
- Repo: learning_ai_common_plat — shared packages + microservices
- Library scope: @bytelyst/* (packages/)
- Service scope: @lysnrai/* (services/)
- Consumers: LysnrAI (voice dictation), MindLyst (multimodal memory)
- Product-agnostic: every Cosmos document MUST include a productId field
- Package manager: pnpm — NEVER use npm

## Monorepo Structure
- packages/errors/ → Typed HTTP errors (400–429)
- packages/cosmos/ → Azure Cosmos DB client singleton
- packages/config/ → Zod env loader + product identity
- packages/auth/ → JWT, middleware, password hashing
- packages/api-client/ → Fetch wrapper with auth injection
- packages/react-auth/ → React auth context factory
- packages/design-tokens/ → Cross-platform tokens (JSON → CSS/TS/Kotlin/Swift)
- services/platform-service/ → Auth, audit, flags, blob (port 4003)
- services/billing-service/ → Subscriptions, Stripe, usage (port 4002)
- services/growth-service/ → Invitations, referrals, promos (port 4001)
- services/tracker-service/ → Items, comments, votes, public roadmap (port 4004)
- services/monitoring/ → Loki + Grafana, health-check

## TypeScript Rules
- ESM everywhere ("type": "module")
- Target: ES2022, moduleResolution: NodeNext
- All packages/services extend ../../tsconfig.base.json
- Fastify 5 with Zod validation for all inputs
- Module pattern: types.ts → repository.ts → routes.ts
- Auth: JWT via jose — platform-service issues, all others validate
- Database: Azure Cosmos DB via @azure/cosmos
- Tests: Vitest (passWithNoTests at root)
- NEVER use console.log — use req.log or app.log in Fastify
- NEVER use any type — use Zod inference or explicit types

## Package Rules
- Export from src/index.ts → dist/index.js
- Use exports field in package.json (not just main)
- Heavy deps in peerDependencies, not dependencies
- Workspace deps: "@bytelyst/errors": "workspace:*"

## Service Rules
- Services re-export @bytelyst/* in src/lib/ for clean internal imports
- Services use self-contained Zod config schemas in src/lib/config.ts
- Health: GET /health → { status: "ok", service, requestId }
- Propagate x-request-id headers across all services

## Conventions
- Commit messages: type(scope): description (feat, fix, docs, refactor, test, chore)
- Fix source code, not tests (unless the test itself is wrong)
- Never delete existing comments/documentation unless asked
- Never add emojis unless asked
- Never hardcode secrets or API keys
- Never modify generated token files directly — edit bytelyst.tokens.json

## Key Commands
- pnpm build → build all packages + services
- pnpm test → run all tests (165+)
- pnpm typecheck → type-check everything
- pnpm --filter @lysnrai/platform-service dev → run one service
- pnpm --filter @bytelyst/design-tokens generate → regen tokens

## Key Documents
- AGENTS.md — Full AI agent instructions
- README.md — Quick start + consuming packages
- docs/ECOSYSTEM_ARCHITECTURE.md — Full architecture
- docs/ROADMAP.md — Phased extraction plan
- .env.example — Required environment variables