feat: create AI.dev/SKILLS repository with reusable development skills

- Add 15 comprehensive skills extracted from Windsurf workflows - Cover debugging, testing, releases, deployment, security, and documentation - Each skill includes step-by-step instructions and copy-pasteable commands - Skills organized by category with cross-references and difficulty levels
2026-02-12 17:13:16 -08:00 · 2026-02-12 17:13:16 -08:00 · c3b869ceb9
commit c3b869ceb9
parent 90b9cf93d8
17 changed files with 5314 additions and 0 deletions
--- a/AI.dev/SKILLS/README.md
+++ b/AI.dev/SKILLS/README.md
@ -0,0 +1,113 @@
+# AI Development Skills Repository
+
+This directory contains reusable skills and patterns extracted from Windsurf conversation history across all repositories. These skills represent proven approaches to common development tasks that can be applied consistently across projects.
+
+## Skill Categories
+
+### 🏗️ Architecture & Setup
+
+- **Monorepo Management** - Managing multi-repo workspaces with shared dependencies
+- **Service Architecture** - Fastify microservices patterns with Cosmos DB
+- **Mobile Architecture** - KMP + Native iOS/Android patterns
+- **Dashboard Architecture** - Next.js dashboards with shared packages
+
+### 🔧 Development Workflows
+
+- **Production Readiness** - Comprehensive pre-release validation
+- **Debugging Services** - Systematic debugging methodology
+- **Local Development** - Starting and managing all services locally
+- **Docker Compose** - Container orchestration for full stack
+
+### 📱 Mobile Development
+
+- **Mobile Code Quality** - Cross-platform mobile code standards
+- **iOS Development** - SwiftUI + Xcode patterns
+- **Android Development** - Kotlin + Jetpack Compose patterns
+- **KMP Development** - Kotlin Multiplatform best practices
+
+### 🚀 Release & Deployment
+
+- **Desktop Release** - Cross-platform desktop app packaging
+- **iOS Release** - TestFlight and App Store deployment
+- **Service Deployment** - Microservice deployment patterns
+- **Dashboard Deployment** - Next.js production deployment
+
+### 🧪 Testing & Quality
+
+- **Test Strategies** - Unit, integration, and E2E testing patterns
+- **Code Quality** - Linting, formatting, and static analysis
+- **Security Auditing** - Dependency and code security checks
+- **Performance Monitoring** - Bundle size and performance budgets
+
+### 📚 Documentation & Communication
+
+- **Agent Documentation** - Maintaining AI assistant documentation
+- **API Documentation** - REST API documentation patterns
+- **Architecture Documentation** - System design documentation
+- **Onboarding Documentation** - Developer onboarding materials
+
+## How to Use These Skills
+
+1. **Browse by category** - Each skill has its own markdown file with detailed instructions
+2. **Copy-paste commands** - Most skills include ready-to-use command snippets
+3. **Adapt patterns** - Modify the patterns to fit your specific project needs
+4. **Combine skills** - Many workflows combine multiple skills (e.g., Production Readiness)
+5. **Contribute back** - Add new skills or improve existing ones based on your experience
+
+## Skill Format
+
+Each skill follows a consistent format:
+
+- **Description** - What the skill does and when to use it
+- **Prerequisites** - Required tools and setup
+- **Steps** - Detailed, copy-pasteable instructions
+- **Notes** - Important considerations and tips
+- **Related Skills** - Links to related skills
+
+## Quick Reference
+
+| Need                       | Skill                                                | Location                         |
+| -------------------------- | ---------------------------------------------------- | -------------------------------- |
+| Fix a failing service      | [Debug Service](./debug-service.md)                  | 🔧 Development Workflows         |
+| Prepare for release        | [Production Readiness](./production-readiness.md)    | 🧪 Testing & Quality             |
+| Start all services locally | [Local Development Setup](./local-development.md)    | 🔧 Development Workflows         |
+| Release desktop app        | [Desktop Release](./desktop-release.md)              | 🚀 Release & Deployment          |
+| Ensure mobile code quality | [Mobile Code Quality](./mobile-code-quality.md)      | 📱 Mobile Development            |
+| Update AI docs             | [Update Agent Documentation](./update-agent-docs.md) | 📚 Documentation & Communication |
+| Write tests                | [Test Strategies](./test-strategies.md)              | 🧪 Testing & Quality             |
+| Docker full stack          | [Docker Compose](./docker-compose.md)                | 🔧 Development Workflows         |
+| Security audit             | [Security Auditing](./security-auditing.md)          | 🧪 Testing & Quality             |
+| Architecture patterns      | [Architecture Patterns](./architecture-patterns.md)  | 🏗️ Architecture & Setup          |
+
+## Available Skills
+
+### Core Skills ✅
+
+- [Debug Service](./debug-service.md) - Debug any service systematically
+- [Production Readiness](./production-readiness.md) - Complete pre-release validation
+- [Local Development Setup](./local-development.md) - Run all services locally
+- [Docker Compose](./docker-compose.md) - Containerized full stack
+- [Mobile Code Quality](./mobile-code-quality.md) - Cross-platform mobile standards
+- [Desktop Release](./desktop-release.md) - Build and package desktop apps
+- [iOS Release](./ios-release.md) - TestFlight and App Store deployment
+- [Generate Store Assets](./generate-store-assets.md) - Create app store artwork
+- [Update Agent Documentation](./update-agent-docs.md) - Keep AI docs current
+- [Test Strategies](./test-strategies.md) - Comprehensive testing approach
+- [Test Desktop App](./test-desktop-app.md) - Desktop app testing
+- [Test iOS App](./test-ios-app.md) - iOS simulator testing
+- [Architecture Patterns](./architecture-patterns.md) - System design patterns
+- [Security Auditing](./security-auditing.md) - Security checks and best practices
+- [Scan Repo Context](./scan-repo-context.md) - Generate project documentation
+
+### Planned Skills 📋
+
+- Monorepo Management
+- iOS/Android Development
+- Service Deployment
+- Performance Monitoring
+- API Documentation
+- And more...
+
+---
+
+_Last updated: 2025-02-12_
--- a/AI.dev/SKILLS/architecture-patterns.md
+++ b/AI.dev/SKILLS/architecture-patterns.md
@ -0,0 +1,487 @@
+# Architecture Patterns Skill
+
+**Description**: Common architectural patterns and structures used across the projects.
+
+## When to Use
+
+- Designing new services or features
+- Onboarding to the codebase
+- Making architectural decisions
+- Understanding system design
+
+## Core Architectures
+
+### 1. Microservices Architecture
+
+```
+┌─────────────────┐    ┌─────────────────┐
+│   Frontend      │    │   Frontend      │
+│   (Next.js)     │    │   (Next.js)     │
+└─────────┬───────┘    └─────────┬───────┘
+          │                      │
+          └──────────┬───────────┘
+                     │
+          ┌─────────────────────┐
+          │   API Gateway       │
+          │   (Traefik)         │
+          └─────────┬───────────┘
+                    │
+    ┌───────────────┼───────────────┐
+    │               │               │
+┌───▼───┐    ┌─────▼─────┐    ┌───▼───┐
+│Billing│    │ Platform  │    │Growth │
+│Service│    │ Service   │    │Service│
+└───────┘    └───────────┘    └───────┘
+```
+
+**Key Principles:**
+
+- Single responsibility per service
+- Independent deployment
+- Shared data through Cosmos DB
+- JWT-based authentication via platform service
+- Product-agnostic design (productId field)
+
+### 2. Monorepo Structure
+
+```
+learning_voice_ai_agent/          # Product repo
+├── src/                          # Desktop app (Python)
+├── backend/                      # FastAPI backend
+├── admin-dashboard-web/          # Next.js admin UI
+├── user-dashboard-web/           # Next.js user portal
+├── tracker-dashboard-web/        # Next.js tracker UI
+└── mobile_app/                   # Native mobile apps
+
+learning_ai_common_plat/          # Shared platform
+├── packages/                     # @bytelyst/* libraries
+│   ├── errors/                   # Error types
+│   ├── cosmos/                   # DB client
+│   ├── auth/                     # JWT utils
+│   ├── config/                   # Config loader
+│   ├── api-client/               # Fetch wrapper
+│   └── design-tokens/            # Design system
+└── services/                     # @lysnrai/* microservices
+    ├── billing-service/
+    ├── growth-service/
+    ├── platform-service/
+    └── tracker-service/
+```
+
+### 3. Mobile Architecture (MindLyst)
+
+```
+┌─────────────────────────────────────┐
+│           KMP Shared Module        │
+│  (Business Logic, Repositories)    │
+└──────────────┬──────────────────────┘
+               │
+    ┌──────────┴──────────┐
+    │                     │
+┌───▼────┐        ┌──────▼────┐
+│ Android│        │    iOS    │
+│(Compose)│       │ (SwiftUI) │
+└────────┘        └───────────┘
+```
+
+## Service Patterns
+
+### Fastify Service Template
+
+```typescript
+// src/server.ts
+import Fastify from 'fastify';
+import { TypeBoxTypeProvider } from '@fastify/type-provider-typebox';
+
+const server = Fastify({
+  logger: true,
+}).withTypeProvider<TypeBoxTypeProvider>();
+
+// Register plugins
+await server.register(import('@fastify/cors'));
+await server.register(import('./lib/auth'));
+
+// Register modules
+await server.register(import('./modules/auth/routes'), { prefix: '/api/auth' });
+await server.register(import('./modules/users/routes'), { prefix: '/api/users' });
+
+// Health check
+server.get('/health', async (request, reply) => {
+  return {
+    status: 'ok',
+    service: 'billing-service',
+    requestId: request.id,
+  };
+});
+
+// Start server
+try {
+  await server.listen({ port: 4002, host: '0.0.0.0' });
+} catch (err) {
+  server.log.error(err);
+  process.exit(1);
+}
+```
+
+### Module Pattern (types → repository → routes)
+
+```typescript
+// modules/auth/types.ts
+import { Type } from '@sinclair/typebox';
+
+export const LoginSchema = Type.Object({
+  email: Type.String({ format: 'email' }),
+  password: Type.String({ minLength: 8 }),
+});
+
+export const AuthResponseSchema = Type.Object({
+  token: Type.String(),
+  user: Type.Object({
+    id: Type.String(),
+    email: Type.String(),
+  }),
+});
+
+// modules/auth/repository.ts
+export class AuthRepository {
+  constructor(private client: CosmosClient) {}
+
+  async validateUser(email: string, password: string): Promise<User | null> {
+    // Database logic
+  }
+
+  async createToken(userId: string): Promise<string> {
+    // JWT creation
+  }
+}
+
+// modules/auth/routes.ts
+import { AuthRepository } from './repository';
+import { LoginSchema, AuthResponseSchema } from './types';
+
+export default async function authRoutes(server: FastifyInstance) {
+  const repo = new AuthRepository(server.cosmosClient);
+
+  server.post(
+    '/login',
+    {
+      schema: {
+        body: LoginSchema,
+        response: { 200: AuthResponseSchema },
+      },
+    },
+    async (request, reply) => {
+      const { email, password } = request.body;
+      const user = await repo.validateUser(email, password);
+
+      if (!user) {
+        reply.code(401);
+        return { error: 'Invalid credentials' };
+      }
+
+      const token = await repo.createToken(user.id);
+      return { token, user };
+    }
+  );
+}
+```
+
+## Frontend Patterns
+
+### Next.js Dashboard Structure
+
+```
+src/app/
+├── (dashboard)/           # Layout group
+│   ├── layout.tsx         # Dashboard layout with sidebar
+│   ├── page.tsx           # Dashboard home
+│   ├── users/
+│   │   ├── page.tsx       # Users list
+│   │   └── [id]/
+│   │       └── page.tsx   # User detail
+│   └── settings/
+│       └── page.tsx       # Settings page
+├── api/                   # API routes
+│   ├── auth/
+│   │   └── route.ts       # /api/auth
+│   └── users/
+│       └── route.ts       # /api/users
+├── lib/                   # Utilities
+│   ├── cosmos.ts          # @bytelyst/cosmos wrapper
+│   ├── auth-server.ts     # @bytelyst/auth wrapper
+│   └── api-client.ts      # Fetch wrapper
+└── components/            # Reusable components
+    ├── ui/                # Base UI components
+    └── forms/             # Form components
+```
+
+### Service Client Pattern
+
+```typescript
+// lib/billing-client.ts
+import { createApiClient } from '@bytelyst/api-client';
+
+const api = createApiClient({
+  baseUrl: process.env.BILLING_API_URL || 'http://localhost:4002',
+  getToken: () => localStorage.getItem('token') || undefined,
+});
+
+export const billingClient = {
+  // Subscriptions
+  getSubscriptions: () => api.fetch<Subscription[]>('/api/subscriptions'),
+  createSubscription: (data: CreateSubscriptionDto) =>
+    api.fetch<Subscription>('/api/subscriptions', {
+      method: 'POST',
+      body: JSON.stringify(data),
+    }),
+
+  // Usage
+  getUsage: (userId: string) => api.fetch<Usage>(`/api/usage/${userId}`),
+};
+```
+
+## Data Patterns
+
+### Cosmos DB Document Structure
+
+```typescript
+// Base document interface
+interface BaseDocument {
+  id: string;
+  productId: string; // REQUIRED for multi-tenancy
+  createdAt: string;
+  updatedAt: string;
+  _etag?: string;
+  _ts?: number;
+}
+
+// Example: User document
+interface UserDocument extends BaseDocument {
+  email: string;
+  name: string;
+  role: 'admin' | 'user' | 'viewer';
+  permissions?: string[];
+}
+
+// Example: Tracker item document
+interface TrackerItemDocument extends BaseDocument {
+  title: string;
+  description: string;
+  type: 'feature' | 'bug' | 'task';
+  status: 'planned' | 'in-progress' | 'completed';
+  visibility: 'public' | 'internal';
+  voteCount: number;
+}
+```
+
+### Repository Pattern
+
+```typescript
+// repositories/base.ts
+export abstract class BaseRepository<T extends BaseDocument> {
+  constructor(
+    protected client: CosmosClient,
+    protected database: string,
+    protected container: string
+  ) {}
+
+  protected get container() {
+    return this.client.database(this.database).container(this.container);
+  }
+
+  async create(item: Omit<T, 'id' | 'createdAt' | 'updatedAt'>): Promise<T> {
+    const document: T = {
+      ...item,
+      id: crypto.randomUUID(),
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+    };
+
+    const { resource } = await this.container.items.create(document);
+    return resource!;
+  }
+
+  async getById(id: string, productId: string): Promise<T | null> {
+    const { resource } = await this.container.item(id, productId).read<T>();
+
+    return resource || null;
+  }
+
+  async update(id: string, productId: string, updates: Partial<T>): Promise<T> {
+    const { resource } = await this.container.item(id, productId).replace<T>({
+      ...updates,
+      id,
+      productId,
+      updatedAt: new Date().toISOString(),
+    } as T);
+
+    return resource!;
+  }
+}
+```
+
+## Authentication Patterns
+
+### JWT Flow
+
+```
+┌─────────┐  Login  ┌─────────────┐  Validate  ┌─────────────┐
+│ Frontend │───────▶│ Platform    │────────────▶│ Other       │
+│         │        │ Service     │            │ Services    │
+└─────────┘◀───────└─────────────┘            └─────────────┘
+     Token         JWT Issuer                   JWT Validation
+```
+
+### Implementation
+
+```typescript
+// Platform service - JWT issuance
+export async function loginRoute(server: FastifyInstance) {
+  server.post('/login', async (request, reply) => {
+    const { email, password } = request.body;
+
+    // Validate credentials
+    const user = await validateUser(email, password);
+    if (!user) return reply.code(401).send({ error: 'Invalid credentials' });
+
+    // Issue JWT
+    const token = await jwt.sign(
+      { sub: user.id, email: user.email, role: user.role },
+      process.env.JWT_SECRET!,
+      { expiresIn: '24h' }
+    );
+
+    return { token, user };
+  });
+}
+
+// Other services - JWT validation
+export async function authMiddleware(server: FastifyInstance) {
+  server.addHook('onRequest', async (request, reply) => {
+    const token = request.headers.authorization?.replace('Bearer ', '');
+
+    if (!token) {
+      reply.code(401).send({ error: 'No token provided' });
+      return;
+    }
+
+    try {
+      const payload = await jwt.verify(token, process.env.JWT_SECRET!);
+      request.user = payload;
+    } catch {
+      reply.code(401).send({ error: 'Invalid token' });
+    }
+  });
+}
+```
+
+## Configuration Patterns
+
+### Environment-based Configuration
+
+```typescript
+// lib/config.ts
+import { z } from 'zod';
+
+const configSchema = z.object({
+  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
+  PORT: z.coerce.number().default(4002),
+  COSMOS_ENDPOINT: z.string(),
+  COSMOS_KEY: z.string(),
+  COSMOS_DATABASE: z.string().default('lysnrai'),
+  JWT_SECRET: z.string(),
+  AZURE_BLOB_CONNECTION_STRING: z.string().optional(),
+});
+
+export const config = configSchema.parse(process.env);
+```
+
+### Shared Package Configuration
+
+```typescript
+// @bytelyst/config
+export function loadProductIdentity() {
+  const productId = process.env.PRODUCT_ID || 'lysnrai';
+  const env = process.env.NODE_ENV || 'development';
+
+  return {
+    productId,
+    env,
+    isProduction: env === 'production',
+    isDevelopment: env === 'development',
+  };
+}
+```
+
+## Error Handling Patterns
+
+### Standardized Error Types
+
+```typescript
+// @bytelyst/errors
+export class BadRequestError extends Error {
+  constructor(
+    message: string,
+    public details?: any
+  ) {
+    super(message);
+    this.name = 'BadRequestError';
+  }
+}
+
+export class UnauthorizedError extends Error {
+  constructor(message = 'Unauthorized') {
+    super(message);
+    this.name = 'UnauthorizedError';
+  }
+}
+
+export class NotFoundError extends Error {
+  constructor(resource: string) {
+    super(`${resource} not found`);
+    this.name = 'NotFoundError';
+  }
+}
+```
+
+### Global Error Handler
+
+```typescript
+// Error handler for Fastify
+server.setErrorHandler((error, request, reply) => {
+  request.log.error(error);
+
+  if (error instanceof BadRequestError) {
+    reply.code(400);
+    return { error: error.message, details: error.details };
+  }
+
+  if (error instanceof UnauthorizedError) {
+    reply.code(401);
+    return { error: error.message };
+  }
+
+  if (error instanceof NotFoundError) {
+    reply.code(404);
+    return { error: error.message };
+  }
+
+  // Default
+  reply.code(500);
+  return { error: 'Internal server error' };
+});
+```
+
+## Notes
+
+- **Consistency is key** - Follow established patterns
+- **Product-agnostic design** - Always include productId
+- **Shared packages first** - Don't duplicate code
+- **Document decisions** - Use ADRs for major changes
+- **Evolve patterns** - Improve but maintain consistency
+
+## Related Skills
+
+- [Local Development Setup](./local-development.md) - Running the architecture
+- [Production Readiness](./production-readiness.md) - Validating the architecture
+- [Debug Service](./debug-service.md) - Fixing architectural issues
--- a/AI.dev/SKILLS/debug-service.md
+++ b/AI.dev/SKILLS/debug-service.md
@ -0,0 +1,155 @@
+# Debug Service Skill
+
+**Description**: Systematic methodology for diagnosing and fixing failing services or endpoints across the entire stack.
+
+## When to Use
+
+- Any service is returning errors or unexpected behavior
+- Health checks are failing
+- Tests are failing in CI or locally
+- Users report broken functionality
+
+## Prerequisites
+
+- Access to service logs
+- Terminal with curl installed
+- Ability to run tests locally
+
+## Steps
+
+### 1. Identify the Failing Service
+
+Quickly locate which service is affected:
+
+```bash
+# Service locations reference:
+# Backend API (Python/FastAPI) → backend/src/
+# Billing Service (Fastify) → ../learning_ai_common_plat/services/billing-service/src/
+# Growth Service (Fastify) → ../learning_ai_common_plat/services/growth-service/src/
+# Platform Service (Fastify) → ../learning_ai_common_plat/services/platform-service/src/
+# Tracker Service (Fastify) → ../learning_ai_common_plat/services/tracker-service/src/
+# Admin Dashboard (Next.js) → admin-dashboard-web/src/
+# User Dashboard (Next.js) → user-dashboard-web/src/
+# Tracker Dashboard (Next.js) → tracker-dashboard-web/src/
+```
+
+### 2. Check Health Status
+
+```bash
+# Check all services at once
+curl -s http://localhost:8000/health && \
+curl -s http://localhost:4001/health && \
+curl -s http://localhost:4002/health && \
+curl -s http://localhost:4003/health && \
+curl -s http://localhost:4004/health
+```
+
+### 3. Examine Logs
+
+**For local development:**
+
+```bash
+# Check recent logs from all services
+tail -50 .logs/backend.log .logs/growth-service.log .logs/billing-service.log \
+  .logs/platform-service.log .logs/tracker-service.log 2>/dev/null | head -100
+```
+
+**For Docker:**
+
+```bash
+docker compose logs --tail=50 <service-name>
+```
+
+### 4. Reproduce the Issue
+
+- **API errors**: Use curl with verbose output
+  ```bash
+  curl -v -X POST http://localhost:8000/api/endpoint -H "Content-Type: application/json" -d '{"key":"value"}'
+  ```
+- **UI errors**: Check browser console and network tab
+- **Test failures**: Run specific tests with verbose output
+
+  ```bash
+  # Python
+  python -m pytest tests/test_specific.py -v -x
+
+  # TypeScript/Vitest
+  pnpm test --reporter=verbose specific.test.ts
+  ```
+
+### 5. Fix Methodology
+
+Follow this order to avoid common pitfalls:
+
+1. **Read the test first** - Understand what the expected behavior is
+2. **Read the source code** - Trace the execution path
+3. **Fix the source, NOT the test** - Unless the test itself is wrong
+4. **Add a regression test** - If none exists for this bug
+5. **Run the full test suite** - Ensure no new issues were introduced
+
+### 6. Verify the Fix
+
+```bash
+# Python tests
+python -m pytest tests/ backend/tests/ -v --tb=short -x
+
+# TypeScript services
+cd ../learning_ai_common_plat && pnpm --filter @lysnrai/<service-name> test
+
+# Dashboard builds
+cd admin-dashboard-web && npm run build
+```
+
+### 7. Commit with Proper Format
+
+```bash
+git add .
+git commit -m "fix(<scope>): <description>"
+# Examples:
+# fix(billing): handle null subscription in usage endpoint
+# fix(platform): validate JWT token in auth middleware
+# fix(admin): resolve dashboard loading state issue
+git push
+```
+
+## Common Patterns
+
+### Database Connection Issues
+
+```bash
+# Check Cosmos DB connectivity
+curl -s http://localhost:4003/health | jq .
+# Look for database errors in logs
+grep -i "database\|cosmos\|connection" .logs/*.log
+```
+
+### Authentication Issues
+
+```bash
+# Decode JWT to check contents
+echo "<jwt-token>" | cut -d. -f2 | base64 -d | jq .
+# Check auth service health
+curl -s http://localhost:4003/api/auth/me -H "Authorization: Bearer <token>"
+```
+
+### Service Dependencies
+
+```bash
+# Check if dependent services are running
+docker compose ps
+# Verify service communication
+curl -s http://localhost:4002/health | jq .  # billing depends on platform
+```
+
+## Notes
+
+- **Always check logs first** - Most issues have clear error messages
+- **Isolate the problem** - Don't change multiple things at once
+- **Document the fix** - Add comments if the issue was non-obvious
+- **Consider edge cases** - Think about what might cause this to fail again
+
+## Related Skills
+
+- [Local Development Setup](./local-development.md) - Start services locally
+- [Production Readiness](./production-readiness.md) - Comprehensive validation
+- [Test Strategies](./test-strategies.md) - Writing effective tests
--- a/AI.dev/SKILLS/desktop-release.md
+++ b/AI.dev/SKILLS/desktop-release.md
@ -0,0 +1,286 @@
+# Desktop Release Skill
+
+**Description**: Build and release cross-platform desktop applications (macOS, Windows, Linux).
+
+## When to Use
+
+- Preparing for public release
+- Creating distributable packages
+- Setting up CI/CD for desktop builds
+- Code signing and notarization for distribution
+
+## Prerequisites
+
+### macOS Setup
+
+```bash
+# Install system tools
+xcode-select --install                          # Xcode Command Line Tools
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"  # Homebrew
+brew install python@3.13 portaudio              # Python + audio lib for PyAudio
+```
+
+### Project Setup
+
+```bash
+git clone https://github.com/your-org/your-repo.git
+cd your-repo
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+### Azure Credentials
+
+```bash
+cp .env ~/.lysnrai/.env     # Create config dir + env file
+```
+
+Edit `~/.lysnrai/.env` with real values:
+
+- `AZURE_SPEECH_KEY` - Azure Portal → Speech Service → Keys
+- `AZURE_SPEECH_REGION` - e.g. `eastus`
+- `AZURE_OPENAI_ENDPOINT` - Azure Portal → OpenAI → Endpoint
+- `AZURE_OPENAI_KEY` - Azure Portal → OpenAI → Keys
+- `AZURE_OPENAI_DEPLOYMENT` - e.g. `gpt-4o-mini`
+
+## macOS Build and Release
+
+### Step 1 - Build the .app Bundle
+
+```bash
+# From project root
+bash scripts/build.sh
+```
+
+**Output**: `dist/LysnrAI.app` (ad-hoc signed, ready for local use)
+
+### Step 2 - Optional Code Signing and Notarization
+
+#### Set up Apple Developer Account
+
+1. Create "Developer ID Application" certificate:
+   - Go to [developer.apple.com/account/resources/certificates](https://developer.apple.com/account/resources/certificates/list)
+   - Click **+** → select **Developer ID Application**
+   - Create CSR: Keychain Access → Certificate Assistant → Request a Certificate
+   - Upload CSR → download `.cer` → install in Keychain
+   - Verify: `security find-identity -v -p codesigning | grep "Developer ID"`
+
+2. Generate app-specific password:
+   - Go to [appleid.apple.com](https://appleid.apple.com)
+   - Sign-In and Security → App-Specific Passwords
+   - Generate new password, label "App Notarization"
+
+#### Code Sign and Notarize
+
+```bash
+export APPLE_DEVELOPER_ID="Developer ID Application: Your Name (TEAM_ID)"
+bash scripts/codesign_macos.sh dist/LysnrAI.app
+```
+
+The script prompts for:
+
+- Apple ID (default: your@email.com)
+- Team ID (default: from certificate)
+- App-specific password (secure input, not stored)
+
+### Step 3 - Install Locally
+
+```bash
+bash scripts/install_macos.sh
+```
+
+Installs to `/Applications/LysnrAI.app`, creates config, and adds desktop launcher.
+
+### Step 4 - Package for Distribution
+
+```bash
+# Create DMG installer
+bash scripts/create_dmg.sh dist/LysnrAI.app
+
+# Output: dist/LysnrAI-1.0.0.dmg (ready for distribution)
+```
+
+## Windows Build
+
+### Prerequisites
+
+```bash
+# On Windows or via GitHub Actions
+# Install Visual Studio Build Tools
+# Install WiX Toolset for MSI creation
+```
+
+### Build Process
+
+```bash
+# Activate virtual environment
+.venv\Scripts\activate
+
+# Build executable
+python scripts/build_windows.py
+
+# Create installer
+python scripts/create_installer.py
+```
+
+**Output**:
+
+- `dist/LysnrAI.exe` - Portable executable
+- `dist/LysnrAI-Setup-1.0.0.msi` - Windows installer
+
+## Linux Build
+
+### Prerequisites
+
+```bash
+# Ubuntu/Debian
+sudo apt-get update
+sudo apt-get install python3-dev python3-pyqt5 python3-venv
+
+# For AppImage
+sudo apt-get install appimagetool
+```
+
+### Build Process
+
+```bash
+# Build executable
+python scripts/build_linux.py
+
+# Create AppImage
+python scripts/create_appimage.py
+```
+
+**Output**: `dist/LysnrAI.AppImage` - Portable Linux app
+
+## CI/CD Integration
+
+### GitHub Actions Example
+
+```yaml
+name: Build Desktop App
+on: [push, release]
+
+jobs:
+  build-macos:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v4
+        with:
+          python-version: '3.13'
+      - name: Build and sign
+        env:
+          APPLE_ID: ${{ secrets.APPLE_ID }}
+          APPLE_PASSWORD: ${{ secrets.APPLE_PASSWORD }}
+          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+        run: |
+          bash scripts/build.sh
+          bash scripts/codesign_macos.sh dist/LysnrAI.app
+      - name: Create DMG
+        run: bash scripts/create_dmg.sh dist/LysnrAI.app
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v3
+        with:
+          name: macos-build
+          path: dist/*.dmg
+```
+
+## Code Signing Best Practices
+
+### macOS
+
+```bash
+# Verify signing
+codesign -dv --verbose=4 dist/LysnrAI.app
+
+# Verify notarization (after upload)
+xcrun altool --notarization-info <request-uuid> -u your@email.com -p @keychain:AC_PASSWORD
+
+# Staple notarization
+xcrun stapler staple dist/LysnrAI.app
+```
+
+### Windows
+
+```bash
+# Sign with certificate (if you have one)
+signtool sign /f certificate.p12 /p password /t http://timestamp.digicert.com dist/LysnrAI.exe
+```
+
+## Distribution Checklist
+
+### Before Release
+
+- [ ] All tests pass locally
+- [ ] Version number updated in all places
+- [ ] Release notes prepared
+- [ ] Dependencies audited for security
+- [ ] EULA/license included
+
+### After Build
+
+- [ ] Test installation on clean machine
+- [ ] Verify auto-update works
+- [ ] Test all major features
+- [ ] Check file size is reasonable
+- [ ] Virus scan executables
+
+### Release Assets
+
+| Platform | File        | Description           |
+| -------- | ----------- | --------------------- |
+| macOS    | `.dmg`      | Disk image installer  |
+| Windows  | `.msi`      | Windows installer     |
+| Windows  | `.zip`      | Portable version      |
+| Linux    | `.AppImage` | Portable Linux app    |
+| Linux    | `.deb`      | Debian/Ubuntu package |
+| Linux    | `.rpm`      | RedHat/Fedora package |
+
+## Common Issues
+
+### Build Failures
+
+1. **Missing dependencies**: Check `requirements.txt` and system packages
+2. **Python version mismatch**: Use exactly Python 3.13
+3. **Audio library issues**: Install portaudio (macOS) or appropriate Windows equivalent
+
+### Code Signing Issues
+
+1. **Certificate expired**: Renew from Apple Developer portal
+2. **Team ID mismatch**: Verify in certificate and script
+3. **Notarization pending**: Wait 5-15 minutes for Apple processing
+
+### Platform-Specific Issues
+
+- **macOS**: "App is damaged" - run `xattr -cr LysnrAI.app`
+- **Windows**: "DLL not found" - install Visual C++ redistributable
+- **Linux**: Permission denied - run `chmod +x LysnrAI.AppImage`
+
+## Version Management
+
+```bash
+# Update version in all places
+# 1. pyproject.toml
+# 2. src/__init__.py
+# 3. scripts/build.sh
+# 4. Package.json (if applicable)
+
+# Tag release
+git tag -a v1.0.0 -m "Release version 1.0.0"
+git push origin v1.0.0
+```
+
+## Notes
+
+- **Build on target platform** for best results (especially for code signing)
+- **Keep certificates secure** - never commit them to repo
+- **Test on clean machines** to ensure distribution works
+- **Document requirements** clearly for users
+
+## Related Skills
+
+- [Production Readiness](./production-readiness.md) - Before releasing
+- [Docker Compose](./docker-compose.md) - For backend services
+- [Mobile Code Quality](./mobile-code-quality.md) - For mobile releases
--- a/AI.dev/SKILLS/docker-compose.md
+++ b/AI.dev/SKILLS/docker-compose.md
@ -0,0 +1,243 @@
+# Docker Compose Skill
+
+**Description**: Run the entire application stack using Docker Compose for clean, isolated environments.
+
+## When to Use
+
+- On home networks without corporate proxy
+- For CI/CD pipelines
+- When you need reproducible environments
+- To avoid local dependency conflicts
+- For demos and presentations
+
+## Prerequisites
+
+- Docker Desktop running
+- Sufficient RAM (8GB+ recommended)
+- No corporate proxy that intercepts SSL
+
+### Required Environment Files
+
+1. **Root `.env`** (learning_voice_ai_agent)
+2. **admin-dashboard-web/.env.local**
+3. **user-dashboard-web/.env.local**
+4. **tracker-dashboard-web/.env.local**
+
+## Quick Start
+
+```bash
+cd /Users/sd9235/code/mygh/learning_voice_ai_agent
+
+# Start all 10 containers
+docker compose up -d
+
+# Check status
+docker compose ps
+
+# View logs
+docker compose logs -f
+
+# Stop everything
+docker compose down
+```
+
+## Services Overview
+
+| Service           | Container           | Port     | Image                              | Purpose                   |
+| ----------------- | ------------------- | -------- | ---------------------------------- | ------------------------- |
+| Loki              | `loki`              | 3100     | `grafana/loki:3.3.2`               | Log aggregation           |
+| Grafana           | `grafana`           | 3000     | `grafana/grafana:11.4.0`           | Monitoring dashboard      |
+| Traefik Gateway   | `gateway`           | 80, 8080 | `traefik:v3.3`                     | API gateway/load balancer |
+| Backend API       | `backend`           | 8000     | `backend/Dockerfile`               | Python FastAPI backend    |
+| Admin Dashboard   | `admin-dashboard`   | 3001     | `admin-dashboard-web/Dockerfile`   | Next.js admin UI          |
+| User Dashboard    | `user-dashboard`    | 3002     | `user-dashboard-web/Dockerfile`    | Next.js user portal       |
+| Tracker Dashboard | `tracker-dashboard` | 3003     | `tracker-dashboard-web/Dockerfile` | Next.js tracker UI        |
+| Growth Service    | `growth-service`    | 4001     | `../learning_ai_common_plat/...`   | Fastify microservice      |
+| Billing Service   | `billing-service`   | 4002     | `../learning_ai_common_plat/...`   | Fastify microservice      |
+| Platform Service  | `platform-service`  | 4003     | `../learning_ai_common_plat/...`   | Fastify microservice      |
+| Tracker Service   | `tracker-service`   | 4004     | `../learning_ai_common_plat/...`   | Fastify microservice      |
+
+## Traefik Routing (Port 80)
+
+All APIs are accessible through port 80 with path-based routing:
+
+| Path Prefix          | Routes to        | Example                              |
+| -------------------- | ---------------- | ------------------------------------ |
+| `/api` (catch-all)   | Backend API      | `http://localhost/api/health`        |
+| `/health`            | Backend API      | `http://localhost/health`            |
+| `/api/invitations`   | Growth Service   | `http://localhost/api/invitations`   |
+| `/api/referrals`     | Growth Service   | `http://localhost/api/referrals`     |
+| `/api/promos`        | Growth Service   | `http://localhost/api/promos`        |
+| `/api/subscriptions` | Billing Service  | `http://localhost/api/subscriptions` |
+| `/api/payments`      | Billing Service  | `http://localhost/api/payments`      |
+| `/api/usage`         | Billing Service  | `http://localhost/api/usage`         |
+| `/api/plans`         | Billing Service  | `http://localhost/api/plans`         |
+| `/api/licenses`      | Billing Service  | `http://localhost/api/licenses`      |
+| `/api/stripe`        | Billing Service  | `http://localhost/api/stripe`        |
+| `/api/auth`          | Platform Service | `http://localhost/api/auth`          |
+| `/api/audit`         | Platform Service | `http://localhost/api/audit`         |
+| `/api/notifications` | Platform Service | `http://localhost/api/notifications` |
+| `/api/flags`         | Platform Service | `http://localhost/api/flags`         |
+| `/api/ratelimit`     | Platform Service | `http://localhost/api/ratelimit`     |
+| `/api/items`         | Tracker Service  | `http://localhost/api/items`         |
+| `/api/tracker`       | Tracker Service  | `http://localhost/api/tracker`       |
+
+## Direct Port Access
+
+You can also access services directly on their ports:
+
+- **Backend API**: http://localhost:8000
+- **Admin Dashboard**: http://localhost:3001
+- **User Dashboard**: http://localhost:3002
+- **Tracker Dashboard**: http://localhost:3003
+- **Grafana**: http://localhost:3000 (admin / lysnrai)
+- **Traefik Dashboard**: http://localhost:8080
+
+## Common Operations
+
+### Rebuild After Code Changes
+
+```bash
+# Rebuild all images
+docker compose build
+
+# Rebuild specific service
+docker compose build backend
+
+# Restart with new images
+docker compose up -d
+```
+
+### View Logs
+
+```bash
+# All logs
+docker compose logs -f
+
+# Specific service
+docker compose logs -f backend
+
+# Last 100 lines
+docker compose logs --tail=100
+```
+
+### Debug a Container
+
+```bash
+# Get shell in container
+docker compose exec backend sh
+
+# Or for one-off commands
+docker compose run --rm backend python --version
+```
+
+### Clean Up
+
+```bash
+# Remove containers and networks
+docker compose down
+
+# Remove volumes (WARNING: deletes data)
+docker compose down -v
+
+# Remove images
+docker compose down --rmi all
+
+# Full reset
+docker system prune -a
+```
+
+## Observability
+
+### Grafana Dashboard
+
+1. Open http://localhost:3000
+2. Login with admin/lysnrai
+3. View pre-configured dashboards for:
+   - Service health
+   - Request rates
+   - Error rates
+   - Resource usage
+
+### Log Aggregation
+
+All services ship logs to Loki via the Docker driver:
+
+- Logs are automatically collected
+- Available in Grafana with `Explore` feature
+- Use `{container_name="backend"}` to filter
+
+### Health Checks
+
+```bash
+# Check all services via Traefik
+curl http://localhost/health
+
+# Check individual services
+docker compose exec backend curl http://localhost:8000/health
+```
+
+## Troubleshooting
+
+### Container Won't Start
+
+```bash
+# Check logs
+docker compose logs <service>
+
+# Check if port is in use
+lsof -i :8000
+
+# Check resource usage
+docker stats
+```
+
+### Build Failures
+
+- **Python**: Check backend/Dockerfile for Python version compatibility
+- **Node.js**: Ensure package.json lock files are present
+- **Corporate proxy**: Docker builds will fail with SSL interception
+
+### Performance Issues
+
+```bash
+# Check resource usage
+docker stats
+
+# Increase Docker memory limit in Docker Desktop
+# Recommended: 8GB+ RAM, 4+ CPU cores
+```
+
+### Network Issues
+
+```bash
+# Check network configuration
+docker network ls
+docker network inspect learning_voice_ai_agent_default
+
+# Reset network
+docker compose down
+docker network prune
+docker compose up -d
+```
+
+## Production Considerations
+
+- **Environment variables**: Use Docker secrets or external secret management
+- **Persistent data**: Use named volumes for databases
+- **Resource limits**: Set memory/CPU limits in docker-compose.yml
+- **Health checks**: All services include health check endpoints
+- **Logging**: Consider centralized logging in production
+
+## Notes
+
+- **Do NOT use on corporate proxy networks** - SSL interception breaks pip/npm installs
+- **All dashboards require `output: "standalone"`** in next.config.ts (already configured)
+- **Env vars are injected via `env_file`** in docker-compose.yml
+- **Images are multi-stage** for optimal production size
+
+## Related Skills
+
+- [Local Development Setup](./local-development.md) - Alternative non-Docker setup
+- [Production Readiness](./production-readiness.md) - Validation before deployment
+- [Debug Service](./debug-service.md) - Troubleshooting running services
--- a/AI.dev/SKILLS/generate-store-assets.md
+++ b/AI.dev/SKILLS/generate-store-assets.md
@ -0,0 +1,258 @@
+# Generate Store Assets Skill
+
+**Description**: Programmatically generate all app store artwork (icons, screenshots, feature graphics) from a single script.
+
+## When to Use
+
+- Preparing for app store releases
+- Updating app branding
+- Creating assets for multiple platforms
+- Maintaining consistent design across stores
+
+## Prerequisites
+
+- Python 3.7+ with Pillow library
+- App name and branding decided
+- Color palette chosen
+
+## Quick Start
+
+```bash
+# From repo root
+python3 assets/generate-store-assets.py
+```
+
+## Output Overview
+
+The script generates **73 PNG files** across multiple categories:
+
+| Category        | Count | Directory                                             | Platforms                                                  |
+| --------------- | ----- | ----------------------------------------------------- | ---------------------------------------------------------- |
+| App Icons       | 36    | `assets/store/icons/`                                 | iOS (13), Android (6), macOS (7), Windows (5), Favicon (5) |
+| Screenshots     | 32    | `assets/store/screenshots/{ios,android,mac,windows}/` | 4 screens × dark + light themes                            |
+| Feature Graphic | 1     | `assets/store/feature/`                               | Google Play Store                                          |
+| Splash Screens  | 4     | `assets/store/splash/`                                | Android splash screens                                     |
+
+## Customization
+
+### 1. Color Palette
+
+Edit the color variables at the top of `assets/generate-store-assets.py`:
+
+```python
+# Default colors
+GREEN_PRIMARY = "#2E7D32"      # Icon circle, badges, section headers
+GREEN_ACCENT = "#50FA7B"        # Glowing text, active tabs, highlights
+DARK_BG = "#1E1E2E"             # Dark mode background
+DARK_SURFACE = "#282A36"       # Cards, inputs, tab bar
+MUTED = "#6272A4"               # Secondary text, timestamps
+CYAN = "#8BE9FD"                # Transcript card accents
+```
+
+After changing colors, re-run the script to regenerate all assets.
+
+### 2. App Icon Design
+
+The icon features a waveform-in-circle with green glow:
+
+```python
+# Key parameters in generate_app_icon()
+circle_radius = size * 0.28
+corner_radius = size * 0.22
+num_bars = 7
+waveform_heights = [0.3, 0.5, 0.75, 1.0, 0.75, 0.5, 0.3]
+glow_rings = 8  # Number of concentric glow rings
+```
+
+### 3. Screenshot Content
+
+Each screenshot function uses sample data. Edit these functions:
+
+```python
+def generate_screenshot_home():
+    # Customize: greeting, stats, activity list
+    greeting = "Good afternoon, Sarah"
+    stats = {"words": "12,543", "time": "2h 15m", "sessions": 8}
+
+def generate_screenshot_record():
+    # Customize: timer display, live preview
+    timer = "00:47"
+    preview_text = "Meeting notes from the product review..."
+
+def generate_screenshot_history():
+    # Customize: transcript cards
+    transcripts = [
+        {"title": "Product Review", "date": "Today", "words": 1250},
+        {"title": "Team Standup", "date": "Yesterday", "words": 340}
+    ]
+
+def generate_screenshot_settings():
+    # Customize: profile and settings sections
+    profile = {"name": "Sarah Chen", "email": "sarah@example.com", "plan": "Pro"}
+```
+
+## Platform-Specific Requirements
+
+### iOS Icons
+
+- 1024x1024 (App Store)
+- 180x180 (iPhone @3x)
+- 120x120 (iPhone @2x)
+- 167x167 (iPad Pro @2x)
+- 152x152 (iPad @2x)
+- 87x87 (Settings @3x)
+- 58x58 (Settings @2x)
+- 60x60 (Notifications @3x)
+- 40x40 (Notifications @2x)
+- 80x80 (Spotlight @2x)
+- 40x40 (Spotlight @1x)
+- 20x20 (Settings @1x)
+
+### Android Icons
+
+- 512x512 (Google Play Store)
+- 192x192 (adaptive foreground)
+- 432x432 (adaptive background)
+- 144x144 (xxxhdpi)
+- 96x96 (xxhdpi)
+- 72x72 (xhdpi)
+- 48x48 (mdpi)
+
+### Additional Sizes
+
+- macOS: 16x16 to 1024x1024
+- Windows: 16x16 to 256x256
+- Favicon: 16x16, 32x32, 96x96, 192x192
+
+## Screenshot Specifications
+
+### Dimensions
+
+- **iOS**: 1242x2688 (iPhone X/11/12/13) and 2048x2732 (iPad Pro)
+- **Android**: 1080x1920 (phone) and 2048x2732 (tablet)
+- **macOS**: 1280x800 (Mac App Store)
+- **Windows**: 1366x768 (Microsoft Store)
+
+### Themes
+
+- **Light mode**: Light background, dark text
+- **Dark mode**: Dark background, light text
+- Both generated automatically
+
+## Automation Script
+
+Create `scripts/update-store-assets.sh`:
+
+```bash
+#!/bin/bash
+# Update store assets after design changes
+
+echo "Generating store assets..."
+python3 assets/generate-store-assets.py
+
+echo "Verifying output..."
+find assets/store -name "*.png" | wc -l
+
+echo "Opening directory for review..."
+open assets/store
+
+echo "Done! Review assets before committing."
+```
+
+## Integration with CI/CD
+
+### GitHub Actions
+
+```yaml
+name: Generate Store Assets
+on:
+  push:
+    paths:
+      - 'assets/generate-store-assets.py'
+      - 'assets/store/**'
+
+jobs:
+  generate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
+
+      - name: Install dependencies
+        run: pip install Pillow
+
+      - name: Generate assets
+        run: python3 assets/generate-store-assets.py
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v3
+        with:
+          name: store-assets
+          path: assets/store/
+```
+
+## Best Practices
+
+### Design Guidelines
+
+1. **Keep it simple** - Icons should be recognizable at small sizes
+2. **High contrast** - Ensure visibility on various backgrounds
+3. **Brand consistency** - Use consistent colors across all assets
+4. **Text readability** - Use large, clear fonts in screenshots
+
+### Technical Tips
+
+1. **Vector when possible** - Consider SVG for icons (convert to PNG)
+2. **Optimize file size** - Use compression without quality loss
+3. **Test on devices** - Verify how assets look on actual devices
+4. **Version control** - Commit generated assets or regenerate on build
+
+## Common Issues
+
+### Script Won't Run
+
+```bash
+# Install Pillow
+pip install Pillow
+
+# Check Python version (3.7+)
+python --version
+```
+
+### Icons Look Blurry
+
+- Ensure you're generating at the correct resolution
+- Check if the source images are high quality
+- Verify anti-aliasing settings in the script
+
+### Colors Don't Match
+
+- Colors must be in hex format (#RRGGBB)
+- Ensure consistent color space (sRGB)
+- Check gamma correction settings
+
+## Before Release Checklist
+
+- [ ] All 73 assets generated successfully
+- [ ] Icons look good at all sizes
+- [ ] Screenshots show current UI
+- [ ] No placeholder text remains
+- [ ] Dark/light themes both look good
+- [ ] Text is readable in all screenshots
+- [ ] App name is correct in all contexts
+- [ ] Brand colors are consistent
+
+## Notes
+
+- **Single source of truth** - The Python script is the only place to make changes
+- **Regenerate often** - Run after any UI changes
+- **Store requirements change** - Check platform guidelines periodically
+- **Test on actual devices** - Simulators don't always match real devices
+
+## Related Skills
+
+- [Desktop Release](./desktop-release.md) - Packaging with assets
+- [iOS Release](./ios-release.md) - App Store submission
+- [Android Development](./android-development.md) - Android-specific assets
--- a/AI.dev/SKILLS/index.md
+++ b/AI.dev/SKILLS/index.md
@ -0,0 +1,109 @@
+# Skills Index
+
+## 🏗️ Architecture & Setup
+
+- [Architecture Patterns](./architecture-patterns.md) - Common architectural patterns and structures
+- [Monorepo Management](./monorepo-management.md) - Managing multi-repo workspaces
+
+## 🔧 Development Workflows
+
+- [Debug Service](./debug-service.md) - Systematic debugging methodology
+- [Local Development Setup](./local-development.md) - Starting services locally
+- [Docker Compose](./docker-compose.md) - Full stack containerization
+- [Production Readiness](./production-readiness.md) - Pre-release validation
+
+## 📱 Mobile Development
+
+- [Mobile Code Quality](./mobile-code-quality.md) - Cross-platform mobile standards
+- [iOS Development](./ios-development.md) - SwiftUI + Xcode patterns
+- [Android Development](./android-development.md) - Kotlin + Jetpack Compose
+- [KMP Development](./kmp-development.md) - Kotlin Multiplatform best practices
+
+## 🚀 Release & Deployment
+
+- [Desktop Release](./desktop-release.md) - Cross-platform desktop packaging
+- [iOS Release](./ios-release.md) - TestFlight and App Store deployment
+- [Service Deployment](./service-deployment.md) - Microservice deployment
+- [Dashboard Deployment](./dashboard-deployment.md) - Next.js production deployment
+- [Generate Store Assets](./generate-store-assets.md) - App store artwork generation
+
+## 🧪 Testing & Quality
+
+- [Test Strategies](./test-strategies.md) - Unit, integration, and E2E testing
+- [Test Desktop App](./test-desktop-app.md) - Desktop application testing
+- [Test iOS App](./test-ios-app.md) - iOS simulator testing
+- [Code Quality](./code-quality.md) - Linting, formatting, static analysis
+- [Security Auditing](./security-auditing.md) - Security checks and best practices
+- [Performance Monitoring](./performance-monitoring.md) - Metrics and performance budgets
+
+## 📚 Documentation & Communication
+
+- [Update Agent Documentation](./update-agent-docs.md) - AI assistant documentation
+- [Scan Repo Context](./scan-repo-context.md) - Generate comprehensive project context
+- [API Documentation](./api-documentation.md) - REST API documentation patterns
+- [Architecture Documentation](./architecture-documentation.md) - System design docs
+- [Onboarding Documentation](./onboarding-documentation.md) - Developer onboarding
+
+## 🔍 Quick Reference
+
+| Need                  | Skill                                                | Location                         |
+| --------------------- | ---------------------------------------------------- | -------------------------------- |
+| Fix a failing service | [Debug Service](./debug-service.md)                  | 🔧 Development Workflows         |
+| Prepare for release   | [Production Readiness](./production-readiness.md)    | 🧪 Testing & Quality             |
+| Start all services    | [Local Development Setup](./local-development.md)    | 🔧 Development Workflows         |
+| Release desktop app   | [Desktop Release](./desktop-release.md)              | 🚀 Release & Deployment          |
+| Release iOS app       | [iOS Release](./ios-release.md)                      | 🚀 Release & Deployment          |
+| Generate store assets | [Generate Store Assets](./generate-store-assets.md)  | 🚀 Release & Deployment          |
+| Mobile code quality   | [Mobile Code Quality](./mobile-code-quality.md)      | 📱 Mobile Development            |
+| Test desktop app      | [Test Desktop App](./test-desktop-app.md)            | 🧪 Testing & Quality             |
+| Test iOS app          | [Test iOS App](./test-ios-app.md)                    | 🧪 Testing & Quality             |
+| Update AI docs        | [Update Agent Documentation](./update-agent-docs.md) | 📚 Documentation & Communication |
+| Scan repo for context | [Scan Repo Context](./scan-repo-context.md)          | 📚 Documentation & Communication |
+| Write tests           | [Test Strategies](./test-strategies.md)              | 🧪 Testing & Quality             |
+| Docker full stack     | [Docker Compose](./docker-compose.md)                | 🔧 Development Workflows         |
+| Security audit        | [Security Auditing](./security-auditing.md)          | 🧪 Testing & Quality             |
+| Architecture patterns | [Architecture Patterns](./architecture-patterns.md)  | 🏗️ Architecture & Setup          |
+
+## Skill Levels
+
+### 🟢 Beginner
+
+- [Local Development Setup](./local-development.md)
+- [Debug Service](./debug-service.md)
+- [Test Strategies](./test-strategies.md)
+
+### 🟡 Intermediate
+
+- [Production Readiness](./production-readiness.md)
+- [Docker Compose](./docker-compose.md)
+- [Mobile Code Quality](./mobile-code-quality.md)
+- [Security Auditing](./security-auditing.md)
+
+### 🔴 Advanced
+
+- [Architecture Patterns](./architecture-patterns.md)
+- [Desktop Release](./desktop-release.md)
+- [Service Deployment](./service-deployment.md)
+- [Performance Monitoring](./performance-monitoring.md)
+
+## Contributing
+
+To add a new skill:
+
+1. Create a new markdown file in this directory
+2. Follow the established format (description, when to use, steps, notes)
+3. Add it to this index
+4. Update the README.md
+5. Commit with message: `docs: add <skill-name> skill`
+
+## Tags
+
+Each skill includes tags for easy discovery:
+
+- `#beginner` - Easy to get started
+- `#intermediate` - Requires some experience
+- `#advanced` - Complex topics
+- `#critical` - Essential for production
+- `#automation` - Can be automated
+- `#security` - Security-related
+- `#performance` - Performance-related
--- a/AI.dev/SKILLS/ios-release.md
+++ b/AI.dev/SKILLS/ios-release.md
@ -0,0 +1,314 @@
+# iOS Release Skill
+
+**Description**: Build and upload iOS apps to TestFlight for beta testing and App Store distribution.
+
+## When to Use
+
+- Releasing new iOS beta builds
+- Submitting to the App Store
+- Setting up CI/CD for iOS
+- Managing iOS certificates and provisioning
+
+## Prerequisites
+
+### Required Tools
+
+```bash
+# Install Xcode Command Line Tools
+xcode-select --install
+
+# Install full Xcode from Mac App Store (required for iOS builds)
+
+# Install CocoaPods
+brew install cocoapods
+```
+
+### Apple Developer Account
+
+1. Enroll in [Apple Developer Program](https://developer.apple.com/programs/)
+2. Team ID: `748N7QPX7J` (example)
+3. Bundle ID: `com.yourapp.yourapp`
+
+## Fresh Setup
+
+### 1. Configure Xcode
+
+```bash
+# Open Xcode → Settings → Accounts → + → Apple ID
+# Sign in with your Apple Developer account
+# Xcode auto-downloads provisioning profiles and certificates
+```
+
+### 2. Clone and Setup
+
+```bash
+git clone https://github.com/your-org/your-repo.git
+cd your-repo/mobile_app/ios
+pod install
+cd ../..
+```
+
+## Build and Release Process
+
+### 1. Update Build Number
+
+The build number must be unique for each upload:
+
+```bash
+# Option 1: Let Cascade increment (recommended)
+# The build number is in project.pbxproj under CURRENT_PROJECT_VERSION
+
+# Option 2: Manual update
+open mobile_app/ios/YourApp.xcodeproj
+# Navigate to Target → General → Build
+# Increment Build number (not Version)
+```
+
+### 2. Install Dependencies
+
+```bash
+cd mobile_app/ios && pod install && cd ../..
+```
+
+### 3. Clean Build Folder
+
+```bash
+xcodebuild clean \
+  -workspace mobile_app/ios/YourApp.xcworkspace \
+  -scheme YourApp \
+  -configuration Release
+```
+
+### 4. Archive the App
+
+```bash
+xcodebuild archive \
+  -workspace mobile_app/ios/YourApp.xcworkspace \
+  -scheme YourApp \
+  -configuration Release \
+  -archivePath build/YourApp.xcarchive \
+  -destination 'generic/platform=iOS' \
+  DEVELOPMENT_TEAM=YOUR_TEAM_ID \
+  CODE_SIGN_STYLE=Automatic
+```
+
+### 5. Export and Upload
+
+```bash
+xcodebuild -exportArchive \
+  -archivePath build/YourApp.xcarchive \
+  -exportPath build/export \
+  -exportOptionsPlist scripts/ExportOptions.plist
+```
+
+The `app-store-connect` export method auto-uploads to App Store Connect.
+
+### 6. Configure in App Store Connect
+
+1. Go to [App Store Connect](https://appstoreconnect.apple.com)
+2. Navigate to My Apps → YourApp → TestFlight
+3. Wait 5-15 minutes for processing
+4. Add build to testing group:
+   - **Internal Testing**: Available immediately
+   - **External Testing**: Requires review (~24 hours)
+
+## Alternative: Xcode GUI
+
+1. Open `mobile_app/ios/YourApp.xcworkspace` (not `.xcodeproj`)
+2. Select scheme: **YourApp**
+3. Set destination: **Any iOS Device**
+4. Product → Archive
+5. In Organizer window: Distribute App → App Store Connect → Upload
+
+## Key Configuration Files
+
+### ExportOptions.plist
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>method</key>
+    <string>app-store-connect</string>
+    <key>teamID</key>
+    <string>YOUR_TEAM_ID</string>
+    <key>uploadBitcode</key>
+    <false/>
+    <key>uploadSymbols</key>
+    <true/>
+</dict>
+</plist>
+```
+
+### Podfile
+
+```ruby
+platform :ios, '15.0'
+
+target 'YourApp' do
+  use_frameworks!
+
+  # Azure Speech SDK
+  pod 'AzureSpeech', '~> 1.0'
+
+  target 'YourAppTests' do
+    inherit! :search_paths
+  end
+end
+```
+
+## Build Configuration
+
+| Setting           | Value                 | Location                        |
+| ----------------- | --------------------- | ------------------------------- |
+| Team ID           | `748N7QPX7J`          | Xcode project settings          |
+| Bundle ID         | `com.yourapp.yourapp` | Xcode project settings          |
+| Code Signing      | Automatic             | Target → Signing & Capabilities |
+| Deployment Target | iOS 15.0+             | Podfile/Xcode project           |
+
+## CI/CD Integration
+
+### GitHub Actions
+
+```yaml
+name: Build and Release iOS
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: macos-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Xcode
+        uses: maxim-lobanov/setup-xcode@v1
+        with:
+          xcode-version: latest-stable
+
+      - name: Install CocoaPods
+        run: |
+          cd mobile_app/ios
+          pod install
+          cd ../..
+
+      - name: Build Archive
+        env:
+          DEVELOPMENT_TEAM: ${{ secrets.DEVELOPMENT_TEAM }}
+        run: |
+          xcodebuild archive \
+            -workspace mobile_app/ios/YourApp.xcworkspace \
+            -scheme YourApp \
+            -configuration Release \
+            -archivePath build/YourApp.xcarchive \
+            -destination 'generic/platform=iOS' \
+            DEVELOPMENT_TEAM=$DEVELOPMENT_TEAM \
+            CODE_SIGN_STYLE=Automatic
+
+      - name: Export and Upload
+        env:
+          APPLE_ID: ${{ secrets.APPLE_ID }}
+          APPLE_PASSWORD: ${{ secrets.APPLE_PASSWORD }}
+          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+        run: |
+          xcodebuild -exportArchive \
+            -archivePath build/YourApp.xcarchive \
+            -exportPath build/export \
+            -exportOptionsPlist scripts/ExportOptions.plist
+```
+
+## Troubleshooting
+
+### Common Issues and Solutions
+
+| Problem                       | Solution                                                                 |
+| ----------------------------- | ------------------------------------------------------------------------ |
+| "No signing certificate"      | Xcode → Settings → Accounts → Manage Certificates → + Apple Distribution |
+| "Provisioning profile" error  | Xcode → Target → Signing → Enable "Automatically manage signing"         |
+| "Build number already exists" | Increment build number in Xcode project                                  |
+| Upload stuck at "Processing"  | Check [Apple System Status](https://developer.apple.com/system-status/)  |
+| "Invalid bundle"              | Verify Bundle ID matches App Store Connect                               |
+| Pod install fails             | Run `pod deintegrate` then `pod install`                                 |
+| Archive fails                 | Clean build folder, check for linking errors                             |
+
+### Debug Commands
+
+```bash
+# Validate app before upload
+xcrun altool --validate-app \
+  -f build/export/YourApp.ipa \
+  -t ios \
+  -u your@email.com \
+  -p @keychain:AC_PASSWORD
+
+# Check upload status
+xcrun altool --notarization-info <request-uuid> \
+  -u your@email.com \
+  -p @keychain:AC_PASSWORD
+
+# List available provisioning profiles
+ls ~/Library/MobileDevice/Provisioning\ Profiles/
+```
+
+## Best Practices
+
+### Version Management
+
+- Use semantic versioning: `MAJOR.MINOR.PATCH`
+- Increment build number for every upload
+- Keep release notes in App Store Connect
+
+### Testing Before Release
+
+1. **Internal Testing** - Test with team first
+2. **External Testing** - Select beta testers
+3. **TestFlight Groups** - Organize testers by type
+4. **Feedback Collection** - Use TestFlight feedback
+
+### Release Checklist
+
+- [ ] Build number incremented
+- [ ] All tests passing
+- [ ] Release notes written
+- [ ] Screenshots updated (all device sizes)
+- [ ] App metadata current
+- [ ] Privacy policy updated
+- [ ] Age rating appropriate
+- [ ] In-app purchases configured (if applicable)
+
+## App Store Submission
+
+### From TestFlight to Production
+
+1. Ensure TestFlight build is stable
+2. Create new app version in App Store Connect
+3. Select build from TestFlight
+4. Complete app review information
+5. Submit for Review
+
+### Review Process
+
+- **Average time**: 24-48 hours
+- **Common rejections**: Metadata issues, crashes, guideline violations
+- **Expedited review**: Available for critical bug fixes
+
+## Notes
+
+- **Always test on real devices** - Simulators can miss issues
+- **Keep certificates secure** - Never commit .p12 files
+- **Monitor expiration dates** - Certificates expire annually
+- **Use app-specific passwords** - For Apple ID authentication
+- **Backup provisioning profiles** - Export from Xcode
+
+## Related Skills
+
+- [Generate Store Assets](./generate-store-assets.md) - Create required screenshots
+- [Mobile Code Quality](./mobile-code-quality.md) - Before release
+- [Desktop Release](./desktop-release.md) - Cross-platform releases
+- [Test iOS App](./test-ios-app.md) - Local testing
--- a/AI.dev/SKILLS/local-development.md
+++ b/AI.dev/SKILLS/local-development.md
@ -0,0 +1,226 @@
+# Local Development Setup Skill
+
+**Description**: Start and manage all backend services locally for development and testing.
+
+## When to Use
+
+- Setting up a new development machine
+- Starting work on a feature that spans multiple services
+- Running integration tests locally
+- Demonstrating the full system
+
+## Prerequisites
+
+- All repos cloned to `/Users/sd9235/code/mygh/`
+- Python 3.12+ with virtual environment
+- Node.js 20+
+- pnpm installed globally
+- `.env` files configured with necessary secrets
+
+## Quick Start
+
+```bash
+cd /Users/sd9235/code/mygh/learning_voice_ai_agent
+
+# Start all 8 services at once
+./run-local-all-services.sh start
+
+# Verify all services are running
+./run-local-all-services.sh status
+```
+
+## Service URLs and Details
+
+| Service                    | URL                   | Log File                      | Process | Port |
+| -------------------------- | --------------------- | ----------------------------- | ------- | ---- |
+| Backend API (FastAPI)      | http://localhost:8000 | `.logs/backend.log`           | Python  | 8000 |
+| Growth Service (Fastify)   | http://localhost:4001 | `.logs/growth-service.log`    | Node.js | 4001 |
+| Billing Service (Fastify)  | http://localhost:4002 | `.logs/billing-service.log`   | Node.js | 4002 |
+| Platform Service (Fastify) | http://localhost:4003 | `.logs/platform-service.log`  | Node.js | 4003 |
+| Admin Dashboard            | http://localhost:3001 | `.logs/admin-dashboard.log`   | Next.js | 3001 |
+| User Dashboard             | http://localhost:3002 | `.logs/user-dashboard.log`    | Next.js | 3002 |
+| Tracker Service (Fastify)  | http://localhost:4004 | `.logs/tracker-service.log`   | Node.js | 4004 |
+| Tracker Dashboard          | http://localhost:3003 | `.logs/tracker-dashboard.log` | Next.js | 3003 |
+
+## Health Check Commands
+
+```bash
+# Quick health check for all services
+curl -s http://127.0.0.1:8000/health && echo " ✓ Backend"
+curl -s http://127.0.0.1:4001/health && echo " ✓ Growth"
+curl -s http://127.0.0.1:4002/health && echo " ✓ Billing"
+curl -s http://127.0.0.1:4003/health && echo " ✓ Platform"
+curl -s http://127.0.0.1:4004/health && echo " ✓ Tracker"
+
+# Check dashboards (HTTP status codes)
+curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:3001 && echo " ✓ Admin Dashboard"
+curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:3002 && echo " ✓ User Dashboard"
+curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:3003 && echo " ✓ Tracker Dashboard"
+```
+
+## Manual Service Startup
+
+If the script doesn't work, start services manually:
+
+### 1. Common Platform Services
+
+```bash
+cd /Users/sd9235/code/mygh/learning_ai_common_plat
+
+# Growth Service
+cd services/growth-service
+pnpm install
+pnpm dev > /Users/sd9235/code/mygh/learning_voice_ai_agent/.logs/growth-service.log 2>&1 &
+
+# Billing Service
+cd ../billing-service
+pnpm install
+pnpm dev > /Users/sd9235/code/mygh/learning_voice_ai_agent/.logs/billing-service.log 2>&1 &
+
+# Platform Service
+cd ../platform-service
+pnpm install
+pnpm dev > /Users/sd9235/code/mygh/learning_voice_ai_agent/.logs/platform-service.log 2>&1 &
+
+# Tracker Service
+cd ../tracker-service
+pnpm install
+pnpm dev > /Users/sd9235/code/mygh/learning_voice_ai_agent/.logs/tracker-service.log 2>&1 &
+```
+
+### 2. Voice Agent Services
+
+```bash
+cd /Users/sd9235/code/mygh/learning_voice_ai_agent
+
+# Backend API
+cd backend
+source ../.venv/bin/activate
+python -m uvicorn src.main:app --reload --host 0.0.0.0 --port 8000 > ../.logs/backend.log 2>&1 &
+
+# Admin Dashboard
+cd ../admin-dashboard-web
+npm install
+npm run dev > ../.logs/admin-dashboard.log 2>&1 &
+
+# User Dashboard
+cd ../user-dashboard-web
+npm install
+npm run dev > ../.logs/user-dashboard.log 2>&1 &
+
+# Tracker Dashboard
+cd ../tracker-dashboard-web
+npm install
+npm run dev > ../.logs/tracker-dashboard.log 2>&1 &
+```
+
+## Environment Setup
+
+### Required Environment Files
+
+1. **Root `.env`** (learning_voice_ai_agent)
+
+   ```bash
+   COSMOS_ENDPOINT=https://...
+   COSMOS_KEY=...
+   COSMOS_DATABASE=lysnrai
+   JWT_SECRET=...
+   AZURE_SPEECH_KEY=...
+   AZURE_SPEECH_REGION=eastus
+   AZURE_OPENAI_ENDPOINT=...
+   AZURE_OPENAI_KEY=...
+   AZURE_OPENAI_DEPLOYMENT=gpt-4o-mini
+   ```
+
+2. **Dashboard `.env.local`** files
+
+   ```bash
+   # admin-dashboard-web/.env.local
+   COSMOS_ENDPOINT=https://...
+   COSMOS_KEY=...
+   JWT_SECRET=...
+   NEXT_PUBLIC_APP_URL=http://localhost:3001
+
+   # user-dashboard-web/.env.local
+   COSMOS_ENDPOINT=https://...
+   COSMOS_KEY=...
+   JWT_SECRET=...
+   NEXT_PUBLIC_APP_URL=http://localhost:3002
+
+   # tracker-dashboard-web/.env.local
+   TRACKER_API_URL=http://localhost:4004
+   PLATFORM_API_URL=http://localhost:4003
+   JWT_SECRET=...
+   ```
+
+## Log Management
+
+```bash
+# View all logs in real-time
+tail -f .logs/*.log
+
+# View specific service log
+tail -f .logs/backend.log
+
+# Search logs for errors
+grep -i "error\|exception\|failed" .logs/*.log
+
+# Clear all logs
+> .logs/backend.log .logs/growth-service.log .logs/billing-service.log \
+  .logs/platform-service.log .logs/tracker-service.log \
+  .logs/admin-dashboard.log .logs/user-dashboard.log .logs/tracker-dashboard.log
+```
+
+## Stop Services
+
+```bash
+# Stop all services at once
+./run-local-all-services.sh stop
+
+# Or manually kill processes
+pkill -f "uvicorn src.main:app"
+pkill -f "next dev"
+pkill -f "tsx.*src/server.ts"
+```
+
+## Common Issues
+
+### Port Already in Use
+
+```bash
+# Find process using port
+lsof -i :8000
+
+# Kill it
+kill -9 <PID>
+
+# Or use this script to kill all dev ports
+./run-local-all-services.sh stop
+```
+
+### Service Won't Start
+
+1. Check the log file: `tail .logs/<service>.log`
+2. Verify environment variables are set
+3. Ensure dependencies are installed
+4. Check if required ports are available
+
+### Dashboard Can't Connect to Services
+
+1. Verify services are running: `./run-local-all-services.sh status`
+2. Check CORS configuration in services
+3. Verify API URLs in dashboard `.env.local` files
+
+## Development Tips
+
+- **Use the script** - `./run-local-all-services.sh` handles process management and logging
+- **Check logs first** - Most issues have clear error messages in the logs
+- **Restart individual services** - No need to restart everything unless there's a dependency issue
+- **Hot reload** - All services support hot reload for fast development
+- **Use health endpoints** - Quick way to verify services are responding
+
+## Related Skills
+
+- [Debug Service](./debug-service.md) - When something goes wrong
+- [Production Readiness](./production-readiness.md) - Before releasing
+- [Docker Compose](./docker-compose.md) - Alternative containerized setup
--- a/AI.dev/SKILLS/mobile-code-quality.md
+++ b/AI.dev/SKILLS/mobile-code-quality.md
@ -0,0 +1,307 @@
+# Mobile Code Quality Skill
+
+**Description**: Comprehensive code quality checks for native mobile apps (iOS/Swift and Android/Kotlin).
+
+## When to Use
+
+- Before mobile app releases
+- During development sprints
+- In CI/CD pipelines for mobile
+- When onboarding new mobile developers
+
+## Prerequisites
+
+### iOS Development
+
+```bash
+# Install SwiftLint
+brew install swiftlint
+
+# Verify installation
+swiftlint version
+```
+
+### Android Development
+
+```bash
+# Ensure Android SDK is installed
+echo $ANDROID_HOME  # Should point to Android SDK path
+```
+
+## Phase 1: MindLyst Native (Kotlin Multiplatform)
+
+```bash
+cd /Users/sd9235/code/mygh/learning_multimodal_memory_agents/mindlyst-native
+
+# 1. Full project build
+./gradlew build
+# If fails: fix, then git add . && git commit -m "fix(mindlyst): build fixes" && git push
+
+# 2. Kotlin compilation checks
+./gradlew compileKotlinMetadata
+./gradlew :shared:compileKotlinIosSimulatorArm64
+./gradlew :shared:compileKotlinAndroid
+# If fails: fix, commit push
+
+# 3. Kotlin Lint with ktlint
+./gradlew ktlintCheck
+# If fails: auto-fix with ./gradlew ktlintFormat, then git add . && git commit -m "style(mindlyst): ktlint fixes"
+
+# 4. Static Analysis with Detekt
+./gradlew detekt
+# If fails: fix issues, then git add . && git commit -m "fix(mindlyst): detekt issues"
+
+# 5. Unit tests
+./gradlew test
+./gradlew :shared:test
+# If fails: fix, commit push
+```
+
+### Android Specific Checks (if SDK available)
+
+```bash
+./gradlew :androidApp:lintDebug
+./gradlew :androidApp:testDebugUnitTest
+# If fails: fix, commit push
+```
+
+### iOS Specific Checks
+
+```bash
+cd ../iosApp
+
+# SwiftLint check
+swiftlint
+# If fails: auto-fix with swiftlint --fix, then git add . && git commit -m "style(mindlyst): swiftlint fixes"
+
+# Swift format (if configured)
+# swiftformat .
+```
+
+## Phase 2: LysnrAI Mobile Components
+
+```bash
+cd /Users/sd9235/code/mygh/learning_voice_ai_agent/mobile_app
+
+# 1. Android checks
+cd android
+./gradlew build
+./gradlew lintDebug
+./gradlew testDebugUnitTest
+# If fails: fix, commit push
+
+# 2. iOS checks
+cd ../ios/LysnrAI
+xcodebuild -project LysnrAI.xcodeproj -scheme LysnrAI -configuration Debug build
+swiftlint
+# If fails: fix, commit push
+
+# 3. Common checks
+cd ../common
+# Python lint for shared scripts
+python -m ruff check .
+python -m ruff format .
+# If fails: fix, commit push
+```
+
+## Phase 3: Cross-Platform Consistency
+
+### Design Token Synchronization
+
+```bash
+cd /Users/sd9235/code/mygh/learning_multimodal_memory_agents
+
+# Check if tokens are in sync
+./scripts/sync-design-tokens.sh --check
+# If fails: run ./scripts/sync-design-tokens.sh, then git add . && git commit
+```
+
+### Feature Flag Consistency
+
+```bash
+# Verify feature flags are consistent across platforms
+grep -r "FEATURE_" mindlyst-native/shared/src/commonMain/kotlin/
+grep -r "FEATURE_" ../learning_voice_ai_agent/mobile_app/common/
+```
+
+### API Contract Validation
+
+```bash
+# Compare shared API models across platforms
+diff mindlyst-native/shared/src/commonMain/kotlin/api/ \
+     ../learning_voice_ai_agent/mobile_app/common/api/ || echo "API differences found"
+```
+
+## Phase 4: Performance and Security
+
+### Android Performance
+
+```bash
+cd /Users/sd9235/code/mygh/learning_multimodal_memory_agents/mindlyst-native
+
+./gradlew :androidApp:assembleDebug
+
+# Check APK size
+ls -lh androidApp/build/outputs/apk/debug/
+```
+
+### iOS Performance
+
+```bash
+cd ../iosApp
+
+xcodebuild -project LysnrAI.xcodeproj -scheme LysnrAI -configuration Release \
+  -destination 'platform=iOS Simulator,name=iPhone 15' clean build
+```
+
+### Security Scan
+
+```bash
+# Android dependency check
+./gradlew dependencyCheckAnalyze
+
+# iOS (if using mob security)
+# mob security check
+```
+
+## Quality Gates and Metrics
+
+### Coverage Targets
+
+| Platform      | Unit Tests | UI Tests | Coverage          |
+| ------------- | ---------- | -------- | ----------------- |
+| Kotlin Shared | 80%        | N/A      | JaCoCo reports    |
+| Android App   | 70%        | 30%      | Espresso + JUnit  |
+| iOS App       | 70%        | 30%      | XCTest + XCUITest |
+
+### Lint Rules
+
+- **Kotlin**: Official ktlint rules + custom Detekt rules
+- **Swift**: SwiftLint default + custom rules
+- **Android**: Android lint default rules
+
+### Performance Budgets
+
+- **Android APK**: < 50MB
+- **iOS IPA**: < 100MB
+- **Build time**: < 5 minutes
+
+## Automation Scripts
+
+### Setup Script (`scripts/setup-mobile-quality.sh`)
+
+```bash
+#!/bin/bash
+# Install mobile code quality tools
+
+# SwiftLint
+if ! command -v swiftlint &> /dev/null; then
+  brew install swiftlint
+fi
+
+# Kotlin formatting (add to gradle)
+echo "Add ktlint plugin to build.gradle.kts"
+echo "Add detekt plugin to build.gradle.kts"
+```
+
+### Pre-commit Hook (`.husky/pre-commit-mobile`)
+
+```bash
+#!/bin/sh
+# Mobile-specific pre-commit hooks
+
+# Kotlin files
+if git diff --cached --name-only | grep -E "\.kt$"; then
+  cd mindlyst-native
+  ./gradlew ktlintCheck
+  ./gradlew detekt
+fi
+
+# Swift files
+if git diff --cached --name-only | grep -E "\.swift$"; then
+  cd iosApp
+  swiftlint
+fi
+```
+
+## CI/CD Integration
+
+### GitHub Actions Example
+
+```yaml
+name: Mobile Code Quality
+on: [push, pull_request]
+
+jobs:
+  kotlin:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: 17
+      - run: ./gradlew ktlintCheck detekt test
+
+  ios:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: brew install swiftlint
+      - run: cd iosApp && swiftlint
+      - run: xcodebuild -project LysnrAI.xcodeproj -scheme LysnrAI build
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **SwiftLint not found**: Install via Homebrew
+2. **Kotlin lint fails**: Run `./gradlew ktlintFormat` to auto-fix
+3. **Detekt issues**: Check `detekt.yml` configuration
+4. **Android SDK missing**: Set $ANDROID_HOME correctly
+
+### Performance Tips
+
+- Use `--daemon` for Gradle
+- Enable Gradle build cache
+- Use parallel execution where possible
+
+## Reporting
+
+### Generate Quality Report
+
+```bash
+# Combined report
+./gradlew check jacocoTestReport
+open shared/build/reports/jacoco/jacocoTestReport/html/index.html
+
+# Android lint report
+open androidApp/build/reports/lint-results-debug.html
+
+# SwiftLint report (JSON)
+swiftlint --reporter json > swiftlint-report.json
+```
+
+## Commit Patterns
+
+```bash
+fix(mobile): ktlint fixes
+style(ios): swiftlint fixes
+fix(android): lint issues
+test(mobile): add unit tests
+perf(mobile): reduce APK size
+```
+
+## Notes
+
+- **Run before major releases**: Always run full workflow
+- **Incremental checks**: Use pre-commit hooks for immediate feedback
+- **Cross-platform consistency**: Regular sync meetings recommended
+- **Tool versions**: Keep linting tools updated consistently across team
+
+## Related Skills
+
+- [Production Readiness](./production-readiness.md) - Full release validation
+- [Debug Service](./debug-service.md) - When tests fail
+- [Test Strategies](./test-strategies.md) - Writing effective mobile tests
--- a/AI.dev/SKILLS/production-readiness.md
+++ b/AI.dev/SKILLS/production-readiness.md
@ -0,0 +1,225 @@
+# Production Readiness Skill
+
+**Description**: Comprehensive pre-release validation workflow covering all repos with incremental fixes and commits.
+
+## When to Use
+
+- Before any release to production
+- Before major feature deployments
+- As part of regular release cadence
+- When preparing for demos or important presentations
+
+## Prerequisites
+
+- All repos cloned and up to date
+- Appropriate development tools installed (Node.js, Python, etc.)
+- Access to build environments
+
+## Phase 1: Common Platform (learning_ai_common_plat)
+
+```bash
+cd /Users/sd9235/code/mygh/learning_ai_common_plat
+
+# 1. Install dependencies and build
+pnpm install
+pnpm build
+
+# 2. Type-check all packages and services
+pnpm typecheck
+# If fails: fix, then git add . && git commit -m "fix(common): type-check fixes" && git push
+
+# 3. ESLint check
+pnpm lint
+# If fails: fix, then git add . && git commit -m "fix(common): lint fixes" && git push
+
+# 4. Unit tests with coverage (80% threshold)
+pnpm test:coverage
+# If fails: fix, then git add . && git commit -m "test(common): fix failing tests" && git push
+
+# 5. Security audit
+pnpm audit
+# If fails: fix, then git add . && git commit -m "fix(common): security updates" && git push
+
+# 6. Code formatting check
+pnpm format:check
+# If fails: run pnpm format, then git add . && git commit -m "style(common): format fixes" && git push
+
+# 7. Verify package exports
+for pkg in packages/*/dist; do node -e "require('./$pkg/index.js')" 2>/dev/null && echo "✓ $pkg OK" || echo "✗ $pkg FAIL"; done
+# If fails: fix build/exports, commit push
+```
+
+## Phase 2: Voice Agent (learning_voice_ai_agent)
+
+### Dashboard Setup
+
+```bash
+cd /Users/sd9235/code/mygh/learning_voice_ai_agent
+
+# Install dashboards (requires common_plat built)
+cd admin-dashboard-web && npm install
+cd ../user-dashboard-web && npm install
+cd ../tracker-dashboard-web && npm install
+```
+
+### Dashboard Validation
+
+```bash
+# For each dashboard (admin, user, tracker):
+npx tsc --noEmit                    # Type-check
+npm run lint                         # Lint
+npm run format:check                 # Format check
+npm run test:coverage                # Unit tests
+npm run build && npm run build:analyze  # Build + bundle analysis
+npm run size:check                   # Bundle size limits
+npm audit --audit-level moderate     # Security audit
+npm run test:e2e                     # E2E tests
+
+# If any fail: fix, then git add . && git commit -m "fix(<dashboard>): <issue>" && git push
+```
+
+### Python Validation
+
+```bash
+cd /Users/sd9235/code/mygh/learning_voice_ai_agent
+
+# Type checking
+pyright
+# If fails: fix, then git add . && git commit -m "fix(python): type-check fixes" && git push
+
+# Lint and format
+make lint
+# If fails: fix, then git add . && git commit -m "fix(python): lint/format fixes" && git push
+
+# Tests (568 total: 45 desktop + 10 backend)
+python -m pytest tests/ backend/tests/ -v --tb=short
+# If fails: fix, then git add . && git commit -m "test(python): fix failing tests" && git push
+
+# Security audit
+make audit
+# If fails: fix, then git add . && git commit -m "fix(python): security updates" && git push
+```
+
+### Backend API Specific
+
+```bash
+cd backend
+
+# FastAPI type check
+python -m pyright src/
+# If fails: fix, then git add . && git commit -m "fix(backend): type-check fixes" && git push
+
+# Backend lint
+python -m ruff check src/ tests/
+# If fails: fix, then git add . && git commit -m "fix(backend): lint fixes" && git push
+```
+
+### Desktop App (Optional)
+
+```bash
+cd /Users/sd9235/code/mygh/learning_voice_ai_agent
+
+# Build verification (resource-intensive)
+bash scripts/build.sh
+# If fails: fix, then git add . && git commit -m "fix(desktop): build fixes" && git push
+```
+
+## Phase 3: MindLyst (learning_multimodal_memory_agents)
+
+```bash
+cd /Users/sd9235/code/mygh/learning_multimodal_memory_agents/mindlyst-native
+
+# 1. Install and build
+./gradlew build
+# If fails: fix, then git add . && git commit -m "fix(mindlyst): build fixes" && git push
+
+# 2. KMP compile check
+./gradlew :shared:compileKotlinIosSimulatorArm64
+# If fails: fix, then git add . && git commit -m "fix(mindlyst): KMP compile fixes" && git push
+
+# 3. Android compile (if SDK available)
+# ./gradlew :androidApp:compileDebugKotlin
+# If fails: fix, commit push
+
+# 4. Web lint and build
+cd web && npm install && npm run lint
+# If fails: fix, then git add . && git commit -m "fix(mindlyst): web lint fixes" && git push
+npm run build
+# If fails: fix, then git add . && git commit -m "fix(mindlyst): web build fixes" && git push
+
+# 5. Unit tests
+cd .. && ./gradlew :shared:test
+# If fails: fix, commit push
+```
+
+## Phase 4: Integration Smoke Test
+
+```bash
+cd /Users/sd9235/code/mygh/learning_voice_ai_agent
+
+# 1. Start all services with Docker
+docker compose up -d
+sleep 10
+docker compose ps
+# If any service fails: fix, commit push in appropriate repo
+
+# 2. Health check
+cd /Users/sd9235/code/mygh/learning_ai_common_plat
+npx tsx services/monitoring/health-check.ts
+# If fails: fix, commit push in common_plat or voice_agent
+
+# 3. Manual dashboard check
+# Open:
+# - http://localhost:3001 (admin)
+# - http://localhost:3002 (user)
+# - http://localhost:3003 (tracker)
+# If any fails: fix, commit push in voice_agent
+
+# 4. Stop services
+cd /Users/sd9235/code/mygh/learning_voice_ai_agent
+docker compose down
+```
+
+## Coverage Summary
+
+| Component                | Type-Check | Lint | Format | Unit Tests | Coverage | Build | Bundle | E2E | Security |
+| ------------------------ | ---------- | ---- | ------ | ---------- | -------- | ----- | ------ | --- | -------- |
+| **common_plat packages** | ✅         | ✅   | ✅     | ✅         | ✅       | ✅    | ❌     | ❌  | ✅       |
+| **common_plat services** | ✅         | ✅   | ✅     | ✅         | ✅       | ✅    | ❌     | ❌  | ✅       |
+| **admin-dashboard**      | ✅         | ✅   | ✅     | ✅         | ✅       | ✅    | ✅     | ✅  | ✅       |
+| **user-dashboard**       | ✅         | ✅   | ✅     | ✅         | ✅       | ✅    | ✅     | ✅  | ✅       |
+| **tracker-dashboard**    | ✅         | ✅   | ✅     | ✅         | ✅       | ✅    | ✅     | ✅  | ✅       |
+| **desktop app**          | ✅         | ✅   | ❌     | ✅         | ❌       | ✅    | ❌     | ❌  | ✅       |
+| **backend API**          | ✅         | ✅   | ❌     | ✅         | ❌       | ❌    | ❌     | ❌  | ✅       |
+| **mindlyst shared**      | ✅         | 📱   | 📱     | ✅         | ❌       | ✅    | ❌     | ❌  | ❌       |
+| **mindlyst web**         | ❌         | ✅   | ✅     | ❌         | ❌       | ✅    | ❌     | ❌  | ❌       |
+| **mindlyst android**     | ✅         | 📱   | 📱     | ❌         | ❌       | ✅    | ❌     | ❌  | ❌       |
+| **mindlyst ios**         | ❌         | 📱   | 📱     | ❌         | ❌       | ❌    | ❌     | ❌  | ❌       |
+
+📱 = Available via dedicated mobile workflow
+
+## Commit Message Patterns
+
+```bash
+fix(scope): type-check fixes
+test(scope): fix failing tests
+fix(python): lint/format fixes
+fix(mindlyst): KMP compile fixes
+fix(common): security updates
+style(dashboard): format fixes
+fix(backend): build fixes
+```
+
+## Notes
+
+- **Push after each fix** to keep history clean and avoid merge conflicts
+- **common_plat first** because dashboards depend on its built packages
+- **Coverage reports** generated in `coverage/` directory
+- **Bundle analysis** opens in browser when `ANALYZE=true`
+- **Incremental approach** - fix and commit after each phase to track progress
+
+## Related Skills
+
+- [Debug Service](./debug-service.md) - When something fails
+- [Local Development Setup](./local-development.md) - Running services locally
+- [Docker Compose](./docker-compose.md) - Full stack containerization
--- a/AI.dev/SKILLS/scan-repo-context.md
+++ b/AI.dev/SKILLS/scan-repo-context.md
@ -0,0 +1,397 @@
+# Scan Repo & Update Context Skill
+
+**Description**: Scan entire repository and generate comprehensive context documentation for AI assistants.
+
+## When to Use
+
+- Onboarding new AI assistants or developers
+- After major architectural changes
+- Creating project documentation
+- Setting up Windsurf/Cursor/other AI tools
+
+## Prerequisites
+
+- Full repository access
+- Read permissions on all files
+- Understanding of project structure
+
+## Quick Start
+
+```bash
+# From repo root
+/.windsurf/workflows/scan-repo-and-update-windsurf-context.md
+```
+
+Or run the workflow directly if supported:
+
+```bash
+/windsurf-workflow scan-repo-and-update-windsurf-context
+```
+
+## Scanning Process
+
+### Phase 1: Read Key Documentation
+
+Start with high-level understanding:
+
+```bash
+# Core documentation files
+cat AGENTS.md                    # AI agent guide
+cat README.md                    # Project overview
+cat ARCHITECTURE.md              # Technical architecture
+cat CONTRIBUTING.md              # Contribution guidelines
+cat .windsurfrules              # Windsurf-specific rules
+```
+
+### Phase 2: Understand Project Structure
+
+Scan directory structure:
+
+```bash
+# Get overview
+find . -type d -maxdepth 2 | sort
+
+# Key source directories
+find . -name "src" -type d
+find . -name "lib" -type d
+find . -name "components" -type d
+find . -name "modules" -type d
+
+# Configuration files
+find . -name "package.json" -o -name "Cargo.toml" -o -name "pom.xml" -o -name "build.gradle*"
+```
+
+### Phase 3: Analyze Code Organization
+
+For each major component:
+
+```bash
+# List key files
+ls -la src/
+ls -la lib/
+ls -la components/
+
+# Find main entry points
+find . -name "main.*" -o -name "index.*" -o -name "App.*"
+
+# Find configuration
+find . -name "*.config.*" -o -name "*.env*" -o -name "settings.*"
+```
+
+### Phase 4: Identify Patterns
+
+Look for common patterns:
+
+```bash
+# API routes
+find . -path "*/api/*" -name "*.js" -o -name "*.ts" -o -name "*.py"
+
+# Database models
+find . -name "*model*" -o -name "*schema*" -o -name "*entity*"
+
+# Test files
+find . -name "*test*" -o -name "*spec*"
+
+# Documentation
+find . -name "*.md" -o -name "*.rst" -o -name "*.txt"
+```
+
+## Generating Context Documentation
+
+### Structure Template
+
+```markdown
+# [PROJECT_NAME] Context Documentation
+
+> Auto-generated on: YYYY-MM-DD HH:MM
+> Regenerate with: /scan-repo-and-update-windsurf-context
+
+## Project Summary
+
+[Brief 1-paragraph description of the project]
+
+## Architecture
+
+[High-level architecture overview]
+
+## Module Map
+
+| Module | Purpose                        | Key Files              |
+| ------ | ------------------------------ | ---------------------- |
+| auth   | Authentication & authorization | src/auth/, lib/auth.js |
+| api    | REST API endpoints             | src/api/, routes/      |
+| db     | Database layer                 | src/db/, models/       |
+
+## Technology Stack
+
+- **Frontend**: [Framework], [Language]
+- **Backend**: [Framework], [Language]
+- **Database**: [Database type]
+- **Deployment**: [Platform]
+
+## Key Directories
+```
+
+project-root/
+├── src/ # Main source code
+├── tests/ # Test files
+├── docs/ # Documentation
+├── config/ # Configuration files
+└── scripts/ # Build/utility scripts
+
+````
+
+## Important Files
+| File | Purpose |
+|------|---------|
+| package.json | Dependencies and scripts |
+| .env.example | Environment variables template |
+| docker-compose.yml | Container orchestration |
+| README.md | Project documentation |
+
+## Development Workflow
+1. Setup: [Setup instructions]
+2. Development: [How to run locally]
+3. Testing: [How to run tests]
+4. Deployment: [How to deploy]
+
+## Common Commands
+```bash
+# Install dependencies
+npm install
+
+# Run development server
+npm run dev
+
+# Run tests
+npm test
+
+# Build for production
+npm run build
+````
+
+## Coding Conventions
+
+- [Language 1]: [Conventions]
+- [Language 2]: [Conventions]
+- File naming: [Pattern]
+- Commit messages: [Format]
+
+## API Endpoints
+
+| Method | Path            | Purpose      |
+| ------ | --------------- | ------------ |
+| GET    | /api/health     | Health check |
+| POST   | /api/auth/login | User login   |
+
+## Database Schema
+
+[Key tables/collections and relationships]
+
+## Environment Variables
+
+| Variable | Required? | Description         |
+| -------- | --------- | ------------------- |
+| API_KEY  | Yes       | External API key    |
+| DB_URL   | Yes       | Database connection |
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Problem**: Solution
+2. **Problem**: Solution
+
+### Debug Commands
+
+```bash
+# Check logs
+tail -f logs/app.log
+
+# Debug mode
+DEBUG=1 npm run dev
+```
+
+````
+
+## Implementation for Different Project Types
+
+### JavaScript/TypeScript Project
+
+```bash
+# Scan package.json for dependencies
+cat package.json | jq '.dependencies, .devDependencies'
+
+# Find TypeScript config
+find . -name "tsconfig.json"
+
+# Check for framework-specific files
+ls next.config.js webpack.config.js vite.config.js
+````
+
+### Python Project
+
+```bash
+# Check requirements
+cat requirements.txt pyproject.toml setup.py
+
+# Find Python modules
+find . -name "__init__.py" | head -20
+
+# Check for Django/Flask
+ls manage.py app.py wsgi.py
+```
+
+### Mobile Project (React Native)
+
+```bash
+# Check React Native config
+cat package.json | jq '.dependencies | keys | map(select(contains("react-native")))'
+
+# Find platform-specific code
+ls android/ ios/
+
+# Check for native modules
+ls android/app/src/main/java/ ios/YourApp/
+```
+
+### Java/Kotlin Project
+
+```bash
+# Check Gradle configuration
+cat build.gradle settings.gradle gradle.properties
+
+# Find main source directory
+find . -name "src/main/java"
+
+# Check for Spring Boot
+ls src/main/resources/application*.yml
+```
+
+## Automation Script
+
+Create `scripts/generate-context.sh`:
+
+````bash
+#!/bin/bash
+# Generate context documentation
+
+echo "Scanning repository..."
+PROJECT_NAME=$(basename $(pwd))
+OUTPUT_FILE="WINDSURF_CONTEXT.md"
+
+# Header
+cat > $OUTPUT_FILE << EOF
+# $PROJECT_NAME Context Documentation
+
+> Auto-generated on: $(date)
+> Regenerate with: /scan-repo-and-update-windsurf-context
+
+EOF
+
+# Project summary
+if [ -f "README.md" ]; then
+    echo "## Project Summary" >> $OUTPUT_FILE
+    head -20 README.md >> $OUTPUT_FILE
+    echo "" >> $OUTPUT_FILE
+fi
+
+# Directory structure
+echo "## Directory Structure" >> $OUTPUT_FILE
+echo '```' >> $OUTPUT_FILE
+tree -L 2 -I 'node_modules|.git|dist|build' >> $OUTPUT_FILE
+echo '```' >> $OUTPUT_FILE
+echo "" >> $OUTPUT_FILE
+
+# Dependencies
+if [ -f "package.json" ]; then
+    echo "## Dependencies" >> $OUTPUT_FILE
+    echo '```json' >> $OUTPUT_FILE
+    cat package.json | jq '.dependencies' >> $OUTPUT_FILE
+    echo '```' >> $OUTPUT_FILE
+fi
+
+echo "Context documentation generated: $OUTPUT_FILE"
+````
+
+## Best Practices
+
+### What to Include
+
+1. **Project purpose** - What does this project do?
+2. **Architecture** - How is it structured?
+3. **Key components** - Main modules and their purpose
+4. **Development setup** - How to get started
+5. **Common tasks** - Frequently used commands
+6. **Important patterns** - Coding conventions
+7. **Troubleshooting** - Common issues and solutions
+
+### What to Exclude
+
+1. **Sensitive data** - Never include real keys/passwords
+2. **Temporary files** - build/, dist/, node_modules/
+3. **Personal notes** - Keep it professional
+4. **Outdated information** - Keep it current
+
+### Formatting Tips
+
+1. **Use consistent formatting** - Markdown tables, code blocks
+2. **Include examples** - Show, don't just tell
+3. **Cross-reference** - Link to related sections
+4. **Keep it scannable** - Use headings, lists, bold text
+
+## Integration with AI Tools
+
+### Windsurf
+
+The generated `WINDSURF_CONTEXT.md` is automatically picked up by Windsurf.
+
+### Cursor
+
+Add to `.cursorrules`:
+
+```
+Always reference WINDSURF_CONTEXT.md for project understanding
+```
+
+### GitHub Copilot
+
+Include in `.github/copilot-instructions.md`:
+
+```markdown
+## Project Context
+
+See WINDSURF_CONTEXT.md for full project understanding
+```
+
+## Maintenance
+
+### When to Update
+
+- After major feature additions
+- When architecture changes
+- On regular schedule (monthly/quarterly)
+- When new developers join
+
+### Version Control
+
+```bash
+# Commit generated context
+git add WINDSURF_CONTEXT.md
+git commit -m "docs: update AI context documentation"
+git push
+```
+
+## Notes
+
+- **Keep it current** - Outdated context is worse than no context
+- **Be comprehensive** - Include everything a new developer would need
+- **Use examples** - Concrete examples are more helpful than abstract descriptions
+- **Review regularly** - Ensure accuracy and completeness
+
+## Related Skills
+
+- [Update Agent Documentation](./update-agent-docs.md) - For AI-specific docs
+- [Architecture Patterns](./architecture-patterns.md) - Understanding architecture
+- [Local Development Setup](./local-development.md) - Setting up to work
+- [Documentation Standards](./documentation-standards.md) - Writing good docs
--- a/AI.dev/SKILLS/security-auditing.md
+++ b/AI.dev/SKILLS/security-auditing.md
@ -0,0 +1,458 @@
+# Security Auditing Skill
+
+**Description**: Security best practices and audit procedures for full-stack applications.
+
+## When to Use
+
+- Before production deployments
+- After adding new features
+- Regular security reviews
+- Compliance requirements
+
+## Security Checklist
+
+### 🔐 Authentication & Authorization
+
+- [ ] JWT secrets are strong (32+ chars) and rotated regularly
+- [ ] Tokens have appropriate expiration (≤24h for access tokens)
+- [ ] Password hashing uses bcrypt/argon2 with proper salt rounds
+- [ ] Role-based access control (RBAC) is implemented
+- [ ] Admin endpoints require admin role verification
+- [ ] API endpoints validate permissions on every request
+
+### 🔒 Data Protection
+
+- [ ] All sensitive data is encrypted at rest (Cosmos DB)
+- [ ] HTTPS enforced in production
+- [ ] Environment variables contain secrets, never committed
+- [ ] PII data is identified and protected
+- [ ] Database queries use parameterized inputs
+- [ ] Input validation on all endpoints
+
+### 🛡️ API Security
+
+- [ ] CORS properly configured
+- [ ] Rate limiting implemented on public endpoints
+- [ ] Request size limits set
+- [ ] SQL/NoSQL injection protection
+- [ ] XSS protection headers enabled
+- [ ] CSRF protection for state-changing operations
+
+### 📦 Dependencies
+
+- [ ] No known vulnerabilities in dependencies
+- [ ] Dependencies regularly updated
+- [ ] License compliance checked
+- [ ] Supply chain security (SLSA) considered
+
+## Security Auditing Commands
+
+### Python Security Audit
+
+```bash
+# Check for known vulnerabilities
+pip-audit
+
+# Bandit static analysis for security issues
+bandit -r src/ -f json -o bandit-report.json
+
+# Safety check for dependencies
+safety check --json --output safety-report.json
+
+# Semgrep for custom security rules
+semgrep --config=auto src/
+```
+
+### TypeScript/Node.js Security Audit
+
+```bash
+# Audit npm dependencies
+npm audit --audit-level moderate
+
+# Fix vulnerabilities
+npm audit fix
+
+# Snyk for advanced scanning
+npx snyk test --json > snyk-report.json
+
+# eslint-plugin-security for code issues
+npm run lint -- --config .eslintrc.security.js
+```
+
+### Infrastructure Security
+
+```bash
+# Check exposed ports
+nmap -sS -O localhost
+
+# SSL/TLS configuration test
+nmap --script ssl-enum-ciphers -p 443 yourdomain.com
+
+# Docker security scan
+docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
+  aquasec/trivy image your-app:latest
+
+# Terraform security check (if using IaC)
+tfsec .
+```
+
+## Common Security Issues and Fixes
+
+### 1. Hardcoded Secrets
+
+**❌ Bad:**
+
+```typescript
+const apiKey = 'sk-1234567890abcdef';
+```
+
+**✅ Good:**
+
+```typescript
+const apiKey = process.env.API_KEY;
+if (!apiKey) throw new Error('API_KEY required');
+```
+
+### 2. SQL/NoSQL Injection
+
+**❌ Bad:**
+
+```typescript
+const query = `SELECT * FROM users WHERE email = '${email}'`;
+```
+
+**✅ Good:**
+
+```typescript
+const query = 'SELECT * FROM users WHERE email = ?';
+const result = await db.query(query, [email]);
+```
+
+### 3. XSS Prevention
+
+**❌ Bad:**
+
+```typescript
+div.innerHTML = userContent;
+```
+
+**✅ Good:**
+
+```typescript
+div.textContent = userContent;
+// or use a sanitization library
+div.innerHTML = DOMPurify.sanitize(userContent);
+```
+
+### 4. Insecure Direct Object Reference
+
+**❌ Bad:**
+
+```typescript
+app.get('/api/users/:id', async (req, res) => {
+  const user = await getUserById(req.params.id);
+  res.json(user);
+});
+```
+
+**✅ Good:**
+
+```typescript
+app.get('/api/users/:id', async (req, res) => {
+  if (req.user.id !== req.params.id && !req.user.isAdmin) {
+    return res.status(403).json({ error: 'Forbidden' });
+  }
+  const user = await getUserById(req.params.id);
+  res.json(user);
+});
+```
+
+## Security Headers
+
+### Implement in Fastify
+
+```typescript
+import fastifyHelmet from '@fastify/helmet';
+
+await server.register(fastifyHelmet, {
+  contentSecurityPolicy: {
+    directives: {
+      defaultSrc: ["'self'"],
+      styleSrc: ["'self'", "'unsafe-inline'"],
+      scriptSrc: ["'self'"],
+      imgSrc: ["'self'", 'data:', 'https:'],
+    },
+  },
+  hsts: {
+    maxAge: 31536000,
+    includeSubDomains: true,
+    preload: true,
+  },
+});
+```
+
+### Implement in Next.js
+
+```typescript
+// next.config.js
+const securityHeaders = [
+  {
+    key: 'X-DNS-Prefetch-Control',
+    value: 'on',
+  },
+  {
+    key: 'Strict-Transport-Security',
+    value: 'max-age=63072000; includeSubDomains; preload',
+  },
+  {
+    key: 'X-XSS-Protection',
+    value: '1; mode=block',
+  },
+  {
+    key: 'X-Frame-Options',
+    value: 'DENY',
+  },
+  {
+    key: 'X-Content-Type-Options',
+    value: 'nosniff',
+  },
+];
+
+module.exports = {
+  async headers() {
+    return [
+      {
+        source: '/(.*)',
+        headers: securityHeaders,
+      },
+    ];
+  },
+};
+```
+
+## Rate Limiting
+
+### Fastify Implementation
+
+```typescript
+import rateLimit from '@fastify/rate-limit';
+
+await server.register(rateLimit, {
+  max: 100, // 100 requests
+  timeWindow: '1 minute', // per minute
+  errorResponseBuilder: (request, context) => ({
+    code: 'RATE_LIMIT_EXCEEDED',
+    error: 'Too many requests',
+    retryAfter: context.ttl,
+  }),
+});
+
+// Stricter limits for auth endpoints
+await server.register(rateLimit, {
+  max: 5,
+  timeWindow: '15 minutes',
+  hook: 'preHandler',
+  routes: ['/api/auth/login', '/api/auth/register'],
+});
+```
+
+## Environment Security
+
+### .env File Template
+
+```bash
+# .env.example (committed)
+COSMOS_ENDPOINT=
+COSMOS_KEY=
+JWT_SECRET=
+AZURE_SPEECH_KEY=
+AZURE_OPENAI_KEY=
+
+# .env.local (gitignored)
+COSMOS_ENDPOINT=https://your-cosmos.documents.azure.com:443/
+COSMOS_KEY=your-actual-key-here
+JWT_SECRET=your-super-secret-jwt-key-32-chars
+AZURE_SPEECH_KEY=your-speech-key
+AZURE_OPENAI_KEY=your-openai-key
+```
+
+### Git Hooks for Security
+
+```bash
+#!/bin/sh
+# .husky/pre-commit
+# Prevent committing secrets
+
+# Check for potential secrets
+if git diff --cached --name-only | xargs grep -l "password\|secret\|key" 2>/dev/null; then
+  echo "⚠️  Warning: Possible secrets detected in staged files"
+  echo "Please review and ensure no actual secrets are committed"
+  exit 1
+fi
+
+# Check for .env files
+if git diff --cached --name-only | grep -E "\.env$"; then
+  echo "❌ Error: .env files should not be committed"
+  exit 1
+fi
+```
+
+## OWASP Top 10 Mitigations
+
+### 1. Broken Access Control
+
+- Implement proper authorization checks
+- Use RBAC with least privilege
+- Validate permissions on every request
+
+### 2. Cryptographic Failures
+
+- Use strong encryption algorithms
+- Proper key management
+- Hash passwords with bcrypt/argon2
+
+### 3. Injection
+
+- Use parameterized queries
+- Validate and sanitize inputs
+- Use ORMs with built-in protection
+
+### 4. Insecure Design
+
+- Implement security by design
+- Use threat modeling
+- Secure default configurations
+
+### 5. Security Misconfiguration
+
+- Remove default credentials
+- Disable unused features
+- Keep software updated
+
+### 6. Vulnerable Components
+
+- Regular dependency updates
+- Vulnerability scanning
+- Use trusted sources
+
+### 7. Authentication Failures
+
+- Multi-factor authentication
+- Strong password policies
+- Account lockout mechanisms
+
+### 8. Data Integrity Failures
+
+- Digital signatures
+- Checksums
+- Immutable audit logs
+
+### 9. Security Logging Failures
+
+- Comprehensive logging
+- Monitor for suspicious activity
+- Protect log integrity
+
+### 10. Server-Side Request Forgery (SSRF)
+
+- Validate URLs
+- Allowlist destinations
+- Network segmentation
+
+## Security Testing
+
+### Automated Security Tests
+
+```typescript
+// tests/security/auth.test.ts
+describe('Security', () => {
+  it('should reject requests without token', async () => {
+    const response = await app.inject({
+      method: 'GET',
+      url: '/api/protected',
+    });
+
+    expect(response.statusCode).toBe(401);
+  });
+
+  it('should reject invalid tokens', async () => {
+    const response = await app.inject({
+      method: 'GET',
+      url: '/api/protected',
+      headers: {
+        authorization: 'Bearer invalid.token.here',
+      },
+    });
+
+    expect(response.statusCode).toBe(401);
+  });
+
+  it('should prevent SQL injection', async () => {
+    const maliciousInput = "'; DROP TABLE users; --";
+    const response = await app.inject({
+      method: 'POST',
+      url: '/api/search',
+      payload: { query: maliciousInput },
+    });
+
+    expect(response.statusCode).toBe(400);
+  });
+});
+```
+
+### Penetration Testing Checklist
+
+- [ ] Authentication bypass attempts
+- [ ] Authorization testing
+- [ ] Input validation fuzzing
+- [ ] Session management testing
+- [ ] Error disclosure analysis
+- [ ] Business logic flaws
+
+## Incident Response
+
+### Security Incident Plan
+
+1. **Detection**
+   - Monitor security tools
+   - Review logs regularly
+   - Set up alerts
+
+2. **Assessment**
+   - Determine scope
+   - Classify severity
+   - Document findings
+
+3. **Containment**
+   - Isolate affected systems
+   - Change credentials
+   - Block malicious IPs
+
+4. **Eradication**
+   - Remove malware
+   - Patch vulnerabilities
+   - Clean data
+
+5. **Recovery**
+   - Restore from backup
+   - Monitor for recurrence
+   - Update defenses
+
+6. **Post-mortem**
+   - Document lessons learned
+   - Update processes
+   - Train team
+
+## Notes
+
+- **Security is ongoing** - Not a one-time task
+- **Defense in depth** - Multiple layers of security
+- **Principle of least privilege** - Minimum access necessary
+- **Regular audits** - Schedule and perform regularly
+- **Stay informed** - Keep up with security news
+
+## Related Skills
+
+- [Production Readiness](./production-readiness.md) - Security is part of readiness
+- [Debug Service](./debug-service.md) - Security issues debugging
+- [Test Strategies](./test-strategies.md) - Security testing
--- a/AI.dev/SKILLS/test-desktop-app.md
+++ b/AI.dev/SKILLS/test-desktop-app.md
@ -0,0 +1,409 @@
+# Test Desktop App Skill
+
+**Description**: Run and test desktop applications locally during development.
+
+## When to Use
+
+- Developing new desktop features
+- Verifying fixes before release
+- Manual testing workflows
+- Debugging desktop-specific issues
+
+## Prerequisites
+
+### Environment Setup
+
+- Backend services running (if applicable)
+- Python 3.12+ with virtual environment
+- Required platform-specific dependencies
+- Configuration files with necessary secrets
+
+### LysnrAI Desktop Specific
+
+```bash
+# Backend must be running
+./run-local-all-services.sh start
+
+# Verify backend health
+curl http://127.0.0.1:8000/health
+
+# Azure credentials required
+ls ~/.lysnrai/.env  # Must contain AZURE_SPEECH_KEY, AZURE_OPENAI_KEY, etc.
+```
+
+## Testing Workflow
+
+### 1. Prepare Environment
+
+```bash
+# Activate virtual environment
+source .venv/bin/activate
+
+# Or create if doesn't exist
+python3 -m venv .venv
+source .venv/bin/activate
+
+# Install dependencies
+pip install -r requirements.txt
+```
+
+### 2. Verify Configuration
+
+```bash
+# Check environment file
+ls ~/.lysnrai/.env || echo "Missing env file"
+
+# Verify required variables
+grep -E "AZURE_SPEECH_KEY|AZURE_OPENAI_KEY" ~/.lysnrai/.env
+```
+
+### 3. Launch Application
+
+```bash
+# Python desktop app
+python3 -m src.main
+
+# Or with specific module
+python src/main.py
+
+# For Electron apps
+npm run dev
+
+# For Qt apps
+python main.py
+```
+
+### 4. Test Core Functionality
+
+Create a test checklist:
+
+#### Basic Functionality
+
+- [ ] Application window opens correctly
+- [ ] Menu bar/toolbar appears
+- [ ] App icon shows in dock/taskbar
+- [ ] Window can be resized and moved
+
+#### Authentication
+
+- [ ] Login/registration flow works
+- [ ] License key activation (if applicable)
+- [ ] Session persistence
+- [ ] Logout functionality
+
+#### Core Features
+
+- [ ] Main feature works (e.g., dictation, recording)
+- [ ] Settings panel opens and saves
+- [ ] File operations (save/load)
+- [ ] Keyboard shortcuts work
+
+#### Platform Integration
+
+- [ ] Menu bar integration (macOS)
+- [ ] System tray icon (Windows/Linux)
+- [ ] Global hotkeys
+- [ ] Notifications
+
+### 5. Platform-Specific Testing
+
+#### macOS
+
+```bash
+# Test menu bar integration
+# Verify Fn/Globe key works (if applicable)
+# Check sandboxing permissions
+# Test Notarization (if signed)
+
+# macOS specific checks
+spctl -a -v /Applications/YourApp.app
+codesign -dv --verbose=4 /Applications/YourApp.app
+```
+
+#### Windows
+
+```bash
+# Test Windows integration
+# Check registry entries
+# Verify installer works
+# Test auto-startup
+
+# Windows specific checks
+signtool verify /pa YourApp.exe
+```
+
+#### Linux
+
+```bash
+# Test Linux integration
+# Verify desktop entry
+# Check file associations
+# Test package installation
+
+# Linux specific checks
+desktop-file-validate yourapp.desktop
+```
+
+## Debugging Desktop Apps
+
+### Logging Setup
+
+```python
+# Python logging example
+import structlog
+
+logger = structlog.get_logger()
+
+# In main()
+logger.info("Application starting", version="1.0.0")
+logger.error("Failed to connect", service="backend", error=str(e))
+```
+
+### Common Issues
+
+1. **Application won't start**
+
+   ```bash
+   # Check Python version
+   python --version
+
+   # Check dependencies
+   pip list
+
+   # Run with verbose output
+   python -v src/main.py
+   ```
+
+2. **Backend connection issues**
+
+   ```bash
+   # Verify backend is running
+   curl http://localhost:8000/health
+
+   # Check network configuration
+   netstat -an | grep 8000
+   ```
+
+3. **Permission issues**
+
+   ```bash
+   # macOS: check sandboxing
+   spctl -a -v YourApp.app
+
+   # Check file permissions
+   ls -la ~/.lysnrai/
+   ```
+
+### Debug Mode
+
+```python
+# Add debug flag
+import argparse
+
+parser = argparse.ArgumentParser()
+parser.add_argument('--debug', action='store_true')
+args = parser.parse_args()
+
+if args.debug:
+    logging.basicConfig(level=logging.DEBUG)
+```
+
+## Test Data Management
+
+### Sample Data Setup
+
+```python
+# Create test data directory
+os.makedirs(os.path.expanduser('~/.lysnrai/test_data'), exist_ok=True)
+
+# Sample configuration
+test_config = {
+    "user_id": "test-user-123",
+    "license_key": "LYSNR-TEST-1234-5678",
+    "theme": "dark"
+}
+```
+
+### Reset Test Environment
+
+```bash
+# Clear test data
+rm -rf ~/.lysnrai/test_data
+
+# Reset settings
+rm ~/.lysnrai/settings.json
+
+# Clear logs
+> ~/.lysnrai/app.log
+```
+
+## Automated Testing
+
+### Unit Tests for Desktop
+
+```python
+# tests/test_desktop.py
+import pytest
+from src.main import DesktopApp
+
+class TestDesktopApp:
+    def test_app_initialization(self):
+        app = DesktopApp()
+        assert app.is_initialized
+
+    def test_settings_load(self):
+        app = DesktopApp()
+        settings = app.load_settings()
+        assert 'theme' in settings
+
+    def test_backend_connection(self):
+        app = DesktopApp()
+        assert app.check_backend_health()
+```
+
+### UI Automation (Python)
+
+```python
+# Using PyAutoGUI for UI testing
+import pyautogui
+
+def test_main_window():
+    # Find and click menu
+    pyautogui.click('File', duration=0.25)
+    pyautogui.click('New', duration=0.25)
+
+    # Verify new window
+    assert pyautogui.locateOnScreen('new_window.png')
+```
+
+## Performance Testing
+
+### Memory Usage
+
+```bash
+# Monitor memory usage
+top -pid $(pgrep -f "python.*main.py")
+
+# Or with psutil
+python -c "
+import psutil
+import time
+while True:
+    p = psutil.Process()
+    print(f'Memory: {p.memory_info().rss / 1024 / 1024:.2f} MB')
+    time.sleep(1)
+"
+```
+
+### Startup Time
+
+```python
+import time
+import subprocess
+
+start = time.time()
+subprocess.run(['python', 'src/main.py'])
+startup_time = time.time() - start
+print(f"Startup time: {startup_time:.2f}s")
+```
+
+## Test Documentation
+
+### Test Report Template
+
+```markdown
+# Desktop Test Report
+
+## Environment
+
+- OS: macOS 14.0
+- Python: 3.12.0
+- App Version: 1.0.0
+
+## Test Results
+
+| Feature   | Status | Notes                        |
+| --------- | ------ | ---------------------------- |
+| Launch    | ✅     | Starts in 2.3s               |
+| Login     | ✅     | Works with test account      |
+| Recording | ❌     | Fails without mic permission |
+| Settings  | ✅     | Saves correctly              |
+
+## Issues Found
+
+1. Microphone permission not requested on first launch
+2. High memory usage (~200MB idle)
+
+## Recommendations
+
+1. Add permission request on startup
+2. Investigate memory leak
+```
+
+## CI/CD Integration
+
+### GitHub Actions for Desktop Tests
+
+```yaml
+name: Test Desktop App
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [macos-latest, windows-latest, ubuntu-latest]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v4
+        with:
+          python-version: '3.12'
+
+      - name: Install dependencies
+        run: |
+          pip install -r requirements.txt
+          pip install pytest
+
+      - name: Run unit tests
+        run: pytest tests/test_desktop.py
+
+      - name: Test app launch
+        run: |
+          timeout 10s python -m src.main || true
+          # Check if process started
+          pgrep -f "python.*main.py" && echo "App started successfully"
+```
+
+## Best Practices
+
+### Testing Strategy
+
+1. **Test early, test often** - Run tests after each change
+2. **Automate repetitive tests** - Use scripts for common workflows
+3. **Test on target platforms** - Don't rely on cross-platform behavior
+4. **Document test cases** - Keep track of what needs testing
+
+### Test Environment
+
+1. **Isolate test data** - Use separate directory for tests
+2. **Clean state** - Reset between test runs
+3. **Mock external services** - Don't depend on real APIs
+4. **Version control test data** - Commit test fixtures
+
+## Notes
+
+- **Platform differences matter** - Test on all target platforms
+- **Permissions are critical** - Especially on macOS and Windows
+- **User interaction varies** - Consider different user workflows
+- **Performance matters** - Monitor startup time and memory usage
+
+## Related Skills
+
+- [Desktop Release](./desktop-release.md) - After testing
+- [Debug Service](./debug-service.md) - When tests fail
+- [Production Readiness](./production-readiness.md) - Pre-release testing
+- [Security Auditing](./security-auditing.md) - Security testing
--- a/AI.dev/SKILLS/test-ios-app.md
+++ b/AI.dev/SKILLS/test-ios-app.md
@ -0,0 +1,434 @@
+# Test iOS App Skill
+
+**Description**: Build and test iOS applications in Xcode Simulator during development.
+
+## When to Use
+
+- Developing new iOS features
+- Verifying UI/UX changes
+- Testing platform-specific functionality
+- Debugging iOS-only issues
+
+## Prerequisites
+
+### Environment Setup
+
+- Xcode installed from Mac App Store
+- iOS Simulator available
+- Backend services running (if applicable)
+- Apple Developer account (for device testing)
+
+### Service Dependencies
+
+```bash
+# Start required backend services
+./run-local-all-services.sh start
+
+# Verify backend health
+curl http://127.0.0.1:8000/health
+
+# Check all services
+./run-local-all-services.sh status
+```
+
+## Testing Workflow
+
+### 1. Open Project in Xcode
+
+```bash
+# Navigate to iOS project
+cd mobile_app/ios
+
+# Open the workspace (not project)
+open LysnrAI.xcworkspace
+```
+
+### 2. Configure Build Settings
+
+In Xcode:
+
+- **Scheme**: LysnrAI (or your app name)
+- **Destination**: iPhone 16 Pro Simulator (or preferred device)
+- **Configuration**: Debug (for development)
+
+### 3. Build and Run
+
+**Using Xcode:**
+
+- Press `Cmd+R` to build and run
+- Or Product → Run
+
+**Using Command Line:**
+
+```bash
+# Build
+xcodebuild -workspace LysnrAI.xcworkspace \
+  -scheme LysnrAI \
+  -destination 'platform=iOS Simulator,name=iPhone 16 Pro' \
+  build
+
+# Run
+xcodebuild -workspace LysnrAI.xcworkspace \
+  -scheme LysnrAI \
+  -destination 'platform=iOS Simulator,name=iPhone 16 Pro' \
+  test
+```
+
+### 4. Core Functionality Testing
+
+#### Authentication Flow
+
+```swift
+// Test cases to verify:
+// 1. Registration with valid email/password
+// 2. Registration with invalid data (show errors)
+// 3. Login with existing credentials
+// 4. Login with wrong password (show error)
+// 5. Logout functionality
+// 6. Session persistence
+```
+
+#### Main Features
+
+```swift
+// Verify these screens work:
+// 1. Home screen with personalized greeting
+// 2. Core feature screens (e.g., recording, dashboard)
+// 3. Settings/profile screen
+// 4. Navigation between tabs
+// 5. Form validation throughout
+```
+
+### 5. Platform-Specific Testing
+
+#### iOS Features
+
+- [ ] Push notifications (if enabled)
+- [ ] Background app refresh
+- [ ] Face ID/Touch ID (if implemented)
+- [ ] Dark mode support
+- [ ] Dynamic Type (font scaling)
+- [ ] VoiceOver accessibility
+- [ ] iPad layout (if universal app)
+
+#### Device Testing
+
+```bash
+# List available simulators
+xcrun simctl list devices
+
+# Boot specific simulator
+xcrun simctl boot "iPhone 16 Pro"
+
+# Install app on simulator
+xcrun simctl install "iPhone 16 Pro" build/Build/Products/Debug-iphonesimulator/YourApp.app
+
+# Launch app
+xcrun simctl launch "iPhone 16 Pro" com.yourbundle.yourapp
+```
+
+## Key Testing Areas
+
+### 1. User Interface
+
+- Layout on different screen sizes
+- iPhone vs iPad layout differences
+- Rotation support
+- Keyboard appearance/disappearance
+- Safe area handling
+
+### 2. Network Behavior
+
+- API calls with valid responses
+- Error handling (no network, server errors)
+- Loading states
+- Offline functionality (if any)
+- Request timeout handling
+
+### 3. Data Persistence
+
+- Core Data/UserDefaults saving
+- Data survives app restart
+- Sync with backend (if applicable)
+- Data migration between versions
+
+### 4. Performance
+
+- App startup time
+- Screen transition smoothness
+- Memory usage monitoring
+- Battery drain assessment
+
+## Debugging Tools
+
+### Xcode Debugging
+
+```swift
+// Breakpoints
+// Use lldb commands in console
+// po object - print object description
+// p variable - print variable value
+// expr expression - evaluate expression
+
+// View hierarchy debugging
+// Debug → View Debugging → Capture View Hierarchy
+```
+
+### Console Logging
+
+```swift
+// Structured logging
+import os.log
+
+let logger = Logger(subsystem: "com.yourapp.yourapp", category: "Main")
+
+logger.info("User logged in")
+logger.error("Failed to load data: \(error.localizedDescription)")
+```
+
+### Network Debugging
+
+```swift
+// Use Charles Proxy or Proxyman
+// Or implement network logging
+extension NetworkLogger {
+    static func log(request: URLRequest) {
+        print("🌐 \(request.httpMethod ?? "") \(request.url?.absoluteString ?? "")")
+    }
+}
+```
+
+## Automated Testing
+
+### Unit Tests
+
+```swift
+// Tests/YourAppTests/AuthenticationTests.swift
+import XCTest
+@testable import YourApp
+
+class AuthenticationTests: XCTestCase {
+    var authService: AuthService!
+
+    override func setUp() {
+        super.setUp()
+        authService = AuthService()
+    }
+
+    func testValidLogin() async {
+        let result = await authService.login(email: "test@example.com", password: "password")
+        XCTAssertTrue(result.success)
+    }
+
+    func testInvalidLogin() async {
+        let result = await authService.login(email: "test@example.com", password: "wrong")
+        XCTAssertFalse(result.success)
+    }
+}
+```
+
+### UI Tests
+
+```swift
+// Tests/YourAppUITests/AuthenticationUITests.swift
+import XCTest
+
+class AuthenticationUITests: XCTestCase {
+    override func setUpWithError() throws {
+        continueAfterFailure = false
+    }
+
+    func testLoginFlow() throws {
+        let app = XCUIApplication()
+        app.launch()
+
+        // Tap login button
+        app.buttons["Login"].tap()
+
+        // Enter credentials
+        app.textFields["Email"].typeText("test@example.com")
+        app.secureTextFields["Password"].typeText("password")
+
+        // Submit
+        app.buttons["Sign In"].tap()
+
+        // Verify home screen
+        XCTAssertTrue(app.staticTexts["Welcome"].waitForExistence(timeout: 5))
+    }
+}
+```
+
+### Run Tests
+
+```bash
+# Unit tests
+xcodebuild test -workspace LysnrAI.xcworkspace \
+  -scheme LysnrAI \
+  -destination 'platform=iOS Simulator,name=iPhone 16 Pro'
+
+# UI tests
+xcodebuild test -workspace LysnrAI.xcworkspace \
+  -scheme LysnrAI \
+  -destination 'platform=iOS Simulator,name=iPhone 16 Pro' \
+  -only-testing:LysnrAITests
+```
+
+## Common Issues and Solutions
+
+### Build Issues
+
+| Problem                | Solution                                 |
+| ---------------------- | ---------------------------------------- |
+| "No such module"       | Run `pod install` and clean build        |
+| Code signing errors    | Set automatic signing in target settings |
+| Simulator won't launch | Reset Simulator content and settings     |
+| App crashes on launch  | Check device console logs                |
+
+### Runtime Issues
+
+| Problem               | Solution                         |
+| --------------------- | -------------------------------- |
+| Network requests fail | Check API endpoint configuration |
+| UI not updating       | Verify main thread usage         |
+| Data not persisting   | Check Core Data model version    |
+| Memory leaks          | Use Instruments → Leaks          |
+
+## Performance Testing
+
+### Instruments
+
+```bash
+# Launch with Instruments
+xcrun xctrace open --template Time Profiler
+xcrun xctrace open --template Allocations
+xcrun xctrace open --template Leaks
+```
+
+### Metrics to Track
+
+- App startup time (< 3 seconds)
+- Memory usage (< 100MB typical)
+- CPU usage during tasks
+- Network request times
+- Battery consumption
+
+## Device Testing
+
+### Physical Device Setup
+
+```bash
+# Connect device
+# Trust computer on device
+# Check in Xcode: Window → Devices and Simulators
+
+# Install on device
+xcodebuild -workspace LysnrAI.xcworkspace \
+  -scheme LysnrAI \
+  -destination 'platform=iOS,name=Your iPhone' \
+  install
+```
+
+### Test on Real Devices
+
+- Performance differences
+- Touch ID/Face ID
+- Camera/microphone access
+- Push notifications
+- Background modes
+
+## CI/CD Integration
+
+### GitHub Actions
+
+```yaml
+name: iOS Tests
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: macos-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Xcode
+        uses: maxim-lobanov/setup-xcode@v1
+        with:
+          xcode-version: latest-stable
+
+      - name: Install CocoaPods
+        run: |
+          cd mobile_app/ios
+          pod install
+
+      - name: Run Tests
+        run: |
+          xcodebuild test \
+            -workspace mobile_app/ios/LysnrAI.xcworkspace \
+            -scheme LysnrAI \
+            -destination 'platform=iOS Simulator,name=iPhone 16 Pro'
+```
+
+## Test Documentation
+
+### Test Checklist Template
+
+```markdown
+# iOS Test Report - Version 1.0.0
+
+## Environment
+
+- Xcode: 15.0
+- iOS: 17.0
+- Device: iPhone 16 Pro Simulator
+
+## Test Results
+
+| Feature            | Status | Notes                |
+| ------------------ | ------ | -------------------- |
+| Authentication     | ✅     | All flows working    |
+| Home Screen        | ✅     | Data loads correctly |
+| Settings           | ⚠️     | Dark mode issue      |
+| Push Notifications | ❌     | Not configured       |
+
+## Bugs Found
+
+1. Settings screen crashes in dark mode
+2. Push notification permission not requested
+
+## Next Steps
+
+1. Fix dark mode crash
+2. Implement push permission flow
+```
+
+## Best Practices
+
+### Testing Strategy
+
+1. **Test on multiple devices** - Different screen sizes
+2. **Test iOS versions** - Support current and previous major version
+3. **Use real devices** - Simulators don't catch everything
+4. **Automate regression tests** - Prevent breaking existing features
+
+### Debugging Tips
+
+1. **Use breakpoints effectively** - Conditional breakpoints
+2. **Check console logs** - Both Xcode and device console
+3. **Use view debugger** - Inspect UI hierarchy
+4. **Profile performance** - Don't guess, measure
+
+## Notes
+
+- **Simulator limitations** - Some features differ on real devices
+- **iOS version differences** - Test on minimum supported version
+- **App Store guidelines** - Test against review guidelines
+- **Accessibility matters** - Test with VoiceOver and other accessibility features
+
+## Related Skills
+
+- [iOS Release](./ios-release.md) - After testing
+- [Mobile Code Quality](./mobile-code-quality.md) - Code standards
+- [Test Strategies](./test-strategies.md) - General testing
+- [Debug Service](./debug-service.md) - Troubleshooting
--- a/AI.dev/SKILLS/test-strategies.md
+++ b/AI.dev/SKILLS/test-strategies.md
@ -0,0 +1,509 @@
+# Test Strategies Skill
+
+**Description**: Comprehensive testing patterns and strategies for full-stack applications.
+
+## When to Use
+
+- Writing new tests
+- Setting up testing infrastructure
+- Improving test coverage
+- Debugging test failures
+
+## Testing Pyramid
+
+```
+    E2E Tests (10%)
+   ─────────────────
+  Integration Tests (20%)
+ ─────────────────────────
+Unit Tests (70%)
+```
+
+## Unit Testing
+
+### Python (pytest)
+
+```bash
+# Run all tests
+python -m pytest tests/ -v
+
+# Run specific test file
+python -m pytest tests/test_auth.py -v
+
+# Run with coverage
+python -m pytest tests/ --cov=src --cov-report=html
+
+# Run failing tests first
+python -m pytest tests/ --lf
+
+# Stop on first failure
+python -m pytest tests/ -x
+```
+
+#### Test Structure
+
+```python
+# tests/test_auth.py
+import pytest
+from src.auth import auth_client
+
+class TestAuthClient:
+    def setup_method(self):
+        """Run before each test"""
+        self.client = auth_client.AuthClient()
+
+    def test_login_success(self):
+        """Test successful login"""
+        result = self.client.login("user@example.com", "password")
+        assert result.success is True
+        assert result.token is not None
+
+    def test_login_failure(self):
+        """Test login with wrong password"""
+        result = self.client.login("user@example.com", "wrong")
+        assert result.success is False
+        assert "Invalid credentials" in result.error
+
+    @pytest.mark.asyncio
+    async def test_async_login(self):
+        """Test async login method"""
+        result = await self.client.async_login("user@example.com", "password")
+        assert result.success is True
+```
+
+### TypeScript (Vitest)
+
+```bash
+# Run all tests
+pnpm test
+
+# Run in watch mode
+pnpm test --watch
+
+# Run with coverage
+pnpm test --coverage
+
+# Run specific test file
+pnpm test auth.test.ts
+```
+
+#### Test Structure
+
+```typescript
+// src/modules/auth/__tests__/auth.test.ts
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { AuthService } from '../service';
+
+describe('AuthService', () => {
+  let service: AuthService;
+
+  beforeEach(() => {
+    service = new AuthService();
+  });
+
+  it('should validate JWT token', async () => {
+    const token = 'valid.jwt.token';
+    const result = await service.validateToken(token);
+    expect(result.valid).toBe(true);
+    expect(result.userId).toBe('user123');
+  });
+
+  it('should reject invalid token', async () => {
+    const token = 'invalid.token';
+    const result = await service.validateToken(token);
+    expect(result.valid).toBe(false);
+  });
+});
+```
+
+## Integration Testing
+
+### API Integration Tests
+
+```python
+# tests/test_api_integration.py
+import pytest
+from fastapi.testclient import TestClient
+from src.main import app
+
+client = TestClient(app)
+
+def test_user_flow():
+    """Test complete user registration and login flow"""
+    # Register user
+    response = client.post("/api/auth/register", json={
+        "email": "test@example.com",
+        "password": "password123"
+    })
+    assert response.status_code == 201
+
+    # Login
+    response = client.post("/api/auth/login", json={
+        "email": "test@example.com",
+        "password": "password123"
+    })
+    assert response.status_code == 200
+    token = response.json()["token"]
+
+    # Access protected endpoint
+    response = client.get("/api/user/profile", headers={
+        "Authorization": f"Bearer {token}"
+    })
+    assert response.status_code == 200
+    assert response.json()["email"] == "test@example.com"
+```
+
+### Database Integration Tests
+
+```typescript
+// src/modules/__tests__/integration.test.ts
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { CosmosClient } from '@azure/cosmos';
+import { UserRepository } from '../users/repository';
+
+describe('UserRepository Integration', () => {
+  let client: CosmosClient;
+  let repo: UserRepository;
+
+  beforeAll(async () => {
+    client = new CosmosClient(process.env.COSMOS_ENDPOINT!);
+    repo = new UserRepository(client);
+  });
+
+  it('should create and retrieve user', async () => {
+    const user = {
+      id: 'test-user',
+      email: 'test@example.com',
+      productId: 'lysnrai',
+    };
+
+    await repo.create(user);
+    const retrieved = await repo.getById('test-user');
+
+    expect(retrieved).toBeDefined();
+    expect(retrieved.email).toBe(user.email);
+  });
+
+  afterAll(async () => {
+    // Cleanup test data
+    await repo.delete('test-user');
+  });
+});
+```
+
+## End-to-End Testing
+
+### Playwright (Web Dashboards)
+
+```bash
+# Install Playwright
+npm install -D @playwright/test
+
+# Install browsers
+npx playwright install
+
+# Run E2E tests
+npm run test:e2e
+
+# Run in headed mode (useful for debugging)
+npm run test:e2e -- --headed
+```
+
+#### Test Structure
+
+```typescript
+// e2e/login.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Authentication', () => {
+  test('user can login', async ({ page }) => {
+    await page.goto('/login');
+
+    await page.fill('[data-testid=email]', 'admin@example.com');
+    await page.fill('[data-testid=password]', 'password');
+    await page.click('[data-testid=login-button]');
+
+    // Should redirect to dashboard
+    await expect(page).toHaveURL('/dashboard');
+    await expect(page.locator('h1')).toContainText('Welcome');
+  });
+
+  test('shows error for invalid credentials', async ({ page }) => {
+    await page.goto('/login');
+
+    await page.fill('[data-testid=email]', 'admin@example.com');
+    await page.fill('[data-testid=password]', 'wrong');
+    await page.click('[data-testid=login-button]');
+
+    await expect(page.locator('[data-testid=error]')).toContainText('Invalid credentials');
+  });
+});
+```
+
+### Mobile E2E Tests
+
+```typescript
+// mobile/e2e/app.test.ts
+import { device, element, by, expect } from 'detox';
+
+describe('Mobile App', () => {
+  beforeAll(async () => {
+    await device.launchApp();
+  });
+
+  beforeEach(async () => {
+    await device.reloadReactNative();
+  });
+
+  it('should show welcome screen', async () => {
+    await expect(element(by.id('welcome-screen'))).toBeVisible();
+  });
+
+  it('should navigate to settings', async () => {
+    await element(by.id('settings-button')).tap();
+    await expect(element(by.id('settings-screen'))).toBeVisible();
+  });
+});
+```
+
+## Test Data Management
+
+### Fixtures (Python)
+
+```python
+# tests/conftest.py
+import pytest
+from src.database import get_db_session
+
+@pytest.fixture
+def db_session():
+    """Provide a database session for tests"""
+    session = get_db_session()
+    yield session
+    session.rollback()
+    session.close()
+
+@pytest.fixture
+def sample_user():
+    """Provide a sample user for tests"""
+    return {
+        "id": "test-user-123",
+        "email": "test@example.com",
+        "name": "Test User",
+        "productId": "lysnrai"
+    }
+```
+
+### Mock Data (TypeScript)
+
+```typescript
+// src/__tests__/mocks/data.ts
+export const mockUser = {
+  id: 'user-123',
+  email: 'test@example.com',
+  createdAt: new Date().toISOString(),
+  productId: 'lysnrai',
+};
+
+export const mockSubscription = {
+  id: 'sub-123',
+  userId: 'user-123',
+  status: 'active',
+  planId: 'pro',
+};
+```
+
+## Testing Best Practices
+
+### 1. Test Naming
+
+```python
+# Good: descriptive and clear
+def test_user_login_with_valid_credentials_returns_token()
+
+# Bad: vague
+def test_login()
+```
+
+### 2. AAA Pattern (Arrange, Act, Assert)
+
+```python
+def test_discount_applied():
+    # Arrange
+    cart = ShoppingCart()
+    cart.add_item("book", 10)
+    coupon = Coupon("DISCOUNT10", 0.1)
+
+    # Act
+    cart.apply_coupon(coupon)
+
+    # Assert
+    assert cart.total == 9.00
+```
+
+### 3. Test Isolation
+
+```python
+# Each test should be independent
+def test_create_user():
+    user = User(name="Alice")
+    assert user.name == "Alice"
+
+def test_update_user():
+    user = User(name="Bob")  # Fresh instance, not from previous test
+    user.update_name("Charlie")
+    assert user.name == "Charlie"
+```
+
+### 4. Use Test Doubles
+
+```typescript
+// Mock external dependencies
+vi.mock('@azure/cosmos', () => ({
+  CosmosClient: vi.fn().mockImplementation(() => ({
+    database: vi.fn().mockReturnValue({
+      container: vi.fn().mockReturnValue({
+        items: {
+          create: vi.fn().mockResolvedValue({ resource: mockUser })
+        }
+      })
+    })
+  })
+}))
+```
+
+## Coverage Requirements
+
+### Coverage Targets
+
+| Component           | Unit Tests | Integration | E2E | Total Coverage |
+| ------------------- | ---------- | ----------- | --- | -------------- |
+| Backend Services    | 80%        | 40%         | 10% | 85%            |
+| Frontend Components | 70%        | 30%         | 20% | 80%            |
+| Shared Libraries    | 90%        | 50%         | 0%  | 90%            |
+| Mobile Apps         | 70%        | 30%         | 30% | 80%            |
+
+### Coverage Reports
+
+```bash
+# Python
+coverage html
+open htmlcov/index.html
+
+# TypeScript
+open coverage/lcov-report/index.html
+```
+
+## CI/CD Integration
+
+### GitHub Actions
+
+```yaml
+name: Tests
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [3.12]
+        node-version: [20]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+
+      - name: Install dependencies
+        run: |
+          pip install -e ".[dev]"
+          npm install
+
+      - name: Run tests
+        run: |
+          python -m pytest tests/ --cov=src
+          npm run test --coverage
+
+      - name: Upload coverage
+        uses: codecov/codecov-action@v3
+```
+
+## Debugging Tests
+
+### Python
+
+```bash
+# Run with debugger
+python -m pytest tests/test_file.py --pdb
+
+# Print output
+python -m pytest tests/ -v -s
+
+# Show local variables on failure
+python -m pytest tests/ --tb=long
+```
+
+### TypeScript
+
+```bash
+# Run in debug mode
+pnpm test --inspect-brk
+
+# Run specific test file with debugger
+pnpm test specific.test.ts --inspect-brk
+```
+
+## Performance Testing
+
+### Load Testing (k6)
+
+```javascript
+// tests/load/api.js
+import http from 'k6/http';
+import { check } from 'k6';
+
+export let options = {
+  stages: [
+    { duration: '2m', target: 100 },
+    { duration: '5m', target: 100 },
+    { duration: '2m', target: 0 },
+  ],
+};
+
+export default function () {
+  let response = http.post('http://localhost:8000/api/auth/login', {
+    email: 'test@example.com',
+    password: 'password',
+  });
+
+  check(response, {
+    'status is 200': r => r.status === 200,
+    'response time < 500ms': r => r.timings.duration < 500,
+  });
+}
+```
+
+## Notes
+
+- **Test the behavior, not the implementation**
+- **Keep tests simple and readable**
+- **Use descriptive test names**
+- **Mock external dependencies**
+- **Run tests in CI/CD**
+- **Monitor coverage, but don't chase 100%**
+- **Review and refactor tests regularly**
+
+## Related Skills
+
+- [Debug Service](./debug-service.md) - When tests fail
+- [Production Readiness](./production-readiness.md) - Tests part of readiness
+- [Mobile Code Quality](./mobile-code-quality.md) - Mobile-specific testing
--- a/AI.dev/SKILLS/update-agent-docs.md
+++ b/AI.dev/SKILLS/update-agent-docs.md
@ -0,0 +1,384 @@
+# Update Agent Documentation Skill
+
+**Description**: Scan all repos and regenerate AI assistant documentation (AGENTS.md, CLAUDE.md, etc.) across the workspace.
+
+## When to Use
+
+- After adding new packages or services
+- When changing coding conventions
+- After architectural changes
+- Periodically to keep docs current
+- When onboarding new AI assistants
+
+## Repositories Covered
+
+| Repo                                  | Path                                                        | Scope                      |
+| ------------------------------------- | ----------------------------------------------------------- | -------------------------- |
+| **learning_voice_ai_agent**           | `/Users/sd9235/code/mygh/learning_voice_ai_agent`           | LysnrAI product code       |
+| **learning_ai_common_plat**           | `/Users/sd9235/code/mygh/learning_ai_common_plat`           | Shared packages + services |
+| **learning_multimodal_memory_agents** | `/Users/sd9235/code/mygh/learning_multimodal_memory_agents` | MindLyst native app        |
+
+## Files Updated Per Repo
+
+| File                              | Tool             | Format                       | Purpose                          |
+| --------------------------------- | ---------------- | ---------------------------- | -------------------------------- |
+| `AGENTS.md`                       | Universal        | Detailed markdown            | Full onboarding guide            |
+| `CLAUDE.md`                       | Claude Code      | Compact markdown (<50 lines) | Quick reference                  |
+| `.cursorrules`                    | Cursor AI        | Plain text                   | Inline completion + chat rules   |
+| `.github/copilot-instructions.md` | GitHub Copilot   | Markdown                     | Code generation rules            |
+| `.windsurfrules`                  | Windsurf/Codeium | Plain text                   | Project rules for memory         |
+| `.clinerules`                     | Cline/Roo Code   | Plain text                   | Mandatory rules + file locations |
+| `.aider.conf.yml`                 | Aider            | YAML                         | Context files, conventions       |
+| `.editorconfig`                   | All editors      | INI                          | Indent, charset, line ending     |
+
+## Phase 1: Gather Current State
+
+### 1. Scan learning_voice_ai_agent
+
+```bash
+cd /Users/sd9235/code/mygh/learning_voice_ai_agent
+
+# Find all JS projects
+find . -maxdepth 2 -type f -name "package.json" -not -path "*/node_modules/*" | head -20
+
+# Find Python config
+find . -maxdepth 1 -type f -name "*.py" -o -name "*.toml" -o -name "Makefile" | head -20
+
+# Read key files
+cat AGENTS.md
+cat README_MONO_REPO.md
+cat docker-compose.yml
+cat pyproject.toml
+
+# Check dashboard dependencies
+find admin-dashboard-web user-dashboard-web tracker-dashboard-web -name "package.json" -exec grep "@bytelyst" {} \;
+
+# List lib files
+ls admin-dashboard-web/src/lib/
+ls user-dashboard-web/src/lib/
+ls tracker-dashboard-web/src/lib/
+
+# Count tests
+find tests/ -name "test_*.py" | wc -l
+find admin-dashboard-web/src/app/api -name "route.ts" | wc -l
+
+# Check CI workflows
+ls -la .github/workflows/
+
+# Check service topology
+head -20 run-local-all-services.sh
+```
+
+### 2. Scan learning_ai_common_plat
+
+```bash
+cd /Users/sd9235/code/mygh/learning_ai_common_plat
+
+# List all packages
+find packages -maxdepth 2 -name "package.json" -not -path "*/node_modules/*"
+
+# List all services
+find services -maxdepth 2 -name "package.json" -not -path "*/node_modules/*"
+
+# Read key files
+cat AGENTS.md
+cat README.md
+cat pnpm-workspace.yaml
+cat tsconfig.base.json
+
+# Check package exports
+find packages -name "src/index.ts" -exec echo "=== {} ===" \; -exec cat {} \;
+
+# Check service modules
+find services -name "src/server.ts" -exec echo "=== {} ===" \; -exec cat {} \;
+
+# Count tests (quick)
+pnpm test 2>&1 | tail -5
+
+# Check design tokens
+cat packages/design-tokens/tokens/bytelyst.tokens.json
+ls packages/design-tokens/generated/
+```
+
+### 3. Scan learning_multimodal_memory_agents
+
+```bash
+cd /Users/sd9235/code/mygh/learning_multimodal_memory_agents
+
+# Find source files
+find mindlyst-native -maxdepth 3 -name "*.kt" -o -name "*.swift" -o -name "*.tsx" | head -30
+
+# Read key files
+cat AGENTS.md
+cat README.md
+cat ARCHITECTURE.md
+
+# Check dependencies
+cat mindlyst-native/gradle/libs.versions.toml
+cat mindlyst-native/shared/build.gradle.kts
+
+# List shared logic
+ls mindlyst-native/shared/src/commonMain/kotlin/com/mindlyst/shared/
+
+# List platform code
+ls mindlyst-native/iosApp/
+ls mindlyst-native/web/src/pages/
+
+# Check token sync
+head -20 design-system/web/mindlyst.css
+```
+
+## Phase 2: Identify Changes
+
+Compare gathered info against existing docs:
+
+- New packages or services?
+- Changed conventions?
+- New file ownership patterns?
+- Updated environment variables?
+- Different test counts?
+- New CI workflows?
+
+Build a change summary before editing.
+
+## Phase 3: Update Documentation
+
+### 1. Update AGENTS.md (Most Comprehensive)
+
+Ensure these sections are current:
+
+```markdown
+## Project Identity
+
+- Product name, IDs, prefixes
+- License format
+- Config directory
+
+## Monorepo Layout
+
+- Directory tree with descriptions
+- Include sibling repo structure
+- Service ports and responsibilities
+
+## Tech Stack Rules
+
+- Python: version, linter, formatter, tests, logging
+- TypeScript services: framework, patterns, database
+- TypeScript dashboards: framework, shared packages
+
+## Coding Conventions
+
+- MUST follow rules
+- MUST NOT do rules
+- Commit message format
+
+## File Ownership Map
+
+- Table mapping domains → services → key files
+- Include all @bytelyst/\* mappings
+
+## How to Run Things
+
+- Start services command
+- Test commands
+- Docker compose
+- Seed database
+
+## Common Patterns
+
+- Adding Fastify modules
+- Adding dashboard pages
+- Adding service clients
+- Adding backend routes
+- Debugging methodology
+
+## Environment Variables
+
+- Required vars per service
+- Env file locations
+- Azure service references
+
+## Key Documents
+
+- "When you need to..." → "read this" table
+```
+
+### 2. Update CLAUDE.md (Compact Summary)
+
+Keep under 50 lines:
+
+- Identity (product, tech stack)
+- Key commands (start services, run tests)
+- Critical rules (MUST follow)
+- Current @bytelyst/\* wiring state
+
+### 3. Update .cursorrules
+
+```text
+Project: LysnrAI - Voice-to-text platform
+Stack: Python 3.12 + FastAPI + Next.js 16 + Fastify 5
+Rules:
+- Always use req.log, never console.log
+- Every Cosmos doc needs productId field
+- Use @bytelyst/* packages from common_plat
+- Commit: feat(scope): description
+- See AGENTS.md for full details
+```
+
+### 4. Update .github/copilot-instructions.md
+
+```markdown
+# LysnrAI Copilot Instructions
+
+## Always Do
+
+- Use structlog for Python logging
+- Validate with Zod schemas in TypeScript
+- Include productId in all Cosmos documents
+- Use @bytelyst/api-client for service calls
+
+## Never Do
+
+- Use console.log in production
+- Hardcode secrets or API keys
+- Modify tests to make them pass
+- Use any type in TypeScript
+
+## Key Patterns
+
+- Fastify modules: types.ts → repository.ts → routes.ts
+- Dashboard pages: src/app/(dashboard)/page-name/page.tsx
+- Python routes: backend/src/routes/name.py
+
+See AGENTS.md for comprehensive guide.
+```
+
+### 5. Update .windsurfrules
+
+```text
+Project: LysnrAI
+Product ID: lysnrrai
+Config dir: ~/.lysnrai/
+Key services: backend(8000), billing(4002), growth(4001), platform(4003), tracker(4004)
+Dashboards: admin(3001), user(3002), tracker(3003)
+Rules: Use @bytelyst/* packages, no console.log, productId required, commit format: type(scope): desc
+```
+
+### 6. Update .clinerules
+
+```text
+# LysnrAI Project Rules
+- All business logic in backend/src/ or services/
+- Dashboards in admin-dashboard-web/, user-dashboard-web/, tracker-dashboard-web/
+- Shared packages in ../learning_ai_common_plat/packages/
+- Use @bytelyst/cosmos for DB, @bytelyst/auth for JWT
+- Python: use ruff lint, pytest tests
+- TypeScript: use ESLint, Vitest tests
+- Never commit .env files or secrets
+```
+
+### 7. Update .aider.conf.yml
+
+```yaml
+# Aider configuration for LysnrAI
+auto-commits: false
+lint-cmd: |
+  python: ruff check --fix
+  typescript: pnpm lint
+  shell: shellcheck -f gcc
+test-cmd: |
+  python: pytest tests/ -v
+  typescript: pnpm test
+
+# Always include these files in context
+context-files:
+  - AGENTS.md
+  - README_MONO_REPO.md
+  - docker-compose.yml
+  - pyproject.toml
+  - pnpm-workspace.yaml
+  - tsconfig.base.json
+```
+
+### 8. Update .editorconfig
+
+```ini
+# EditorConfig for LysnrAI
+root = true
+
+[*.py]
+indent_style = space
+indent_size = 4
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+
+[*.{js,ts,tsx,json}]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+
+[*.{kt,swift}]
+indent_style = space
+indent_size = 4
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+```
+
+## Phase 4: Validate Updates
+
+```bash
+# For each repo:
+git add .
+git commit -m "docs: update AI agent documentation"
+git push
+
+# Verify files are readable
+cat AGENTS.md | head -20
+cat CLAUDE.md
+cat .cursorrules
+```
+
+## Automation Script
+
+Create `scripts/update-all-agent-docs.sh`:
+
+```bash
+#!/bin/bash
+# Update all agent docs across repos
+
+REPOS=(
+  "/Users/sd9235/code/mygh/learning_voice_ai_agent"
+  "/Users/sd9235/code/mygh/learning_ai_common_plat"
+  "/Users/sd9235/code/mygh/learning_multimodal_memory_agents"
+)
+
+for repo in "${REPOS[@]}"; do
+  echo "Updating docs in $repo"
+  cd "$repo"
+
+  # Run the update workflow
+  # (This would be the full workflow implementation)
+
+  git add .
+  git commit -m "docs: update AI agent documentation"
+  git push
+done
+```
+
+## Notes
+
+- **Be consistent** - Keep the same structure across all repos
+- **Be specific** - Include actual file paths and commands
+- **Stay current** - Run this workflow regularly
+- **Get feedback** - Ask developers if docs are helpful
+- **Version control** - Track changes to understand evolution
+
+## Related Skills
+
+- [Production Readiness](./production-readiness.md) - Docs are part of readiness
+- [Local Development Setup](./local-development.md) - Docs should match local setup
+- [Debug Service](./debug-service.md) - Docs should help with debugging