# 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 + AKV resolver
- packages/auth/ → JWT, middleware, password hashing
- packages/api-client/ → Fetch wrapper with auth injection
- packages/fastify-core/ → createServiceApp() + startService()
- packages/react-auth/ → React auth context factory
- packages/logger/ → Structured logging (pino)
- packages/testing/ → Test mocks, Fastify inject helpers
- packages/blob/ → Azure Blob Storage client + SAS
- packages/extraction/ → createExtractionClient(), shared types
- packages/monitoring/ → Health-check utilities
- packages/design-tokens/ → Cross-platform tokens (JSON → CSS/TS/Kotlin/Swift)
- services/platform-service/ → Consolidated: auth, audit, flags, blob, subscriptions, stripe, usage, plans, licenses, invitations, referrals, promos, items, comments, votes, public (port 4003)
- services/extraction-service/ → Text extraction + Python sidecar (port 4005)
- 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 (234+)
- 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