docs: add AGENTS.md and CLAUDE.md for AI coding agent onboarding

AGENTS.md covers: - Project identity and scopes (@bytelyst/* packages, @lysnrai/* services) - Full monorepo layout with all 7 packages and 5 services - Tech stack rules (ESM, Fastify 5, Zod, Vitest, pnpm) - Coding conventions (MUST/MUST NOT rules) - File ownership map (27 domains) - Build/test/dev commands - Common patterns (new module, new package, token workflow) - Environment variables reference - Dependency graph and build order - 12 common pitfalls CLAUDE.md is a compact summary referencing AGENTS.md.
2026-02-12 12:51:39 -08:00 · 2026-02-12 12:51:39 -08:00 · 5cd4bc69ea
commit 5cd4bc69ea
parent 09c767295a
2 changed files with 299 additions and 0 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@ -0,0 +1,275 @@
+# AGENTS.md — AI Coding Agent Instructions
+
+> **For:** Claude Code, OpenAI Codex, Cursor, GitHub Copilot, Windsurf Cascade, and any AI coding agent.
+> **Repo:** `learning_ai_common_plat` — Shared platform packages + microservices for the ByteLyst ecosystem.
+> **See also:** [`README.md`](README.md) for quick start, [`docs/ECOSYSTEM_ARCHITECTURE.md`](docs/ECOSYSTEM_ARCHITECTURE.md) for full architecture.
+
+---
+
+## 1. Project Identity
+
+| Key | Value |
+|-----|-------|
+| **Root package** | `@bytelyst/root` |
+| **Library scope** | `@bytelyst/*` (packages/) |
+| **Service scope** | `@lysnrai/*` (services/) |
+| **Product consumers** | [LysnrAI](../learning_voice_ai_agent), [MindLyst](../learning_multimodal_memory_agents) |
+| **Product-agnostic** | Yes — every Cosmos doc includes `productId` |
+| **Runtime** | Node.js (ESM), TypeScript 5.7+ |
+| **Package manager** | pnpm (workspace) |
+| **Test runner** | Vitest |
+
+## 2. Monorepo Layout
+
+```
+learning_ai_common_plat/
+├── packages/                       # @bytelyst/* shared libraries
+│   ├── errors/                     # Typed HTTP service errors (400–429)
+│   ├── cosmos/                     # Azure Cosmos DB client singleton + container registry
+│   ├── config/                     # Zod-based env loader + product identity (loadProductIdentity)
+│   ├── auth/                       # JWT utilities, auth middleware, password hashing
+│   ├── api-client/                 # Configurable fetch wrapper with auth token injection
+│   ├── react-auth/                 # React auth context factory (typed provider + hook)
+│   └── design-tokens/              # Cross-platform tokens (JSON → CSS/TS/Kotlin/Swift)
+│       ├── tokens/bytelyst.tokens.json   # ← CANONICAL SOURCE
+│       ├── scripts/generate.ts           # Token generator
+│       └── generated/                    # Output: tokens.css, tokens.ts, MindLystTokens.kt, MindLystTheme.swift
+├── services/                       # @lysnrai/* product-agnostic microservices
+│   ├── platform-service/           # Auth, audit, flags, notifications, blob (port 4003)
+│   ├── billing-service/            # Subscriptions, Stripe, usage, licenses (port 4002)
+│   ├── growth-service/             # Invitations, referrals, promos (port 4001)
+│   ├── tracker-service/            # Items, comments, votes, public roadmap (port 4004)
+│   └── monitoring/                 # Loki + Grafana config, health-check script
+├── docs/                           # Architecture docs, roadmap, analysis
+├── package.json                    # Root scripts: build, test, typecheck, clean
+├── pnpm-workspace.yaml             # Workspace: packages/* + services/*
+├── tsconfig.base.json              # Shared TS config (ES2022, NodeNext, strict)
+├── vitest.config.ts                # Root vitest config (passWithNoTests)
+├── docker-compose.yml              # Full service stack + Loki + Grafana + Traefik
+├── .env.example                    # Required env vars template
+└── .editorconfig                   # Editor settings
+```
+
+## 3. Tech Stack Rules
+
+### TypeScript (all packages + services)
+- **Module system:** ESM (`"type": "module"` everywhere)
+- **TS target:** ES2022, `moduleResolution: NodeNext`
+- **Base config:** All packages/services extend `../../tsconfig.base.json`
+- **Builds:** `tsc` — outputs to `dist/`
+- **Tests:** Vitest with `passWithNoTests: true` at root
+
+### Service framework (Fastify)
+- **Framework:** Fastify 5 with Zod validation
+- **Module pattern:** `types.ts` → `repository.ts` → `routes.ts` per module
+- **Auth:** JWT via `jose` — platform-service issues, all others validate
+- **Database:** Azure Cosmos DB via `@azure/cosmos`
+- **Logging:** Fastify built-in `req.log` / `app.log` (never `console.log`)
+- **Health:** Every service exposes `GET /health` → `{ status: "ok", service, requestId }`
+- **Request tracing:** `x-request-id` header propagated across all services
+- **Dev mode:** `tsx watch src/server.ts`
+
+### Package conventions
+- All packages export from `src/index.ts` → `dist/index.js`
+- Use `exports` field in `package.json` (not just `main`)
+- Peer dependencies for heavy/shared deps (`@azure/cosmos`, `jose`, `bcryptjs`, `react`, `zod`)
+- Workspace deps: `"@bytelyst/errors": "workspace:*"`
+
+## 4. Coding Conventions
+
+### MUST follow
+- Every Cosmos document MUST include a `productId` field
+- Every REST endpoint MUST validate input with Zod schemas
+- Every service MUST propagate `x-request-id` headers
+- Use `PRODUCT_ID` from `@bytelyst/config` (`loadProductIdentity()`) — never hardcode
+- Services use self-contained Zod config schemas in `src/lib/config.ts` (avoids zod version mismatch with shared packages)
+- Services re-export from `@bytelyst/*` in their `src/lib/` files (`errors.ts`, `cosmos.ts`, `product-config.ts`)
+- Commit messages: `type(scope): description` — types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`
+
+### MUST NOT do
+- Never use `console.log` in production code — use `req.log` or `app.log` in Fastify
+- Never use `any` type — use Zod inference or explicit types
+- Never hardcode secrets or API keys
+- Never modify tests to make them pass — fix the actual code
+- Never delete existing comments or documentation unless explicitly asked
+- Never add emojis to code unless explicitly asked
+
+## 5. File Ownership Map
+
+| Domain | Location | Key Files |
+|--------|----------|-----------|
+| **Errors** | `packages/errors/` | `src/index.ts` — `BadRequestError`, `UnauthorizedError`, `ForbiddenError`, `NotFoundError`, `ConflictError`, `RateLimitError` |
+| **Cosmos client** | `packages/cosmos/` | `src/index.ts` — `getCosmosClient()`, `getContainer()`, container registry |
+| **Config / Product ID** | `packages/config/` | `src/index.ts` — `loadEnvConfig()`, `loadProductIdentity()`, `getProductId()` |
+| **JWT / Auth** | `packages/auth/` | `src/index.ts` — `signJwt()`, `verifyJwt()`, `hashPassword()`, `verifyPassword()`, auth middleware |
+| **API client** | `packages/api-client/` | `src/index.ts` — `createApiClient()` with token injection |
+| **React auth** | `packages/react-auth/` | `src/index.ts` — `createAuthContext()` factory (provider + hook) |
+| **Design tokens** | `packages/design-tokens/` | `tokens/bytelyst.tokens.json` (source), `scripts/generate.ts` (generator), `generated/` (output) |
+| **Auth / JWT issue** | `services/platform-service/` | `src/modules/auth/` |
+| **Feature flags** | `services/platform-service/` | `src/modules/flags/` — FNV-1a hash for deterministic rollout |
+| **Blob storage** | `services/platform-service/` | `src/modules/blob/`, `src/lib/blob.ts` — SAS tokens, CRUD |
+| **Audit log** | `services/platform-service/` | `src/modules/audit/` |
+| **Notifications** | `services/platform-service/` | `src/modules/notifications/` |
+| **Subscriptions** | `services/billing-service/` | `src/modules/subscriptions/` |
+| **Stripe webhooks** | `services/billing-service/` | `src/modules/stripe/` |
+| **Usage tracking** | `services/billing-service/` | `src/modules/usage/` |
+| **Invitations** | `services/growth-service/` | `src/modules/invitations/` |
+| **Referrals** | `services/growth-service/` | `src/modules/referrals/` |
+| **Tracker items** | `services/tracker-service/` | `src/modules/items/` |
+| **Public roadmap** | `services/tracker-service/` | `src/modules/public/` |
+| **Tracker comments** | `services/tracker-service/` | `src/modules/comments/` |
+| **Tracker votes** | `services/tracker-service/` | `src/modules/votes/` |
+| **Monitoring** | `services/monitoring/` | `health-check.ts`, `loki/`, `grafana/` |
+
+## 6. How to Run Things
+
+```bash
+# ── Install ────────────────────────────────────────
+pnpm install
+
+# ── Build all packages + services ──────────────────
+pnpm build
+
+# ── Run all tests (165+ across all workspaces) ─────
+pnpm test
+
+# ── Type-check everything ──────────────────────────
+pnpm typecheck
+
+# ── Clean dist/ in all packages ────────────────────
+pnpm clean
+
+# ── Run a specific service in dev mode ─────────────
+pnpm --filter @lysnrai/platform-service dev
+pnpm --filter @lysnrai/billing-service dev
+pnpm --filter @lysnrai/growth-service dev
+pnpm --filter @lysnrai/tracker-service dev
+
+# ── Run tests for one workspace ────────────────────
+pnpm --filter @lysnrai/platform-service test
+pnpm --filter @bytelyst/errors test
+
+# ── Generate design tokens ─────────────────────────
+pnpm --filter @bytelyst/design-tokens generate
+
+# ── Docker Compose (all services + monitoring) ─────
+docker compose up -d
+docker compose down
+
+# ── Health check all services ──────────────────────
+pnpm --filter @lysnrai/monitoring check
+```
+
+## 7. Common Patterns
+
+### Adding a new Fastify module
+1. Create `services/<service>/src/modules/<name>/types.ts` — Zod schemas + TS interfaces
+2. Create `services/<service>/src/modules/<name>/repository.ts` — Cosmos CRUD
+3. Create `services/<service>/src/modules/<name>/routes.ts` — REST endpoints
+4. Register in `services/<service>/src/server.ts`: `await app.register(routes, { prefix: "/api" })`
+5. Add tests: `services/<service>/src/modules/<name>/<name>.test.ts`
+
+### Adding a new shared package
+1. Create `packages/<name>/` with `package.json` (`name: "@bytelyst/<name>"`)
+2. Add `src/index.ts` with exports
+3. Add `tsconfig.json` extending `../../tsconfig.base.json`
+4. Heavy deps go in `peerDependencies`, not `dependencies`
+5. Consumer services add `"@bytelyst/<name>": "workspace:*"` to their `dependencies`
+
+### Using shared packages in services
+Services re-export from `@bytelyst/*` in `src/lib/` for clean internal imports:
+```typescript
+// src/lib/errors.ts
+export { BadRequestError, NotFoundError, ConflictError } from "@bytelyst/errors";
+
+// src/lib/cosmos.ts
+export { getCosmosClient, getContainer } from "@bytelyst/cosmos";
+
+// src/lib/product-config.ts
+import { loadProductIdentity } from "@bytelyst/config";
+const identity = loadProductIdentity();
+export const PRODUCT_ID = identity.productId;
+```
+
+### Design token workflow
+1. Edit `packages/design-tokens/tokens/bytelyst.tokens.json`
+2. Run `pnpm --filter @bytelyst/design-tokens generate`
+3. Copy generated files to consumer repos:
+   - `MindLystTokens.kt` → `mindlyst-native/shared/.../theme/`
+   - `MindLystTheme.swift` → `mindlyst-native/iosApp/`
+   - Token CSS → `design-system/web/mindlyst.css` (token section only)
+
+## 8. Environment Variables
+
+Required by all services (see `.env.example`):
+```
+COSMOS_ENDPOINT=https://<account>.documents.azure.com:443/
+COSMOS_KEY=<primary-key>
+COSMOS_DATABASE=lysnrai
+JWT_SECRET=<shared-secret>
+```
+
+Additional per-service:
+```
+# billing-service + growth-service
+STRIPE_SECRET_KEY=<stripe-key>
+STRIPE_WEBHOOK_SECRET=<webhook-secret>
+
+# platform-service (blob storage)
+AZURE_BLOB_CONNECTION_STRING=<connection-string>
+AZURE_BLOB_ACCOUNT_NAME=bytelystblobs
+AZURE_BLOB_ACCOUNT_KEY=<account-key>
+
+# All services
+DEFAULT_PRODUCT_ID=lysnrai
+```
+
+## 9. Dependency Graph
+
+```
+@bytelyst/errors          ← no deps (foundation)
+@bytelyst/cosmos          ← peers: @azure/cosmos
+@bytelyst/config          ← peers: zod
+@bytelyst/auth            ← peers: jose, bcryptjs
+@bytelyst/api-client      ← no deps
+@bytelyst/react-auth      ← deps: @bytelyst/api-client; peers: react
+@bytelyst/design-tokens   ← no deps (standalone generator)
+
+@lysnrai/platform-service ← @bytelyst/{config, cosmos, errors}
+@lysnrai/billing-service  ← @bytelyst/{config, cosmos, errors}
+@lysnrai/growth-service   ← @bytelyst/{config, cosmos, errors}
+@lysnrai/tracker-service  ← @bytelyst/{config, cosmos, errors}
+```
+
+Build order: packages first (they have no inter-deps), then services. `pnpm build` handles this automatically via workspace topology.
+
+## 10. Key Documents
+
+| When you need to... | Read this |
+|---------------------|-----------|
+| Understand the full architecture | [`docs/ECOSYSTEM_ARCHITECTURE.md`](docs/ECOSYSTEM_ARCHITECTURE.md) |
+| See the extraction roadmap | [`docs/ROADMAP.md`](docs/ROADMAP.md) |
+| Understand why this repo exists | [`docs/COMMON_PLATFORM_ANALYSIS.md`](docs/COMMON_PLATFORM_ANALYSIS.md) |
+| Quick start / consuming packages | [`README.md`](README.md) |
+| LysnrAI product repo conventions | [`../learning_voice_ai_agent/AGENTS.md`](../learning_voice_ai_agent/AGENTS.md) |
+| MindLyst native repo conventions | [`../learning_multimodal_memory_agents/AGENTS.md`](../learning_multimodal_memory_agents/AGENTS.md) |
+
+## 11. Service Test Counts
+
+| Service / Package | Tests | Runner |
+|-------------------|-------|--------|
+| platform-service | 55 | vitest |
+| tracker-service | 45 | vitest |
+| growth-service | 33 | vitest |
+| billing-service | 32 | vitest |
+| **Total** | **165+** | |
+
+## 12. Common Pitfalls
+
+1. **Don't import `zod` from `@bytelyst/config` in services** — services bundle their own zod version. Use self-contained Zod schemas in `src/lib/config.ts`.
+2. **Don't forget `productId`** — every Cosmos document must include it.
+3. **Don't use `dependencies` for heavy libs in packages** — use `peerDependencies` so consumers control the version.
+4. **Don't mix up package scopes** — libraries are `@bytelyst/*`, services are `@lysnrai/*`.
+5. **Don't run `npm` commands** — this is a pnpm workspace. Always use `pnpm`.
+6. **Don't modify generated files directly** — edit `bytelyst.tokens.json` and re-run the generator.
+7. **Build packages before testing services** — service tests may import from `@bytelyst/*` dist. Run `pnpm build` first if you get import errors.
--- a/CLAUDE.md
+++ b/CLAUDE.md
@ -0,0 +1,24 @@
+# CLAUDE.md — Compact Agent Reference
+
+Read [`AGENTS.md`](AGENTS.md) for full instructions. This file is a quick summary.
+
+## Identity
+- **Repo:** `learning_ai_common_plat` — shared `@bytelyst/*` packages + `@lysnrai/*` microservices
+- **Consumers:** LysnrAI (voice dictation), MindLyst (multimodal memory)
+- **Stack:** TypeScript, ESM, pnpm workspace, Fastify 5, Vitest, Azure Cosmos DB
+
+## Key Commands
+```bash
+pnpm install && pnpm build && pnpm test   # full verify
+pnpm --filter @lysnrai/platform-service dev  # run one service
+pnpm --filter @bytelyst/design-tokens generate  # regen tokens
+```
+
+## Critical Rules
+- Every Cosmos doc needs `productId`
+- Every endpoint validates with Zod
+- Services re-export `@bytelyst/*` in `src/lib/` files
+- Services use self-contained Zod config (not from shared package)
+- `@bytelyst/*` = packages, `@lysnrai/*` = services
+- Use pnpm, never npm
+- Commit format: `type(scope): description`