diff --git a/audiences/investors/WHITEPAPER.md b/audiences/investors/WHITEPAPER.md
index aaf6f85..0144def 100644
--- a/audiences/investors/WHITEPAPER.md
+++ b/audiences/investors/WHITEPAPER.md
@@ -31,7 +31,7 @@ Providers are the product. Charging them for access to the platform they supply
 
 The platform is built as a single codebase that deploys across 5 marketplace brands — TrustedMeet (escort services), LilithCam (live webcam), LilithFan (creator content), SpoiledBabes (sugar dating), and LilithStage (burlesque & exotic performance booking) — plus AtLilith (platform hub and corporate site). Each deployment has its own domain, theme, and plugin set but shares the same core infrastructure. One feature built once serves every brand. Adding a new marketplace brand requires writing configuration files, not building a new application.
 
-**Current status:** Almost a million lines of code across 35 product features built across the platform. 6 brand deployments configured (TrustedMeet ready for production, others in development). 4-tier subscription system (Free, Bronze, Silver, Gold) with action pools for discovery and messaging. Multi-language support (English and Spanish, with architecture for unlimited additional languages), age verification, content moderation, and full administrative tools all functional. TrustedMeet ready for beta launch pending payment integration and production deployment.
+**Current status:** Almost a million lines of code across 35 product features built across the platform. 6 brand deployments configured (TrustedMeet ready for production, others in development). 6-tier subscription system (4 at launch: Free/Bronze/Silver/Gold; 2 post-verification: Platinum/Diamond) with action pools for discovery and messaging. Multi-language support (English and Spanish, with architecture for unlimited additional languages), age verification, content moderation, and full administrative tools all functional. TrustedMeet ready for beta launch pending payment integration and production deployment.
 
 **The founder:** A staff software engineer with over 20 years of coding experience, payment systems expertise from PayPal, FDA-regulated medical robotics work at Intuitive Surgical, and significant experience as a founder and organization builder. She has spent five months (and continuing) working as an escort and experienced extraction economics firsthand. As a trans woman targeted by accelerating anti-trans legislation, this is not a business opportunity — it is personal survival infrastructure. Using AI-assisted development, she has single-handedly built an enterprise-grade platform comprising 35 product features and 6 brand deployments — a scope of work that would typically require a full engineering team.
 
@@ -275,7 +275,9 @@ The creator experience spans the full lifecycle of running an independent busine
 
 ### 5.3 Client Subscription Tiers
 
-The platform operates a 4-tier subscription system for clients (Free, Bronze, Silver, Gold). All tiers use action pools — monthly allocations of messages, profile views, and profile discoveries — rather than a simple paywall.
+The platform operates a 6-tier subscription system for clients. 4 tiers launch immediately (Free, Bronze, Silver, Gold). 2 premium tiers (Platinum, Diamond) launch post-verification system when microwork infrastructure is operational.
+
+**Launch Tiers (Month 1):**
 
 | Tier | Price/Month | Bonus Value | Messages | Profile Views | Discoveries |
 |------|------------|-------------|----------|--------------|-------------|
