diff --git a/README.md b/README.md
index f69e0479..68c3c3ef 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,29 @@
 # @bytelyst/common-platform
 
-Shared packages for the ByteLyst ecosystem — used by [LysnrAI](https://github.com/saravanakumardb1/learning_voice_ai_agent) and [MindLyst](https://github.com/saravanakumardb1/learning_multimodal_memory_agents).
+Shared packages **and** product-agnostic microservices for the ByteLyst ecosystem — used by [LysnrAI](https://github.com/saravanakumardb1/learning_voice_ai_agent) and [MindLyst](https://github.com/saravanakumardb1/learning_multimodal_memory_agents).
 
-## Packages
+## Repository Structure
+
+```
+learning_ai_common_plat/
+├── packages/                    # Shared libraries (@bytelyst/*)
+│   ├── errors/                  # Typed HTTP service errors (400–429)
+│   ├── cosmos/                  # Azure Cosmos DB client + container registry
+│   ├── config/                  # Zod env loader + product identity
+│   ├── auth/                    # JWT, middleware, password hashing
+│   ├── api-client/              # Configurable fetch wrapper
+│   ├── react-auth/              # React auth context factory
+│   └── design-tokens/           # Cross-platform tokens (JSON → CSS/TS/Kotlin/Swift)
+├── services/                    # 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
+└── docs/                        # Architecture docs, roadmap, analysis
+```
+
+## Shared Libraries
 
 | Package | Description | Peer Dependencies |
 |---------|-------------|-------------------|
@@ -14,31 +35,43 @@ Shared packages for the ByteLyst ecosystem — used by [LysnrAI](https://github.
 | `@bytelyst/react-auth` | React auth context factory (typed provider + hook) | `react` |
 | `@bytelyst/design-tokens` | Cross-platform design tokens (JSON → CSS/TS/Kotlin/Swift) | — |
 
+## Shared Services
+
+| Service | Port | Description | Tests |
+|---------|------|-------------|-------|
+| `platform-service` | 4003 | Auth, audit, feature flags, notifications, blob storage | 55 |
+| `billing-service` | 4002 | Subscriptions, Stripe webhooks, usage tracking, licenses, plans | 32 |
+| `growth-service` | 4001 | Invitations, referrals, promo codes | 33 |
+| `tracker-service` | 4004 | Feature requests, bugs, tasks, public roadmap | 45 |
+| `monitoring` | — | Loki + Grafana dashboards, health-check script | — |
+
+All services are **product-agnostic** — every Cosmos document includes a `productId` field, so a single deployment serves LysnrAI, MindLyst, or any future product.
+
 ## Quick Start
 
 ```bash
 # Install dependencies
 pnpm install
 
-# Build all packages
+# Build all packages + services
 pnpm build
 
-# Run all tests
+# Run all tests (165 total across packages + services)
 pnpm test
 
 # Type-check all packages
 pnpm typecheck
+
+# Run a specific service in dev mode
+pnpm --filter @lysnrai/platform-service dev
 ```
 
-## Consuming from LysnrAI / MindLyst
+## Consuming Libraries from Product Repos
 
 During development, use `file:` references in consumer `package.json`:
 
 ```jsonc
-// From Fastify services (3 levels up):
-"@bytelyst/errors": "file:../../../learning_ai_common_plat/packages/errors"
-
-// From Next.js dashboards at repo root (2 levels up):
+// From a Next.js dashboard at repo root (2 levels up):
 "@bytelyst/errors": "file:../../learning_ai_common_plat/packages/errors"
 
 // From MindLyst web (3 levels up — inside mindlyst-native/web/):