# .clinerules — Cline / Roo Code Rules for @bytelyst Common Platform
# Read AGENTS.md for the complete onboarding guide.

## Project: @bytelyst Common Platform — Shared packages + microservices for the ByteLyst ecosystem
Architecture: TypeScript, ESM, pnpm workspace, Fastify 5, Vitest, Azure Cosmos DB

## Mandatory Rules
- Package manager: pnpm — NEVER use npm
- ESM everywhere: "type": "module", .js extensions in imports
- Fastify module pattern: types.ts → repository.ts → routes.ts
- Use req.log / app.log — never console.log
- Every Cosmos document MUST include a productId field
- peerDependencies for heavy deps; workspace:* for inter-package deps
- Services re-export @bytelyst/* in src/lib/ for clean internal imports
- Commits: `type(scope): description`
- After changes, verify: `pnpm build && pnpm test && pnpm typecheck`

## Key File Locations
- packages/ — @bytelyst/* shared libraries (errors, cosmos, config, auth, api-client, fastify-core, react-auth, logger, testing, blob, extraction, monitoring, design-tokens)
- services/platform-service/ — consolidated platform service (port 4003)
- services/extraction-service/ — text extraction + Python sidecar (port 4005)
- dashboards/admin-web/ — admin console (port 3001)
- dashboards/tracker-web/ — issue tracker (port 3003)
- Full guide: `AGENTS.md`