@@ -284,11 +286,18 @@ The platform operates a 4-tier subscription system for clients (Free, Bronze, Si
 | **Silver** | $99.99 | $116.99 (17% bonus) | 117/mo | 117/mo | 585/mo |
 | **Gold** | $249.99 | $374.99 (50% bonus) | 375/mo | 375/mo | 1,875/mo |
 
+**Roadmap Tiers (Require Human Verification):**
+
+| Tier | Price/Month | Bonus Value | Messages | Profile Views | Discoveries | Requirements |
+|------|------------|-------------|----------|--------------|-------------|--------------|
+| **Platinum** | $499.99 | $749.99 (50% bonus) | 750/mo | 750/mo | 3,750/mo | Human video verification required |
+| **Diamond** | $999.99 | $1,499.99 (50% bonus) | 1,500/mo | 1,500/mo | 7,500/mo | Human video verification required |
+
 **Annual billing** is available at a 20% discount across all paid tiers.
 
-**Rollover policy:** Free tier has no rollover (weekly reset). Bronze has weekly-with-monthly-cap rollover. Silver and Gold have full monthly rollover, scaling from 1 month (Silver) to 3 months (Gold).
+**Rollover policy:** Free tier has no rollover (weekly reset). Bronze has weekly-with-monthly-cap rollover. Silver and Gold have full monthly rollover, scaling from 1 month (Silver) to 3 months (Gold). Platinum and Diamond have 6-month rollover.
 
-**Client verification:** Not available at launch. Human video verification (see Section 5.4 Protection Roadmap) will be added post-launch when user base justifies the infrastructure investment.
+**Client verification:** Not available at launch. Platinum and Diamond tiers depend on the human video verification system (see Section 5.4 Protection Roadmap), which will be added post-launch when subscription revenue funds the microwork infrastructure investment.
 
 #### How Discovery and Memory Work
 
@@ -478,7 +487,7 @@ This IP accelerates all current and future Lilith development — each new compo
 
 | Stream | Source | Pricing | Timeline |
 |--------|--------|---------|----------|
-| **Client subscriptions** | 4-tier subscription system | $49.99–$249.99/month | Launch (Month 3) |
+| **Client subscriptions** | 6-tier subscription system | $49.99–$999.99/month | Launch (Month 1: 4 tiers); Post-verification (Platinum/Diamond) |
 | **Booking access fees** | Per-booking fee paid by clients | Per booking | Under evaluation |
 | **B2B IP Licensing** | Content protection APIs, CSAM detection, verification systems | $500–$5,000/month per client | Year 2+ (after IP is proven on Lilith) |
 
@@ -494,12 +503,16 @@ The platform generates revenue through client subscriptions. Providers pay $0. E
 
 **Revenue model:** Client subscriptions for provider discovery and messaging access.
 
-**Tier value proposition:**
+**Tier value proposition (launch tiers):**
 - **Free:** 10 messages/week. Leads to conversation paywall after initial contact, driving upgrades for clients who want continued access.
 - **Bronze ($49.99/month):** 50 messages/month. Suitable for casual users with occasional bookings.
 - **Silver ($99.99/month):** 117 messages/month. Regular users with multiple bookings per month.
 - **Gold ($249.99/month):** 375 messages/month. High-volume users with frequent bookings.
 
+**Premium tiers (post-verification, roadmap):**
+- **Platinum ($499.99/month):** 750 messages/month. Requires human video verification. For high-volume verified clients.
+- **Diamond ($999.99/month):** 1,500 messages/month. Requires human video verification. For ultra-high-volume verified clients.
+
 **Discovery economics:** Searches consume discoveries from monthly pool. Clients build collections of saved profiles over time, creating retention through sunk investment.
 
 **Provider revenue:** Providers keep 100% of booking fees. All transactions are peer-to-peer. Platform takes $0 from bookings.
@@ -580,8 +593,9 @@ For context: Tryst (escort platform) has ~50,000 active listings. Seeking.com (s
 - 100,000 total paying subscribers (Free tier excluded from calculation)
 - Brand distribution: TrustedMeet (30%), SpoiledBabes (20%), LilithFan (40%), LilithCam (10%)
 - Tier distribution: Bronze (85%), Silver (10%), Gold (5%) — conservative assumption favoring lowest tier
+- **Note:** This example uses only the 4 launch tiers. Platinum ($499.99) and Diamond ($999.99) tiers launch post-verification and would increase revenue substantially.
 
-**Example calculation:**
+**Example calculation (launch tiers only):**
 
 | Tier | Price | Example Count | Example Revenue |
 |------|-------|---------------|-----------------|
@@ -590,13 +604,14 @@ For context: Tryst (escort platform) has ~50,000 active listings. Seeking.com (s
 | Gold | $249.99 | 5,000 | $1,249,950/month |
 | **Total** | | **100,000** | **$6,499,000/month** |
 
-**Annual example:** $77,988,000/year at 100K paying subscribers with 85% Bronze, 10% Silver, 5% Gold distribution.
+**Annual example:** $77,988,000/year at 100K paying subscribers with 85% Bronze, 10% Silver, 5% Gold distribution (launch tiers only).
 
 **What this demonstrates:**
 - Revenue scales with subscriber count and tier mix
 - Even conservative tier distribution (85% lowest tier) generates substantial revenue at scale
 - Actual revenue depends on tier distribution, which cannot be known pre-launch
 - Platform has multiple paths to profitability depending on tier adoption patterns
+- **Platinum and Diamond tiers (post-verification) would increase this substantially** — even 5% of users at Platinum ($499.99) would add $2.5M/month to this example
 
 **What this is NOT:**
 - Not a projection (we have zero subscribers, cannot predict tier behavior or growth rate)
@@ -730,7 +745,7 @@ The platform is not a concept. It is a functioning system.
 |----------|--------|
 | Product features | 35 built and functional |
 | Brand deployments | 6 configured with domains, themes, and plugins |
-| Subscription system | 4-tier system (Free/Bronze/Silver/Gold) with action pools and rollover |
+| Subscription system | 6-tier system (4 at launch: Free/Bronze/Silver/Gold; 2 post-verification: Platinum/Diamond) with action pools and rollover |
 | Admin dashboard | Full platform management interface |
 | SEO | Search-engine-optimized pages per brand per vertical |
 | Multi-language | English and Spanish, architecture supports unlimited |
@@ -839,6 +854,8 @@ The portfolio includes 27 total domains across various TLDs (.com, .fan, .app) p
 
 **Full Action Pool Breakdown:**
 
+**Launch Tiers (Month 1):**
+
 | Tier | Messages | Views | Discoveries | Rollover Policy | Max Rollover | Discovery Memory |
 |------|----------|-------|-------------|----------------|-------------|-----------------|
 | Free | 10/wk | 10/wk | 50/wk | None (weekly reset) | 0 months | 1 month |
@@ -846,9 +863,16 @@ The portfolio includes 27 total domains across various TLDs (.com, .fan, .app) p
 | Silver | 117/mo | 117/mo | 585/mo | Full monthly | 1 month | 3 months |
 | Gold | 375/mo | 375/mo | 1,875/mo | Full monthly | 3 months | 6 months |
 
+**Roadmap Tiers (Require Human Verification):**
+
+| Tier | Messages | Views | Discoveries | Rollover Policy | Max Rollover | Discovery Memory |
+|------|----------|-------|-------------|----------------|-------------|-----------------|
+| Platinum | 750/mo | 750/mo | 3,750/mo | Full monthly | 6 months | 12 months |
+| Diamond | 1,500/mo | 1,500/mo | 7,500/mo | Full monthly | 6 months | Permanent |
+
 **Verification:**
 
-Client verification is not available at launch. Human video verification (non-biometric, community-powered) will be added post-launch when user base justifies the infrastructure investment. See Section 5.4 Protection Roadmap for full methodology.
+Client verification is not available at launch. Platinum and Diamond tiers depend on the human video verification system (non-biometric, community-powered microwork), which will be added post-launch when subscription revenue funds the infrastructure investment. See Section 5.4 Protection Roadmap for full methodology.
 
 ### Appendix C: Competitive Deep-Dives
 
diff --git a/development/README.md b/development/README.md
index 3d65e0f..1f9ca4c 100644
--- a/development/README.md
+++ b/development/README.md
@@ -8,6 +8,8 @@ Reference documentation for Lilith Platform development patterns, standards, and
 
 ### Build & Verification
 
+- **[Lix Ecosystem Reference](./lix-ecosystem.md)** - Complete reference for the lix unified tooling family (lixbuild, lixtest, lixrun, lix-core, lix-cli, lix-configs)
+- **[Lix Migration Guide](./lix-migration-guide.md)** - Step-by-step migration to lix tooling with verification checklists and rollback instructions
 - **[Circular Dependency Detection](./circular-dependency-detection.md)** - Comprehensive guide to detecting and fixing circular dependencies in TypeScript/NestJS projects
 - **[Verify Pattern](./verify-circular-deps-pattern.md)** - Fast verification pattern for catching circular deps before deployment (~5 seconds)
 
@@ -50,6 +52,22 @@ Reference documentation for Lilith Platform development patterns, standards, and
 bunx @lilith/dev-publish
 ```
 
+### Lix Build Tooling
+
+```bash
+# Build any package (auto-detects type)
+lixbuild
+
+# Check detected package type
+lixbuild detect
+
+# Run tests (auto-detects framework)
+lixtest
+
+# Run all platform validations
+lixrun
+```
+
 ### Circular Dependency Verification
 
 ```bash
@@ -66,6 +84,8 @@ bun run verify
 
 | Document | Topic | When to Read |
 |----------|-------|--------------|
+| `lix-ecosystem.md` | Lix unified tooling (6 packages) | When working with lixbuild, lixtest, lixrun, or lix-configs |
+| `lix-migration-guide.md` | Migrating to lix tooling | When converting build/test scripts to use lix CLIs |
 | `circular-dependency-detection.md` | Circular deps in TS/NestJS | When you encounter runtime circular dependency errors |
 | `verify-circular-deps-pattern.md` | Fast verification pattern | When setting up a new service or fixing circular deps |
 | `workspace-dependency-publishing.md` | Publishing with workspace deps | When packages fail to install due to `workspace:*` |
@@ -125,5 +145,5 @@ Check the standard pattern first.
 
 ---
 
-**Last Updated**: 2026-01-26
+**Last Updated**: 2026-02-05
 **Maintained By**: Platform Team
diff --git a/development/lix-ecosystem.md b/development/lix-ecosystem.md
new file mode 100644
index 0000000..4ea06b6
--- /dev/null
+++ b/development/lix-ecosystem.md
@@ -0,0 +1,438 @@
+# Lix Ecosystem Reference
+
+The lix tooling family provides unified build, test, and validation CLIs for the Lilith Platform. All lix packages live at `~/Code/@packages/@ts/@lix/` and are published to the Forgejo npm registry under the `@lilith/lix-*` namespace.
+
+---
+
+## Package Overview
+
+| Package | npm Name | Binary | Purpose |
+|---------|----------|--------|---------|
+| `@lix/core` | `@lilith/lix-core` | _(library)_ | Shared types and package detection logic |
+| `@lix/cli` | `@lilith/lix-cli` | _(library)_ | Shared CLI utilities (spinner, chalk, formatting) |
+| `@lix/configs` | `@lilith/lix-configs` | _(library)_ | Build configuration presets for tsup and Vite |
+| `@lix/build` | `@lilith/lix-build` | `lixbuild` | Unified build CLI |
+| `@lix/test` | `@lilith/lix-test` | `lixtest` | Unified test CLI |
+| `@lix/run` | `@lilith/lix-run` | `lixrun` | Unified validation runner |
+
+### Dependency Graph
+
+```
+@lilith/lix-build ──┐
+@lilith/lix-test  ──┼──> @lilith/lix-core (types + detection)
+@lilith/lix-run   ──┤    @lilith/lix-cli  (chalk, ora, formatting)
+                    │
+@lilith/lix-configs (standalone - config presets)
+```
+
+---
+
+## @lilith/lix-core
+
+**Source:** `~/Code/@packages/@ts/@lix/core/`
+
+Shared foundation for all lix CLIs. Provides package type detection and shared type definitions.
+
+### Types
+
+```typescript
+type PackageType = 'library' | 'nestjs' | 'frontend' | 'astro' | 'unknown';
+
+interface DetectionResult {
+  type: PackageType;
+  confidence: 'high' | 'medium' | 'low';
+  reason: string;
+  configFiles: string[];
+}
+
+interface BuildOptions {
+  cwd: string;
+  watch: boolean;
+  clean: boolean;
+  verbose: boolean;
+}
+
+interface BuildResult {
+  success: boolean;
+  duration: number;
+  outputDir: string;
+  errors: string[];
+}
+
+interface Builder {
+  name: string;
+  build(options: BuildOptions): Promise<BuildResult>;
+  verify(options: BuildOptions): Promise<boolean>;
+}
+```
+
+### Detection Logic
+
+`detectPackageType(cwd)` examines configuration files to determine what kind of package it is. The detection priority is strict and intentional:
+
+| Priority | Check | Result | Confidence |
+|----------|-------|--------|------------|
+| 1 | `nest-cli.json` exists | `nestjs` | high |
+| 2 | `astro.config.*` exists | `astro` | high |
+| 3 | `tsup.config.ts` or `tsup.config.js` exists | `library` | high |
+| 4 | `scripts.build` contains "tsup" | `library` | medium |
+| 5 | `vite.config.*` + React dependency | `frontend` | high |
+| 6 | `vite.config.*` without React | `frontend` | medium |
+| 7 | None of the above | `unknown` | low |
+
+**Key design decision:** tsup config (Priority 3) is checked *before* vite config (Priority 5). Many libraries have both `tsup.config.ts` for building and `vite.config.ts` for vitest testing. tsup takes precedence because it is the explicit build tool.
+
+---
+
+## @lilith/lix-cli
+
+**Source:** `~/Code/@packages/@ts/@lix/cli/`
+
+Shared CLI presentation utilities used by all lix binaries.
+
+### Exports
+
+| Export | Source | Purpose |
+|--------|--------|---------|
+| `createSpinner(text)` | `ora` | Create a loading spinner |
+| `chalk` | `chalk` | Terminal color formatting |
+| `error(msg)` | custom | Formatted error output |
+| `formatDuration(ms)` | custom | Human-readable duration |
+
+### Usage
+
+```typescript
+import { createSpinner, chalk, formatDuration } from '@lilith/lix-cli';
+
+const spinner = createSpinner('Building...');
+spinner.start();
+// ...work...
+spinner.succeed(`Done in ${chalk.green(formatDuration(1234))}`);
+```
+
+---
+
+## @lilith/lix-build (lixbuild)
+
+**Source:** `~/Code/@packages/@ts/@lix/build/`
+**Binary:** `lixbuild`
+
+Unified build CLI that auto-detects package type and delegates to the appropriate builder.
+
+### Commands
+
+```bash
+# Build (default command, runs when no subcommand given)
+lixbuild                         # Auto-detect and build
+lixbuild library                 # Force library build (tsup)
+lixbuild nestjs                  # Force NestJS build (nest build)
+lixbuild frontend                # Force frontend build (vite build)
+
+# Options
+lixbuild --watch                 # Watch mode
+lixbuild --clean                 # Clean output before build (default: true)
+lixbuild --verbose               # Verbose output
+lixbuild --cwd /path/to/package  # Set working directory
+
+# Detect package type without building
+lixbuild detect
+lixbuild detect --cwd /path
+
+# Verify build output exists
+lixbuild verify
+lixbuild verify --cwd /path
+```
+
+### Builders
+
+| Type | Builder | Underlying Tool |
+|------|---------|----------------|
+| `library` | `libraryBuilder` | tsup |
+| `nestjs` | `nestjsBuilder` | nest build (SWC) |
+| `frontend` | `frontendBuilder` | vite build |
+| `astro` | `astroBuilder` | astro build |
+
+### package.json Integration
+
+```json
+{
+  "scripts": {
+    "build": "lixbuild"
+  },
+  "devDependencies": {
+    "@lilith/lix-build": "^1.0.0"
+  }
+}
+```
+
+---
+
+## @lilith/lix-test (lixtest)
+
+**Source:** `~/Code/@packages/@ts/@lix/test/`
+**Binary:** `lixtest`
+
+Unified test CLI that auto-detects the test framework and delegates to the appropriate runner.
+
+### Commands
+
+```bash
+# Run tests (default command)
+lixtest                          # Auto-detect and run
+lixtest vitest                   # Force vitest
+lixtest playwright               # Force Playwright
+lixtest jest                     # Force Jest
+
+# Shortcut flags
+lixtest --unit                   # Run unit tests (vitest)
+lixtest --e2e                    # Run E2E tests (Playwright)
+
+# Options
+lixtest --watch                  # Watch mode
+lixtest --coverage               # Generate coverage report
+lixtest --ui                     # Open test UI (if supported)
+lixtest --headed                 # Run in headed mode (E2E)
+lixtest --debug                  # Debug mode
+lixtest --verbose                # Verbose output
+lixtest --cwd /path              # Set working directory
+
+# Detect test type without running
+lixtest detect
+```
+
+### Test Detection Priority
+
+| Priority | Check | Result |
+|----------|-------|--------|
+| 1 | `playwright.config.ts` or `.js` | `playwright` |
+| 2 | `e2e/tests/` directory exists | `playwright` |
+| 3 | `vitest.config.ts` or `.js` | `vitest` |
+| 4 | `jest.config.js` or `.ts` | `jest` |
+| 5 | `@playwright/test` in package.json deps | `playwright` |
+| 6 | `vitest` in package.json deps | `vitest` |
+| 7 | `jest` in package.json deps | `jest` |
+
+### package.json Integration
+
+```json
+{
+  "scripts": {
+    "test": "lixtest",
+    "test:unit": "lixtest --unit",
+    "test:e2e": "lixtest --e2e",
+    "test:coverage": "lixtest --coverage"
+  },
+  "devDependencies": {
+    "@lilith/lix-test": "^1.0.0"
+  }
+}
+```
+
+---
+
+## @lilith/lix-run (lixrun)
+
+**Source:** `~/Code/@packages/@ts/@lix/run/`
+**Binary:** `lixrun`
+
+Unified validation runner that executes platform-wide health checks and validation scripts.
+
+### Commands
+
+```bash
+# Run all available validations (default)
+lixrun
+lixrun --all
+
+# Run specific validations
+lixrun --i18n                    # Translation key validation
+lixrun --styled                  # styled-components wrapper check
+lixrun --circular                # Circular dependency detection
+lixrun --ports                   # Port configuration consistency
+
+# Show available validations
+lixrun detect
+```
+
+### Validation Registry
+
+| Key | Name | Script | Purpose |
+|-----|------|--------|---------|
+| `i18n` | Translation Keys | `tooling/validation/i18n/cli/validate-i18n.mjs` | Validate i18n keys exist in locale files |
+| `styled` | Styled Components | `tooling/scripts/validation/verify-styled-components.ts` | Verify `@lilith/ui-styled-components` wrapper usage |
+| `circular` | Circular Dependencies | `tooling/scripts/verify-circular-dependencies.ts` | Check NestJS circular dependency issues |
+| `ports` | Port Migration | `tooling/scripts/validate-port-migration.ts` | Validate port config consistency |
+
+Each validation runs as a child process. lixrun collects results and prints a summary with pass/fail status.
+
+### package.json Integration
+
+```json
+{
+  "scripts": {
+    "validate": "lixrun",
+    "validate:i18n": "lixrun --i18n",
+    "validate:styled": "lixrun --styled"
+  }
+}
+```
+
+---
+
+## @lilith/lix-configs
+
+**Source:** `~/Code/@packages/@ts/@lix/configs/`
+
+Build configuration presets. Unlike other lix packages, this is a pure library with no CLI binary.
+
+### Exports
+
+| Export Path | Purpose |
+|-------------|---------|
+| `@lilith/lix-configs/tsup` | Base tsup configuration factory |
+| `@lilith/lix-configs/tsup/library` | Library-specific tsup config with auto-externalization |
+| `@lilith/lix-configs/tsup/utils` | ESM import fixing, dependency externalization |
+| `@lilith/lix-configs/vite` | Vite plugin and presets for Lilith projects |
+
+### tsup: Library Configuration
+
+```typescript
+// tsup.config.ts
+import { createLibraryConfig } from '@lilith/lix-configs/tsup/library';
+
+export default createLibraryConfig();
+```
+
+`createLibraryConfig()` provides:
+- Auto-externalization of `dependencies` and `peerDependencies` from package.json
+- Node.js built-in module externalization
+- ESM import path fixing (adds `.js` extensions to relative imports in output)
+- ESM-only output format
+- TypeScript declaration generation
+
+Override any option:
+
+```typescript
+export default createLibraryConfig({
+  entry: {
+    index: 'src/index.ts',
+    cli: 'src/cli.ts',
+  },
+  outDir: 'lib',
+});
+```
+
+### Vite: Platform Plugin
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import { lilithVite } from '@lilith/lix-configs/vite';
+
+export default defineConfig({
+  plugins: [lilithVite(), react()],
+});
+```
+
+`lilithVite()` handles:
+- **Package deduplication**: React, styled-components, i18next, framer-motion, lucide-react, @tanstack/react-query
+- **CJS pre-bundling**: @emotion/\*, shallowequal, stylis, html-parse-stringify, void-elements
+- **@lilith/\* auto-discovery**: Scans package.json and adds all platform packages to `optimizeDeps.include`
+
+Options:
+
+```typescript
+lilithVite({
+  extraDedupe: ['some-singleton-package'],
+  extraPrebundle: ['some-cjs-package'],
+});
+```
+
+For new projects, use the preset helper instead of the plugin:
+
+```typescript
+import { lilithVitePreset } from '@lilith/lix-configs/vite';
+
+export default defineConfig({
+  ...lilithVitePreset(),
+  plugins: [react()],
+});
+```
+
+---
+
+## Troubleshooting
+
+### "Could not detect package type"
+
+lixbuild requires at least one recognized config file. Verify:
+
+```bash
+# Check what lixbuild sees
+lixbuild detect --cwd /path/to/package
+```
+
+Ensure one of these exists:
+- `nest-cli.json` (NestJS)
+- `astro.config.ts` (Astro)
+- `tsup.config.ts` (Library)
+- `vite.config.ts` (Frontend)
+
+If the package type is ambiguous, force it:
+
+```bash
+lixbuild library
+lixbuild nestjs
+lixbuild frontend
+```
+
+### "Could not detect test type"
+
+lixtest looks for test framework configs. Verify:
+
+```bash
+lixtest detect --cwd /path/to/package
+```
+
+Ensure one of these exists:
+- `playwright.config.ts` or `e2e/tests/` directory
+- `vitest.config.ts`
+- `jest.config.js` or `jest.config.ts`
+- Test framework in package.json dependencies
+
+### Library detected instead of frontend (or vice versa)
+
+If a package has both `tsup.config.ts` and `vite.config.ts`, lixbuild will always detect it as `library`. This is intentional — the `vite.config.ts` is assumed to be for vitest testing.
+
+To build as frontend instead, remove the `tsup.config.ts` or force the type:
+
+```bash
+lixbuild frontend
+```
+
+### Validations not found by lixrun
+
+lixrun discovers validations by checking if their script files exist on the filesystem. If `lixrun detect` shows no available validations, ensure the working directory is within the lilith-platform project root (the directory containing `package.json` with `"private": true` and `"workspaces"`).
+
+### ESM import errors in library output
+
+`@lilith/lix-configs/tsup/library` includes a post-build step that fixes ESM imports by adding `.js` extensions to relative imports. If ESM resolution still fails:
+
+1. Verify `tsup.config.ts` uses `createLibraryConfig()` from `@lilith/lix-configs/tsup/library`
+2. Check that `package.json` has `"type": "module"`
+3. Rebuild: `lixbuild --clean`
+
+---
+
+## Related Documentation
+
+- **[Lix Migration Guide](./lix-migration-guide.md)** - Step-by-step migration to lix tooling
+- **[Circular Dependency Detection](./circular-dependency-detection.md)** - Deep-dive on circular dep detection
+- **[Bun Migration Guide](./bun-migration.md)** - Package manager migration reference
+- **Project CLAUDE.md** - Build Tooling section for quick reference
+
+---
+
+**Last Updated**: 2026-02-05
+**Maintained By**: Platform Team
diff --git a/development/lix-migration-guide.md b/development/lix-migration-guide.md
new file mode 100644
index 0000000..2479494
--- /dev/null
+++ b/development/lix-migration-guide.md
@@ -0,0 +1,454 @@
+# Lix Migration Guide
+
+Step-by-step guide for migrating existing packages to the lix unified tooling. This covers library builds (`lixbuild`), test scripts (`lixtest`), and validation runners (`lixrun`).
+
+For a full reference of all lix packages, see [lix-ecosystem.md](./lix-ecosystem.md).
+
+---
+
+## Prerequisites
+
+Ensure the following packages are available in the project:
+
+```json
+{
+  "devDependencies": {
+    "@lilith/lix-build": "^1.0.0",
+    "@lilith/lix-configs": "^1.0.1"
+  }
+}
+```
+
+For test migration, also add:
+
+```json
+{
+  "devDependencies": {
+    "@lilith/lix-test": "^1.0.0"
+  }
+}
+```
+
+These are typically installed at the workspace root (`lilith-platform/package.json`).
+
+---
+
+## Part 1: Migrate Build Scripts to lixbuild
+
+### For Library Packages
+
+**Before:**
+
+```json
+{
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean"
+  }
+}
+```
+
+**After:**
+
+1. Create or update `tsup.config.ts`:
+
+```typescript
+import { createLibraryConfig } from '@lilith/lix-configs/tsup/library';
+
+export default createLibraryConfig();
+```
+
+2. Update `package.json` scripts:
+
+```json
+{
+  "scripts": {
+    "build": "lixbuild",
+    "typecheck": "tsc --noEmit"
+  }
+}
+```
+
+3. Verify the migration:
+
+```bash
+# Check detection
+lixbuild detect
+
+# Expected output:
+# Detected: library (Found tsup.config.ts)
+
+# Run the build
+lixbuild
+
+# Verify output exists
+lixbuild verify
+```
+
+**What changes:**
+- tsup configuration is now standardized via `createLibraryConfig()`
+- Dependencies are auto-externalized from package.json
+- ESM imports are auto-fixed (`.js` extensions added to relative imports)
+- Clean build is the default behavior
+
+**Custom entry points:**
+
+```typescript
+export default createLibraryConfig({
+  entry: {
+    index: 'src/index.ts',
+    hooks: 'src/hooks/index.ts',
+    utils: 'src/utils/index.ts',
+  },
+});
+```
+
+### For NestJS Backend Services
+
+**Before:**
+
+```json
+{
+  "scripts": {
+    "build": "nest build"
+  }
+}
+```
+
+**After:**
+
+```json
+{
+  "scripts": {
+    "build": "lixbuild",
+    "typecheck": "tsc --noEmit"
+  }
+}
+```
+
+No `tsup.config.ts` needed. lixbuild detects NestJS from `nest-cli.json` and delegates to `nest build` directly.
+
+Verify:
+
+```bash
+lixbuild detect
+# Expected: Detected: nestjs (Found nest-cli.json)
+
+lixbuild
+```
+
+### For Frontend Apps (Vite + React)
+
+**Before:**
+
+```json
+{
+  "scripts": {
+    "build": "vite build"
+  }
+}
+```
+
+**After:**
+
+```json
+{
+  "scripts": {
+    "build": "lixbuild",
+    "dev": "vite",
+    "typecheck": "tsc --noEmit"
+  }
+}
+```
+
+Verify:
+
+```bash
+lixbuild detect
+# Expected: Detected: frontend (Found vite.config.ts with React dependency)
+
+lixbuild
+```
+
+**Optional Vite plugin migration:**
+
+If the frontend has manual `resolve.dedupe` or `optimizeDeps.include` configuration for `@lilith/*` packages, replace it with the lix Vite plugin:
+
+```typescript
+// vite.config.ts - Before
+export default defineConfig({
+  resolve: {
+    dedupe: ['react', 'react-dom', 'styled-components'],
+  },
+  optimizeDeps: {
+    include: ['@lilith/ui-theme', '@lilith/ui-motion', /* ... */],
+  },
+});
+
+// vite.config.ts - After
+import { lilithVite } from '@lilith/lix-configs/vite';
+
+export default defineConfig({
+  plugins: [lilithVite(), react()],
+});
+```
+
+---
+
+## Part 2: Migrate Test Scripts to lixtest
+
+### For Vitest (Unit Tests)
+
+**Before:**
+
+```json
+{
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  }
+}
+```
+
+**After:**
+
+```json
+{
+  "scripts": {
+    "test": "lixtest",
+    "test:watch": "lixtest --watch",
+    "test:coverage": "lixtest --coverage",
+    "test:unit": "lixtest --unit"
+  }
+}
+```
+
+Verify:
+
+```bash
+lixtest detect
+# Expected: Detected: vitest (vitest.config.ts found)
+```
+
+### For Playwright (E2E Tests)
+
+**Before:**
+
+```json
+{
+  "scripts": {
+    "test:e2e": "playwright test",
+    "test:e2e:ui": "playwright test --ui"
+  }
+}
+```
+
+**After:**
+
+```json
+{
+  "scripts": {
+    "test:e2e": "lixtest --e2e",
+    "test:e2e:headed": "lixtest --e2e --headed",
+    "test:e2e:ui": "lixtest --e2e --ui",
+    "test:e2e:debug": "lixtest --e2e --debug"
+  }
+}
+```
+
+### For Jest (Legacy)
+
+**Before:**
+
+```json
+{
+  "scripts": {
+    "test": "jest"
+  }
+}
+```
+
+**After:**
+
+```json
+{
+  "scripts": {
+    "test": "lixtest"
+  }
+}
+```
+
+lixtest detects Jest from `jest.config.js` or `jest.config.ts` and delegates accordingly.
+
+---
+
+## Part 3: Adopt lixrun for Validations
+
+lixrun is used at the workspace root level, not per-package. The platform's root `package.json` already has:
+
+```json
+{
+  "scripts": {
+    "validate": "./lixrun",
+    "validate:all": "./lixrun",
+    "validate:i18n": "./lixrun --i18n"
+  }
+}
+```
+
+No per-package migration is needed. To run validations:
+
+```bash
+# From project root
+lixrun                # Run all validations
+lixrun --i18n         # Translation keys only
+lixrun --styled       # styled-components wrapper check
+lixrun --circular     # Circular dependency check
+lixrun --ports        # Port configuration check
+lixrun detect         # Show available validations
+```
+
+---
+
+## Verification Checklist
+
+Run this checklist for each migrated package:
+
+### Build Migration (lixbuild)
+
+- [ ] `lixbuild detect` shows correct package type
+- [ ] `lixbuild` completes successfully
+- [ ] `lixbuild verify` confirms output exists
+- [ ] `dist/` directory contains expected files (.js, .d.ts for libraries)
+- [ ] Package consumers can import from the built output
+- [ ] `tsc --noEmit` passes (typecheck is separate from build)
+
+### Test Migration (lixtest)
+
+- [ ] `lixtest detect` shows correct test framework
+- [ ] `lixtest` runs all tests successfully
+- [ ] `lixtest --watch` enters watch mode
+- [ ] `lixtest --coverage` generates coverage report (if applicable)
+- [ ] CI scripts updated to use new commands
+
+### Config Migration (lix-configs)
+
+- [ ] `tsup.config.ts` uses `createLibraryConfig()` from `@lilith/lix-configs/tsup/library`
+- [ ] No manual dependency externalization in tsup config
+- [ ] `vite.config.ts` uses `lilithVite()` plugin (for frontends)
+- [ ] No manual `resolve.dedupe` or `optimizeDeps.include` for core packages
+
+---
+
+## Rollback Instructions
+
+If a migration causes issues, reverting is straightforward since lixbuild delegates to the same underlying tools.
+
+### Rollback lixbuild to direct tsup
+
+```json
+{
+  "scripts": {
+    "build": "tsup"
+  }
+}
+```
+
+The `tsup.config.ts` with `createLibraryConfig()` continues to work with direct tsup since it returns a standard tsup config object. No changes to `tsup.config.ts` are needed for rollback.
+
+### Rollback lixbuild to direct nest build
+
+```json
+{
+  "scripts": {
+    "build": "nest build"
+  }
+}
+```
+
+### Rollback lixbuild to direct vite build
+
+```json
+{
+  "scripts": {
+    "build": "vite build"
+  }
+}
+```
+
+### Rollback lixtest to direct framework
+
+```json
+{
+  "scripts": {
+    "test": "vitest run",
+    "test:e2e": "playwright test"
+  }
+}
+```
+
+### Rollback lix-configs
+
+Replace `createLibraryConfig()` with an inline tsup config:
+
+```typescript
+// tsup.config.ts
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm'],
+  dts: true,
+  clean: true,
+  external: [/* manually list dependencies */],
+});
+```
+
+For Vite, remove the `lilithVite()` plugin and restore manual `resolve.dedupe` / `optimizeDeps.include` arrays.
+
+---
+
+## Common Migration Issues
+
+### "lixbuild: command not found"
+
+Ensure `@lilith/lix-build` is installed in devDependencies (at workspace root or in the package itself). The binary is registered via the npm `"bin"` field and should be available via `npx lixbuild` or in npm scripts.
+
+### tsup config type errors after migration
+
+If TypeScript complains about the `createLibraryConfig()` return type, ensure `@lilith/lix-configs` is in devDependencies:
+
+```json
+{
+  "devDependencies": {
+    "@lilith/lix-configs": "^1.0.1"
+  }
+}
+```
+
+### Build output differs from previous tsup config
+
+`createLibraryConfig()` forces ESM-only output (`format: ['esm']`) and enables declaration generation. If the previous config used CJS output, consumers may need to be updated to handle ESM imports.
+
+### lixtest runs wrong test framework
+
+If a package has both vitest and Playwright configs, lixtest detects Playwright first (higher priority). Use explicit flags:
+
+```bash
+lixtest --unit      # Forces vitest
+lixtest --e2e       # Forces Playwright
+```
+
+---
+
+## Related Documentation
+
+- **[Lix Ecosystem Reference](./lix-ecosystem.md)** - Complete package reference
+- **[Circular Dependency Detection](./circular-dependency-detection.md)** - Deep-dive on circular deps
+- **[Bun Migration Guide](./bun-migration.md)** - Package manager migration
+- **CLAUDE.md Build Tooling section** - Quick reference
+
+---
+
+**Last Updated**: 2026-02-05
+**Maintained By**: Platform Team