diff --git a/AI.dev/PROMPTS/README.md b/AI.dev/PROMPTS/README.md
new file mode 100644
index 00000000..adcbf393
--- /dev/null
+++ b/AI.dev/PROMPTS/README.md
@@ -0,0 +1,75 @@
+# ByteLyst Ecosystem — Reusable AI Prompts
+
+> **Location:** `AI.dev/PROMPTS/`
+> **Audience:** Claude Code, Codex, Cursor, Copilot, Windsurf Cascade, Gemini, and any AI coding agent.
+> **Scope:** All 37 repos in `D:\BYTELYST\CODE\` — common platform, product repos, tooling repos.
+
+---
+
+## How to Use
+
+Copy-paste a prompt into your AI assistant, or reference it by path:
+
+```
+@file AI.dev/PROMPTS/roadmap-execution.md
+```
+
+Each prompt is **self-contained** — it includes the context the agent needs without
+requiring you to manually explain the ecosystem every time.
+
+## Prompt Index
+
+### 🗺️ Planning & Roadmap
+
+| Prompt | Purpose |
+|--------|---------|
+| [roadmap-execution.md](./roadmap-execution.md) | Execute a phased roadmap with checkpoints, commits, and validation |
+| [new-product-scaffold.md](./new-product-scaffold.md) | Scaffold a new ByteLyst product repo from scratch |
+| [prd-to-implementation.md](./prd-to-implementation.md) | Convert a PRD into a concrete, phased implementation plan |
+
+### 🔧 Development & Debugging
+
+| Prompt | Purpose |
+|--------|---------|
+| [cross-repo-debug.md](./cross-repo-debug.md) | Systematically debug issues spanning multiple repos |
+| [backend-module-crud.md](./backend-module-crud.md) | Add a complete Fastify CRUD module (types → repo → routes → tests) |
+| [platform-integration.md](./platform-integration.md) | Wire a product repo into the common platform ecosystem |
+| [refactor-with-tests.md](./refactor-with-tests.md) | Safely refactor code with test-first methodology |
+
+### 🧪 Quality & Testing
+
+| Prompt | Purpose |
+|--------|---------|
+| [test-gap-analysis.md](./test-gap-analysis.md) | Identify and fill test coverage gaps in any repo |
+| [type-safety-sweep.md](./type-safety-sweep.md) | Fix TypeScript errors across a repo or the workspace |
+| [dependency-health-check.md](./dependency-health-check.md) | Audit and update dependencies across repos |
+
+### 📦 Release & Ops
+
+| Prompt | Purpose |
+|--------|---------|
+| [pre-release-validation.md](./pre-release-validation.md) | Full pre-release checklist: build, test, lint, security |
+| [docker-production-prep.md](./docker-production-prep.md) | Prepare Docker images for production deployment |
+
+### 📚 Documentation
+
+| Prompt | Purpose |
+|--------|---------|
+| [agents-md-sync.md](./agents-md-sync.md) | Update AGENTS.md across all repos to match current state |
+| [ecosystem-audit.md](./ecosystem-audit.md) | Full ecosystem health audit with actionable report |
+
+---
+
+## Conventions
+
+- **Agent-agnostic:** Prompts work across Claude, Copilot, Cursor, Windsurf, Gemini.
+- **Ecosystem-aware:** Each prompt embeds the key ByteLyst conventions (productId, Fastify module pattern, @bytelyst/* packages, pnpm workspace).
+- **Commit-friendly:** Prompts that produce code changes include commit message guidance.
+- **Incremental:** Each prompt favors small, validated, committed steps over big-bang changes.
+
+## Adding a New Prompt
+
+1. Create `AI.dev/PROMPTS/<prompt-name>.md`
+2. Include a YAML-style header with `name`, `description`, `argument-hint`
+3. Add it to this index
+4. Commit: `docs(prompts): add <prompt-name> reusable prompt`
diff --git a/AI.dev/PROMPTS/agents-md-sync.md b/AI.dev/PROMPTS/agents-md-sync.md
new file mode 100644
index 00000000..0e50bd9c
--- /dev/null
+++ b/AI.dev/PROMPTS/agents-md-sync.md
@@ -0,0 +1,119 @@
+---
+name: agents-md-sync
+description: 'Audit and update AGENTS.md files across all ByteLyst repos to match current codebase reality — layout, test counts, API endpoints, packages.'
+argument-hint: 'Scope, e.g. "all repos", "learning_ai_efforise only", "test counts only"'
+agent: agent
+---
+
+# AGENTS.md Sync Prompt
+
+Ensure all AGENTS.md files across the ByteLyst ecosystem accurately reflect the current state of each repository.
+
+## Context — What AGENTS.md Does
+
+AGENTS.md is the **primary instruction file for AI coding assistants** (Claude Code, Copilot, Cursor, Windsurf, Gemini). It must be accurate because:
+- AI agents read it before making changes
+- Incorrect docs lead to incorrect code
+- Stale test counts erode agent trust
+- Wrong layout trees cause file-not-found errors
+
+## Standard AGENTS.md Sections
+
+Every ByteLyst repo should have these sections:
+
+1. **Project Identity** — product name, ID, bundle IDs, ports, ecosystem
+2. **Repo Layout** — file tree (keep up to date!)
+3. **Tech Stack** — frameworks, languages, tools per layer
+4. **Coding Conventions** — MUST follow / MUST NOT do
+5. **.npmrc rules** — never edit directly
+6. **Cosmos Containers** (if backend) — container, partition key, purpose
+7. **Build & Test Commands** — exact `pnpm` commands
+8. **API Endpoints** (if backend) — method, path, description
+9. **Environment Variables** — var, default, description
+10. **Current State** (optional) — phases, commits, test counts
+11. **Cross-Repo Automation** — link to CODING_AGENT_AUTOMATION_PLAYBOOK.md
+
+## Sync Protocol
+
+### Step 1: Scan Each Repo
+
+For each repo, programmatically verify:
+
+```bash
+# File tree matches layout section
+find . -type f -name "*.ts" -o -name "*.tsx" -o -name "*.swift" -o -name "*.kt" | head -50
+
+# Test count matches
+pnpm test --reporter=verbose 2>&1 | tail -5
+
+# API endpoints match (backend)
+grep -r "app\.\(get\|post\|patch\|put\|delete\)" backend/src/modules/*/routes.ts
+
+# Package count matches
+ls node_modules/@bytelyst/ 2>/dev/null | wc -l
+
+# Cosmos containers match
+grep -r "getCollection\|getContainer" backend/src/modules/*/repository.ts
+```
+
+### Step 2: Identify Drift
+
+Compare AGENTS.md content against reality:
+
+| Section | Check | Drift Signal |
+|---------|-------|-------------|
+| Repo Layout | `find` vs documented tree | New dirs/files not listed |
+| Tech Stack | package.json deps | New framework not mentioned |
+| Test Counts | `pnpm test` output | Count differs by >5 |
+| API Endpoints | route file scan | Missing endpoints |
+| Cosmos Containers | repository scan | New containers |
+| Packages Used | node_modules scan | New @bytelyst/* packages |
+| Ports | shared/product.json | Port mismatch |
+
+### Step 3: Update AGENTS.md
+
+For each drift found:
+- Update the specific section
+- Preserve all existing comments and documentation
+- Keep formatting consistent with other repos
+
+### Step 4: Update CLAUDE.md
+
+If AGENTS.md changed significantly, also sync CLAUDE.md (the Claude Code-specific instruction file).
+
+### Step 5: Commit Per Repo
+
+```bash
+cd <repo>
+git add AGENTS.md CLAUDE.md
+git commit -m "docs(agents): sync AGENTS.md with current repo state
+
+- Updated: <sections that changed>
+- Test count: X → Y
+- <other changes>"
+git push
+```
+
+## Report Format
+
+```markdown
+## AGENTS.md Sync Report
+
+| Repo | Status | Sections Updated | Commit |
+|------|--------|-----------------|--------|
+| learning_ai_common_plat | ✅ Up to date | — | — |
+| learning_ai_efforise | 🔄 Updated | Layout, Tests | abc123 |
+| learning_ai_flowmonk | 🔄 Updated | API Endpoints | def456 |
+| learning_ai_dev_intelli | ❌ Skipped | — | Needs manual review |
+
+### Key Findings
+- <finding 1>
+- <finding 2>
+```
+
+## Guardrails
+
+- **Never delete documentation** — only add or update
+- **Preserve comments** — keep existing notes and explanations
+- **Verify before commit** — run `pnpm typecheck` to ensure no doc references break
+- **One repo per commit** — keep history clean
diff --git a/AI.dev/PROMPTS/backend-module-crud.md b/AI.dev/PROMPTS/backend-module-crud.md
new file mode 100644
index 00000000..a327e8d0
--- /dev/null
+++ b/AI.dev/PROMPTS/backend-module-crud.md
@@ -0,0 +1,246 @@
+---
+name: backend-module-crud
+description: 'Add a complete Fastify CRUD module with types, repository, routes, and tests following ByteLyst conventions.'
+argument-hint: 'Module name and parent repo, e.g. "habits in efforise", "workouts in peakpulse", "conversations in jarvisjr"'
+agent: agent
+---
+
+# Backend Module CRUD Prompt
+
+Create a complete Fastify backend module with Zod-validated types, Cosmos repository, REST routes, and comprehensive tests.
+
+## Context — ByteLyst Backend Pattern
+
+Every product backend follows this module structure:
+```
+backend/src/modules/<module>/
+├── types.ts          # Zod schemas + TypeScript interfaces
+├── repository.ts     # Cosmos DB CRUD operations
+├── routes.ts         # Fastify REST endpoints
+└── <module>.test.ts  # Vitest tests
+```
+
+**Key packages used:**
+- `@bytelyst/datastore` — Cosmos DB abstraction (`getCollection()`)
+- `@bytelyst/errors` — Typed HTTP errors (`BadRequestError`, `NotFoundError`, etc.)
+- `@bytelyst/fastify-auth` — JWT auth middleware
+- `zod` — Schema validation (service's own copy, NOT from @bytelyst/config)
+
+## Implementation Steps
+
+### 1. Create `types.ts`
+
+```typescript
+import { z } from 'zod';
+
+// ── Create schema (input from API) ──
+export const create<Entity>Schema = z.object({
+  // Required fields
+  name: z.string().min(1).max(200),
+  // Optional fields
+  description: z.string().max(1000).optional(),
+  // Enum fields
+  status: z.enum(['active', 'paused', 'completed']).default('active'),
+});
+
+// ── Update schema (partial, for PATCH) ──
+export const update<Entity>Schema = create<Entity>Schema.partial();
+
+// ── Full document (stored in Cosmos) ──
+export const <entity>Schema = create<Entity>Schema.extend({
+  id: z.string().uuid(),
+  userId: z.string(),
+  productId: z.string(),
+  createdAt: z.string().datetime(),
+  updatedAt: z.string().datetime(),
+});
+
+// ── TypeScript types ──
+export type Create<Entity> = z.infer<typeof create<Entity>Schema>;
+export type Update<Entity> = z.infer<typeof update<Entity>Schema>;
+export type <Entity> = z.infer<typeof <entity>Schema>;
+```
+
+### 2. Create `repository.ts`
+
+```typescript
+import { getCollection } from '../../lib/datastore.js';
+import type { Create<Entity>, Update<Entity>, <Entity> } from './types.js';
+import { NotFoundError } from '../../lib/errors.js';
+import { randomUUID } from 'node:crypto';
+
+const CONTAINER = '<product>_<entities>';
+
+function getContainer() {
+  return getCollection(CONTAINER);
+}
+
+export async function create<Entity>(
+  userId: string,
+  productId: string,
+  data: Create<Entity>
+): Promise<<Entity>> {
+  const now = new Date().toISOString();
+  const doc: <Entity> = {
+    ...data,
+    id: randomUUID(),
+    userId,
+    productId,
+    createdAt: now,
+    updatedAt: now,
+  };
+  const container = getContainer();
+  await container.create(doc);
+  return doc;
+}
+
+export async function list<Entities>(
+  userId: string,
+  productId: string
+): Promise<<Entity>[]> {
+  const container = getContainer();
+  return container.query<Entity>({
+    query: 'SELECT * FROM c WHERE c.userId = @userId AND c.productId = @productId ORDER BY c.createdAt DESC',
+    parameters: [
+      { name: '@userId', value: userId },
+      { name: '@productId', value: productId },
+    ],
+  });
+}
+
+export async function get<Entity>ById(
+  id: string,
+  userId: string,
+  productId: string
+): Promise<<Entity>> {
+  const container = getContainer();
+  const doc = await container.read<Entity>(id, userId);
+  if (!doc || doc.productId !== productId) {
+    throw new NotFoundError('<Entity> not found');
+  }
+  return doc;
+}
+
+export async function update<Entity>(
+  id: string,
+  userId: string,
+  productId: string,
+  data: Update<Entity>
+): Promise<<Entity>> {
+  const existing = await get<Entity>ById(id, userId, productId);
+  const updated: <Entity> = {
+    ...existing,
+    ...data,
+    updatedAt: new Date().toISOString(),
+  };
+  const container = getContainer();
+  await container.replace(id, updated, userId);
+  return updated;
+}
+
+export async function delete<Entity>(
+  id: string,
+  userId: string,
+  productId: string
+): Promise<void> {
+  await get<Entity>ById(id, userId, productId); // Verify ownership
+  const container = getContainer();
+  await container.delete(id, userId);
+}
+```
+
+### 3. Create `routes.ts`
+
+```typescript
+import type { FastifyInstance } from 'fastify';
+import { create<Entity>Schema, update<Entity>Schema } from './types.js';
+import * as repo from './repository.js';
+import { getUserId, getRequestProductId } from '../../lib/request-context.js';
+
+export default async function <entity>Routes(app: FastifyInstance) {
+  // GET /api/<entities>
+  app.get('/<entities>', async (req) => {
+    const userId = getUserId(req);
+    const productId = getRequestProductId(req);
+    return repo.list<Entities>(userId, productId);
+  });
+
+  // GET /api/<entities>/:id
+  app.get('/<entities>/:id', async (req) => {
+    const { id } = req.params as { id: string };
+    const userId = getUserId(req);
+    const productId = getRequestProductId(req);
+    return repo.get<Entity>ById(id, userId, productId);
+  });
+
+  // POST /api/<entities>
+  app.post('/<entities>', async (req, reply) => {
+    const userId = getUserId(req);
+    const productId = getRequestProductId(req);
+    const data = create<Entity>Schema.parse(req.body);
+    const entity = await repo.create<Entity>(userId, productId, data);
+    reply.code(201);
+    return entity;
+  });
+
+  // PATCH /api/<entities>/:id
+  app.patch('/<entities>/:id', async (req) => {
+    const { id } = req.params as { id: string };
+    const userId = getUserId(req);
+    const productId = getRequestProductId(req);
+    const data = update<Entity>Schema.parse(req.body);
+    return repo.update<Entity>(id, userId, productId, data);
+  });
+
+  // DELETE /api/<entities>/:id
+  app.delete('/<entities>/:id', async (req, reply) => {
+    const { id } = req.params as { id: string };
+    const userId = getUserId(req);
+    const productId = getRequestProductId(req);
+    await repo.delete<Entity>(id, userId, productId);
+    reply.code(204);
+  });
+}
+```
+
+### 4. Register in `server.ts`
+
+```typescript
+import <entity>Routes from './modules/<entities>/routes.js';
+// ...
+await app.register(<entity>Routes, { prefix: '/api' });
+```
+
+### 5. Create tests
+
+Write tests covering:
+- ✅ Create with valid data → 201
+- ✅ Create with invalid data → 400
+- ✅ List returns user's items only
+- ✅ Get by ID returns correct item
+- ✅ Get by ID with wrong user → 404
+- ✅ Update modifies fields + updatedAt
+- ✅ Delete removes item → 204
+- ✅ Delete with wrong user → 404
+
+### 6. Validate
+
+```bash
+cd backend
+pnpm test
+pnpm typecheck
+pnpm build
+```
+
+### 7. Commit
+
+```bash
+git add .
+git commit -m "feat(<entities>): add <entity> CRUD module
+
+- types.ts: Zod schemas for create/update/<entity>
+- repository.ts: Cosmos CRUD with user ownership
+- routes.ts: GET/POST/PATCH/DELETE endpoints
+- tests: N tests covering CRUD + auth + validation"
+git push
+```
diff --git a/AI.dev/PROMPTS/cross-repo-debug.md b/AI.dev/PROMPTS/cross-repo-debug.md
new file mode 100644
index 00000000..4841cab9
--- /dev/null
+++ b/AI.dev/PROMPTS/cross-repo-debug.md
@@ -0,0 +1,145 @@
+---
+name: cross-repo-debug
+description: 'Systematically debug issues that span multiple ByteLyst repos, tracing from symptom to root cause across service boundaries.'
+argument-hint: 'Symptom description, e.g. "auth token rejected by FlowMonk backend", "design tokens not applied in PeakPulse iOS", "platform-service 500 on /api/flags"'
+agent: agent
+---
+
+# Cross-Repo Debug Prompt
+
+Systematically diagnose and fix bugs that span multiple repositories in the ByteLyst ecosystem.
+
+## Context — ByteLyst Architecture
+
+**Service topology:**
+```
+Product clients (web/mobile)
+    → Product backend (Fastify, port 40xx)
+        → @bytelyst/* packages (shared libraries)
+        → platform-service (port 4003: auth, flags, billing, etc.)
+            → Cosmos DB (productId multi-tenancy)
+            → Azurite (blob storage)
+```
+
+**Common cross-repo failure points:**
+1. **Auth chain:** platform-service issues JWT → product backend validates → client stores
+2. **Package version mismatch:** Zod, jose, or @azure/cosmos version conflicts between packages and services
+3. **Config drift:** .env vars, .npmrc, or product.json out of sync
+4. **API contract breaks:** platform-service endpoint changed but consumer not updated
+5. **Design token gaps:** token JSON updated but generated files not regenerated/copied
+
+## Debug Protocol
+
+### Step 1: Symptom Capture
+
+Document:
+- **What:** Exact error message, HTTP status, or unexpected behavior
+- **Where:** Which repo/service/file/line
+- **When:** Always, intermittent, or after a specific change
+- **Who:** Which product(s) affected
+
+### Step 2: Trace the Call Chain
+
+Starting from the symptom, trace backwards:
+
+```
+1. Client (web/mobile) — check network tab, API client code
+2. Product backend — check routes.ts, request-context.ts, auth.ts
+3. Shared packages — check @bytelyst/* import versions
+4. Platform service — check the module handling this request
+5. Data layer — check Cosmos queries, partition keys, productId
+```
+
+For each layer, check:
+- Is the service running? (`curl http://localhost:<port>/health`)
+- Are env vars set? (compare with `.env.example`)
+- Are packages built? (`pnpm build` in common_plat)
+- Are types aligned? (`pnpm typecheck`)
+
+### Step 3: Isolate
+
+Run targeted tests to narrow scope:
+```bash
+# Test the specific module
+pnpm --filter @lysnrai/platform-service test -- --grep "auth"
+pnpm --filter @bytelyst/auth test
+
+# Test the product backend
+cd <product>/backend && pnpm test
+
+# Typecheck across repos
+cd learning_ai_common_plat && pnpm typecheck
+cd <product> && pnpm typecheck
+```
+
+### Step 4: Fix
+
+- Fix in the **lowest-level** repo first (packages → services → products)
+- Rebuild packages if you changed a `@bytelyst/*` package:
+  ```bash
+  cd learning_ai_common_plat && pnpm build
+  ```
+- Reinstall in consumer repos if package API changed:
+  ```bash
+  cd <product> && pnpm install
+  ```
+
+### Step 5: Validate Across Repos
+
+After fixing:
+```bash
+# 1. Rebuild common platform
+cd learning_ai_common_plat && pnpm build && pnpm test
+
+# 2. Reinstall + test affected products
+cd <product> && pnpm install && pnpm test
+
+# 3. Verify health endpoints
+curl -s http://localhost:4003/health | jq .
+curl -s http://localhost:<product-port>/health | jq .
+```
+
+### Step 6: Commit in Correct Repos
+
+Commit in dependency order:
+```bash
+# Fix in common_plat first
+cd learning_ai_common_plat
+git add . && git commit -m "fix(<package>): <description>" && git push
+
+# Then fix in product repo
+cd <product>
+git add . && git commit -m "fix(<scope>): <description>" && git push
+```
+
+## Common Diagnosis Patterns
+
+### "Module not found" or import errors
+- Check: Was `pnpm build` run in common_plat?
+- Check: Are `file:` refs in product's `package.json` pointing to correct paths?
+- Check: Is the export in the package's `src/index.ts`?
+
+### "Zod validation failed" or schema errors
+- Check: Service uses self-contained Zod schemas in `src/lib/config.ts` (not from @bytelyst/config)
+- Check: Zod version alignment between package and service
+
+### "401 Unauthorized" across services
+- Check: JWT_SECRET matches between platform-service and product backend
+- Check: Token is being forwarded in `Authorization: Bearer` header
+- Check: Product backend's auth.ts re-exports correctly from @bytelyst/auth
+
+### Design tokens not working
+- Check: Token generator was run (`pnpm --filter @bytelyst/design-tokens generate`)
+- Check: Generated files were copied to consumer repos
+- Check: CSS custom properties use correct product prefix (--er-*, --fm-*, --di-*, etc.)
+
+## Output
+
+For each issue found, report:
+```
+### Issue: <title>
+- **Root cause:** <repo>/<file> — <explanation>
+- **Fix:** <what was changed>
+- **Commit:** `<hash>` in `<repo>`
+- **Validated:** <test commands run>
+```
diff --git a/AI.dev/PROMPTS/dependency-health-check.md b/AI.dev/PROMPTS/dependency-health-check.md
new file mode 100644
index 00000000..d5805a4e
--- /dev/null
+++ b/AI.dev/PROMPTS/dependency-health-check.md
@@ -0,0 +1,139 @@
+---
+name: dependency-health-check
+description: 'Audit dependencies across ByteLyst repos for outdated packages, security vulnerabilities, version conflicts, and unused deps.'
+argument-hint: 'Scope, e.g. "all repos", "learning_ai_common_plat only", "security audit only"'
+agent: agent
+---
+
+# Dependency Health Check Prompt
+
+Audit and remediate dependency issues across the ByteLyst ecosystem.
+
+## Context — ByteLyst Dependency Conventions
+
+- **Package manager:** pnpm (workspace) — never npm or yarn
+- **Heavy deps:** Use `peerDependencies` in `@bytelyst/*` packages, NOT `dependencies`
+- **Workspace refs:** `"@bytelyst/<name>": "workspace:*"` for internal deps
+- **Product refs:** `"@bytelyst/<name>": "file:../../learning_ai_common_plat/packages/<name>"` for product repos
+- **Node version:** 22 (see `.nvmrc`)
+- **Key shared deps:** `@azure/cosmos`, `jose`, `bcryptjs`, `zod`, `fastify`
+
+## Audit Protocol
+
+### Step 1: Scan Dependencies
+
+For each repo:
+```bash
+# Check for outdated packages
+pnpm outdated
+
+# Security audit
+pnpm audit
+
+# Check for unused dependencies
+npx depcheck
+
+# Check for duplicate packages
+pnpm why <package>
+```
+
+### Step 2: Classify Issues
+
+| Severity | Type | Action |
+|----------|------|--------|
+| 🔴 **Critical** | Known security vulnerability (CVE) | Update immediately |
+| 🔴 **Critical** | Major version conflict causing runtime errors | Resolve version |
+| 🟡 **High** | Outdated major version with breaking changes | Plan upgrade |
+| 🟡 **High** | Unused dependency adding bundle bloat | Remove |
+| 🔵 **Medium** | Minor/patch updates available | Batch update |
+| ⚪ **Low** | Cosmetic (deprecated warning, newer alternative) | Track for later |
+
+### Step 3: Check Cross-Repo Version Alignment
+
+Ensure these critical packages are aligned across all repos:
+
+| Package | Expected Range | Check |
+|---------|---------------|-------|
+| `typescript` | `^5.7` | All repos |
+| `zod` | `^3.23` | All repos using Zod |
+| `fastify` | `^5` | All backends |
+| `vitest` | `^3` | All repos with tests |
+| `jose` | `^5` or `^6` | Auth-related packages |
+| `@azure/cosmos` | `^4` | Data layer |
+| `react` | `^19` | Web/mobile clients |
+| `next` | `^15` or `^16` | Next.js web apps |
+
+### Step 4: Safe Update Process
+
+#### Minor/patch updates (low risk):
+```bash
+pnpm update
+pnpm test
+pnpm typecheck
+git add . && git commit -m "chore(deps): update minor/patch dependencies" && git push
+```
+
+#### Major updates (higher risk):
+```bash
+# Update one package at a time
+pnpm update <package>@latest
+
+# Test immediately
+pnpm test
+pnpm typecheck
+pnpm build
+
+# Commit separately
+git add . && git commit -m "chore(deps): upgrade <package> to v<version>" && git push
+```
+
+#### Cross-repo updates:
+```bash
+# 1. Update in common_plat first
+cd learning_ai_common_plat
+pnpm update <package>@latest
+pnpm build && pnpm test
+git add . && git commit -m "chore(deps): upgrade <package>" && git push
+
+# 2. Then update in product repos
+cd <product>
+pnpm install  # Picks up new versions from common_plat
+pnpm test
+git add . && git commit -m "chore(deps): sync <package> version" && git push
+```
+
+### Step 5: Report
+
+```markdown
+## Dependency Health Check: <Scope>
+
+### Executive Summary
+- Repos audited: N
+- Critical issues: N
+- Updates available: N
+- Unused deps found: N
+
+### Critical Issues
+| Repo | Package | Issue | Action |
+|------|---------|-------|--------|
+
+### Version Alignment
+| Package | Expected | Repos In Sync | Repos Mismatched |
+|---------|----------|---------------|------------------|
+
+### Recommended Updates
+| Priority | Repo | Package | Current | Target | Risk |
+|----------|------|---------|---------|--------|------|
+
+### Unused Dependencies
+| Repo | Package | Safe to Remove |
+|------|---------|---------------|
+```
+
+## Guardrails
+
+- **Never update all dependencies at once** — do it incrementally
+- **Always test after each update** — `pnpm test && pnpm typecheck && pnpm build`
+- **Update common_plat first** — product repos depend on it
+- **Check peerDependencies** — ensure package consumers are compatible
+- **Don't force-resolve version conflicts** — understand why they exist first
diff --git a/AI.dev/PROMPTS/docker-production-prep.md b/AI.dev/PROMPTS/docker-production-prep.md
new file mode 100644
index 00000000..34746f2e
--- /dev/null
+++ b/AI.dev/PROMPTS/docker-production-prep.md
@@ -0,0 +1,195 @@
+---
+name: docker-production-prep
+description: 'Prepare Docker images for production deployment following ByteLyst conventions for corporate network, multi-stage builds, and security.'
+argument-hint: 'Product and surface, e.g. "efforise backend", "flowmonk backend + web", "all product backends"'
+agent: agent
+---
+
+# Docker Production Prep Prompt
+
+Build production-ready Docker images for ByteLyst services following network, security, and performance best practices.
+
+## Context — ByteLyst Docker Conventions
+
+**Critical rules from corporate network:**
+- **Never use Alpine** — `apk` cannot bypass TLS interception; use `node:22-slim` (Debian)
+- **Never use `corepack`** in Dockerfiles — use `npm install -g pnpm@10` or plain `npm`
+- **Always add** `npm config set strict-ssl false` before any `npm install` in build stages
+- **Always add** `ENV NODE_TLS_REJECT_UNAUTHORIZED=0` in build stages with native modules
+- **Production images** don't need these workarounds (only build stages)
+
+## Dockerfile Template (Backend Service)
+
+```dockerfile
+# ── Build Stage ────────────────────────────────────
+FROM node:22-slim AS builder
+
+# Corporate network workaround (build stage only)
+RUN npm config set strict-ssl false
+ENV NODE_TLS_REJECT_UNAUTHORIZED=0
+
+WORKDIR /app
+
+# Install pnpm (never use corepack)
+RUN npm install -g pnpm@10
+
+# Copy workspace files
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./
+COPY backend/package.json backend/
+COPY shared/ shared/
+
+# Copy @bytelyst/* tarballs (if using prep-consumer.sh)
+COPY .bytelyst-tarballs/ .bytelyst-tarballs/
+
+# Install dependencies
+RUN pnpm install --frozen-lockfile
+
+# Copy source and build
+COPY backend/ backend/
+RUN cd backend && pnpm build
+
+# ── Production Stage ───────────────────────────────
+FROM node:22-slim AS production
+
+WORKDIR /app
+
+# Non-root user for security
+RUN groupadd -r appuser && useradd -r -g appuser appuser
+
+# Copy only production artifacts
+COPY --from=builder /app/backend/dist/ ./dist/
+COPY --from=builder /app/backend/package.json ./
+COPY --from=builder /app/shared/ ./shared/
+COPY --from=builder /app/node_modules/ ./node_modules/
+
+# Security headers
+ENV NODE_ENV=production
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+  CMD node -e "fetch('http://localhost:${PORT:-4020}/health').then(r => r.ok ? process.exit(0) : process.exit(1)).catch(() => process.exit(1))"
+
+# Run as non-root
+USER appuser
+
+EXPOSE ${PORT:-4020}
+
+CMD ["node", "dist/server.js"]
+```
+
+## Preparation Steps
+
+### 1. Pack @bytelyst/* Dependencies
+
+If the Docker build doesn't have access to the sibling common_plat repo:
+
+```bash
+cd ../learning_ai_common_plat
+./scripts/prep-consumer.sh /path/to/<product>
+```
+
+This packs tarballs and rewrites `file:` refs in package.json.
+
+### 2. Create/Update docker-compose.yml
+
+```yaml
+services:
+  backend:
+    build:
+      context: .
+      dockerfile: backend/Dockerfile
+    ports:
+      - "${PORT:-4020}:${PORT:-4020}"
+    env_file: ./backend/.env
+    restart: unless-stopped
+    depends_on:
+      platform-service:
+        condition: service_healthy
+    healthcheck:
+      test: ["CMD", "node", "-e", "fetch('http://localhost:${PORT:-4020}/health')"]
+      interval: 30s
+      timeout: 3s
+      retries: 3
+
+  web:
+    build:
+      context: .
+      dockerfile: web/Dockerfile
+    ports:
+      - "3000:3000"
+    environment:
+      - NEXT_PUBLIC_API_URL=http://backend:${PORT:-4020}
+```
+
+### 3. Build & Test Locally
+
+```bash
+# Build
+docker compose build
+
+# Run
+docker compose up -d
+
+# Verify health
+docker compose ps
+curl -s http://localhost:<port>/health | jq .
+
+# Check logs
+docker compose logs backend --tail=20
+
+# Run smoke test
+curl -s http://localhost:<port>/api/<endpoint> | jq .
+
+# Cleanup
+docker compose down
+```
+
+### 4. Security Scan
+
+```bash
+# Scan the built image
+docker scout cves <image>
+
+# Check for leaked secrets
+docker history <image> --no-trunc | grep -i "secret\|key\|password"
+```
+
+### 5. Optimize Image Size
+
+```bash
+# Check image size
+docker images | grep <product>
+
+# Target: < 200MB for backend services
+# If too large, check:
+# - Are devDependencies excluded? (use --prod install)
+# - Is the build stage copying unnecessary files?
+# - Are node_modules pruned in the production stage?
+```
+
+### 6. Commit
+
+```bash
+git add Dockerfile docker-compose.yml
+git commit -m "chore(docker): production-ready Docker setup
+
+- Multi-stage build (builder + production)
+- Non-root user for security
+- Health check configured
+- Corporate network workarounds in build stage only
+- Production image: ~NMB"
+git push
+```
+
+## Checklist
+
+- [ ] Base image: `node:22-slim` (never Alpine)
+- [ ] No `corepack` usage
+- [ ] `strict-ssl false` in build stage
+- [ ] Multi-stage build (builder → production)
+- [ ] Non-root user in production stage
+- [ ] Health check configured
+- [ ] `NODE_ENV=production` in production stage
+- [ ] No secrets in image layers
+- [ ] `.dockerignore` excludes: node_modules, .git, .env, dist, coverage
+- [ ] Image size < 200MB
diff --git a/AI.dev/PROMPTS/ecosystem-audit.md b/AI.dev/PROMPTS/ecosystem-audit.md
new file mode 100644
index 00000000..ad2b8179
--- /dev/null
+++ b/AI.dev/PROMPTS/ecosystem-audit.md
@@ -0,0 +1,148 @@
+---
+name: ecosystem-audit
+description: 'Run a full health audit across the ByteLyst ecosystem — builds, tests, types, dependencies, config drift, and produce an actionable dashboard.'
+argument-hint: 'Depth and focus, e.g. "full audit", "quick health check", "backend focus", "config drift only"'
+agent: agent
+---
+
+# Ecosystem Audit Prompt
+
+Produce a comprehensive health dashboard across all ByteLyst repos with actionable findings.
+
+## Context — ByteLyst Ecosystem
+
+**37 repos** in `D:\BYTELYST\CODE\`, including:
+
+**Core platform:**
+- `learning_ai_common_plat` — shared packages + services
+
+**Active products (with backends):**
+- `learning_ai_efforise` (EffoRise, port 4020)
+- `learning_ai_flowmonk` (FlowMonk, port 4017)
+- `learning_ai_dev_intelli` (DevIntelli, port 4021)
+- `learning_ai_peakpulse` (PeakPulse, port 4010)
+- `learning_ai_clock` (ChronoMind, port 4011)
+- `learning_ai_jarvis_jr` (JarvisJr, port 4012)
+- `learning_ai_fastgap` (NomGap, port 4013)
+- `learning_multimodal_memory_agents` (MindLyst, port 4014)
+
+**Active products (platform-only):**
+- `learning_ai_auth_app` (ByteLyst Auth — no backend)
+- `learning_ai_notes` (NoteLett)
+- `learning_ai_trails` (ActionTrail)
+
+**Tooling & infrastructure:**
+- `learning_ai_local_llms`, `learning_ai_local_memory_gpt`
+- `learning_windsurf_setup`, `learning_claude_code_setup`, `learning_sidecar_setup`
+- `learning_agent_monitoring_fx`, `learning_agentic_tools_portal`
+
+## Audit Dimensions
+
+### 1. Build Health
+For each repo with a `package.json`:
+```bash
+pnpm install --frozen-lockfile  # Can deps resolve?
+pnpm build                       # Does it compile?
+```
+
+### 2. Type Safety
+```bash
+pnpm typecheck                   # TypeScript clean?
+```
+
+### 3. Test Health
+```bash
+pnpm test --run                  # All tests pass?
+```
+Record: total tests, passing, failing, skipped.
+
+### 4. Config Consistency
+Check alignment across repos:
+- `.npmrc` matches canonical template?
+- `.nvmrc` specifies Node 22?
+- `tsconfig.json` extends base correctly?
+- `.editorconfig` present?
+- `shared/product.json` correct?
+- `.env.example` up to date?
+
+### 5. Package Version Alignment
+Verify shared deps are on compatible versions:
+- TypeScript, Zod, Fastify, Vitest, React, Next.js
+- `@bytelyst/*` packages (all on `workspace:*` or `file:`)
+
+### 6. Security
+```bash
+pnpm audit
+# Check for high/critical vulnerabilities
+```
+
+### 7. Documentation Currency
+- AGENTS.md matches current layout?
+- README.md has setup instructions?
+- CLAUDE.md exists?
+
+### 8. Git Hygiene
+- Any repos with uncommitted changes?
+- Any repos behind remote?
+- Any repos with merge conflicts?
+
+## Output: Ecosystem Dashboard
+
+```markdown
+# ByteLyst Ecosystem Health Dashboard
+> Generated: <date>
+
+## Executive Summary
+- Repos audited: N
+- 🟢 Healthy: N
+- 🟡 Issues: N
+- 🔴 Critical: N
+
+## Scorecard
+
+| Repo | Build | Types | Tests | Config | Deps | Security | Docs | Git |
+|------|-------|-------|-------|--------|------|----------|------|-----|
+| common_plat | ✅ | ✅ | 876/876 | ✅ | ✅ | ✅ | ✅ | clean |
+| efforise | ✅ | ✅ | 65/65 | ✅ | ✅ | ⚠️ 2 | ✅ | clean |
+| flowmonk | ✅ | ⚠️ 3 | 196/196 | ✅ | ✅ | ✅ | ✅ | dirty |
+| ... | | | | | | | | |
+
+## Critical Issues (Fix First)
+| Repo | Issue | Impact | Fix |
+|------|-------|--------|-----|
+
+## Action Queue (Prioritized)
+| # | Repo | Action | Effort | Impact |
+|---|------|--------|--------|--------|
+| 1 | ... | ... | S/M/L | High/Med/Low |
+
+## Config Drift Report
+| Config | Expected | Drifted Repos |
+|--------|----------|--------------|
+| .npmrc | canonical template | <list> |
+| .nvmrc | "22" | <list> |
+
+## Dependency Alignment
+| Package | Version | Aligned | Misaligned |
+|---------|---------|---------|-----------|
+```
+
+## Execution Tips
+
+- **Start with common_plat** — it's the foundation
+- **Skip node_modules-only repos** — focus on active development repos
+- **Parallelize where possible** — run independent repo checks simultaneously
+- **Time-box expensive checks** — if `pnpm install` takes >2min, skip and note
+
+## Commit
+
+```bash
+# If you fix issues during audit:
+cd <repo>
+git add .
+git commit -m "fix(<scope>): resolve audit findings
+
+- <finding 1>
+- <finding 2>"
+git push
+```
diff --git a/AI.dev/PROMPTS/new-product-scaffold.md b/AI.dev/PROMPTS/new-product-scaffold.md
new file mode 100644
index 00000000..d80804d8
--- /dev/null
+++ b/AI.dev/PROMPTS/new-product-scaffold.md
@@ -0,0 +1,179 @@
+---
+name: new-product-scaffold
+description: 'Scaffold a new ByteLyst product repo with backend, web, mobile, and full ecosystem integration.'
+argument-hint: 'Product name, ID, and brief description, e.g. "TrackMate, trackmate, GPS-based workout tracker"'
+agent: agent
+---
+
+# New Product Scaffold Prompt
+
+Create a new ByteLyst ecosystem product from scratch with proper platform integration, shared package usage, and consistent patterns.
+
+## Context — ByteLyst Ecosystem
+
+You are scaffolding a new product in the ByteLyst multi-repo ecosystem (`D:\BYTELYST\CODE\`).
+
+**Sibling products for reference:**
+- EffoRise (`learning_ai_efforise`) — identity-based habit tracker
+- FlowMonk (`learning_ai_flowmonk`) — agent-first planning platform
+- DevIntelli (`learning_ai_dev_intelli`) — developer intelligence
+- PeakPulse (`learning_ai_peakpulse`) — fitness tracker
+- NomGap (`learning_ai_fastgap`) — fasting tracker
+
+**All products share:**
+- `platform-service` (port 4003) for auth, flags, telemetry, billing
+- `@bytelyst/*` packages for infrastructure
+- Same Fastify module pattern, Zod validation, Vitest testing
+- Design tokens from `@bytelyst/design-tokens`
+- pnpm workspaces with `file:` refs to common platform
+
+## Scaffold Checklist
+
+### 1. Create Root Structure
+
+```
+learning_ai_<repo_name>/
+├── backend/                     # Fastify 5 product backend
+├── web/ or client/              # Next.js or Vite+React SPA
+├── mobile/                      # React Native + Expo (optional)
+├── shared/
+│   └── product.json             # Canonical product identity
+├── docs/
+├── scripts/
+│   ├── secret-scan-repo.sh
+│   └── secret-scan-staged.sh
+├── .editorconfig
+├── .gitignore
+├── .npmrc                       # From canonical template (never hand-edit)
+├── .nvmrc                       # "22"
+├── .windsurfrules
+├── AGENTS.md
+├── CLAUDE.md
+├── README.md
+├── package.json                 # Root workspace scripts
+├── pnpm-workspace.yaml
+├── docker-compose.yml
+└── tsconfig.json
+```
+
+### 2. Create `shared/product.json`
+
+```json
+{
+  "productId": "<product_id>",
+  "productName": "<ProductName>",
+  "productDescription": "<one-line description>",
+  "domain": "<product>.app",
+  "bundleIdIos": "com.bytelyst.<product_id>",
+  "bundleIdAndroid": "com.bytelyst.<product_id>",
+  "backendPort": <next_available_port>,
+  "tokenNamespace": "--<prefix>-"
+}
+```
+
+**Port allocation:** Check existing products to find the next available port:
+- EffoRise: 4020, DevIntelli: 4021, FlowMonk: 4017, PeakPulse: 4010, ChronoMind: 4011, JarvisJr: 4012, NomGap: 4013, MindLyst: 4014
+
+### 3. Backend Setup
+
+Follow the pattern from EffoRise or FlowMonk:
+
+```
+backend/
+├── src/
+│   ├── server.ts                # createServiceApp() + startService()
+│   ├── lib/
+│   │   ├── config.ts            # Zod env schema (self-contained, no @bytelyst/config zod)
+│   │   ├── product-config.ts    # Read shared/product.json
+│   │   ├── auth.ts              # Re-export from @bytelyst/fastify-auth
+│   │   ├── datastore.ts         # @bytelyst/datastore bridge
+│   │   ├── errors.ts            # Re-export from @bytelyst/errors
+│   │   ├── field-encrypt.ts     # @bytelyst/field-encrypt if needed
+│   │   ├── request-context.ts   # getUserId(req), getRequestProductId(req)
+│   │   ├── telemetry.ts         # @bytelyst/backend-telemetry
+│   │   └── feature-flags.ts     # @bytelyst/backend-flags
+│   └── modules/
+│       └── <first_module>/      # types.ts → repository.ts → routes.ts
+├── __tests__/
+├── .env.example
+├── Dockerfile
+├── package.json
+├── tsconfig.json
+└── vitest.config.ts
+```
+
+**Required `package.json` dependencies:**
+```json
+{
+  "dependencies": {
+    "@bytelyst/fastify-core": "file:../../learning_ai_common_plat/packages/fastify-core",
+    "@bytelyst/config": "file:../../learning_ai_common_plat/packages/config",
+    "@bytelyst/errors": "file:../../learning_ai_common_plat/packages/errors",
+    "@bytelyst/datastore": "file:../../learning_ai_common_plat/packages/datastore",
+    "@bytelyst/auth": "file:../../learning_ai_common_plat/packages/auth",
+    "@bytelyst/fastify-auth": "file:../../learning_ai_common_plat/packages/fastify-auth"
+  }
+}
+```
+
+### 4. Web Setup
+
+Use Next.js (App Router) or Vite + React. Include:
+- Auth via `@bytelyst/react-auth`
+- API client via `@bytelyst/api-client`
+- Design tokens via `@bytelyst/design-tokens` with product namespace (`--<prefix>-*`)
+- UI components via `@bytelyst/ui`
+- Feature flags via `@bytelyst/feature-flag-client`
+
+### 5. AGENTS.md
+
+Follow the exact structure from sibling repos. Include:
+- Project Identity table
+- Repo Layout tree
+- Tech Stack table
+- Coding Conventions (MUST / MUST NOT)
+- Cosmos Containers table
+- Build & Test Commands
+- Environment Variables
+- Cross-Repo Automation reference
+
+### 6. pnpm-workspace.yaml
+
+```yaml
+packages:
+  - 'backend'
+  - 'web'
+  - '../learning_ai_common_plat/packages/*'
+```
+
+### 7. Validation
+
+After scaffolding:
+```bash
+pnpm install
+cd backend && pnpm typecheck && pnpm test && pnpm build
+cd ../web && pnpm typecheck && pnpm build
+```
+
+### 8. Commit & Push
+
+```bash
+git init
+git add .
+git commit -m "feat(<product>): scaffold product repo
+
+- Backend: Fastify 5, @bytelyst/* integration, first module
+- Web: Next.js/Vite + React, auth + design tokens
+- Shared: product.json, AGENTS.md, README.md
+- Tests: initial test suite passing"
+git remote add origin <remote_url>
+git push -u origin main
+```
+
+## Guardrails
+
+- **Never hardcode productId** — always read from `shared/product.json`
+- **Never use console.log** — use `req.log` / `app.log`
+- **Never hand-edit .npmrc** — sync from canonical template
+- **Always include tests** — even the scaffold should have passing tests
+- **Always include AGENTS.md** — this is the source of truth for AI assistants
diff --git a/AI.dev/PROMPTS/platform-integration.md b/AI.dev/PROMPTS/platform-integration.md
new file mode 100644
index 00000000..6530bed5
--- /dev/null
+++ b/AI.dev/PROMPTS/platform-integration.md
@@ -0,0 +1,181 @@
+---
+name: platform-integration
+description: 'Wire a product repo into the ByteLyst common platform ecosystem — auth, flags, telemetry, design tokens, and shared packages.'
+argument-hint: 'Product repo name and integration scope, e.g. "learning_ai_efforise — full integration", "learning_ai_peakpulse — auth + flags only"'
+agent: agent
+---
+
+# Platform Integration Prompt
+
+Connect a product repository to the ByteLyst common platform, wiring up auth, feature flags, telemetry, design tokens, and shared packages.
+
+## Context — Integration Architecture
+
+```
+Product Repo (e.g. learning_ai_efforise)
+├── backend/  ──→  @bytelyst/fastify-core, config, errors, datastore, auth, fastify-auth
+├── web/      ──→  @bytelyst/react-auth, api-client, design-tokens, ui, feature-flag-client
+├── mobile/   ──→  @bytelyst/auth-client, telemetry-client, feature-flag-client
+└── shared/product.json  ──→  Product identity consumed by all layers
+            │
+            ▼
+    platform-service (port 4003)
+    ├── Auth (JWT issue/validate)
+    ├── Feature flags (FNV-1a rollout)
+    ├── Telemetry (event ingestion)
+    ├── Billing (Stripe subscriptions)
+    └── Notifications (email, push)
+```
+
+## Integration Checklist
+
+### 1. Product Identity (`shared/product.json`)
+
+Ensure this file exists and is correct:
+```json
+{
+  "productId": "<product_id>",
+  "productName": "<ProductName>",
+  "backendPort": <port>,
+  "tokenNamespace": "--<prefix>-"
+}
+```
+
+### 2. Backend Integration
+
+#### Config (`backend/src/lib/config.ts`)
+- Self-contained Zod schema (do NOT import zod from @bytelyst/config)
+- Include: PORT, HOST, NODE_ENV, DB_PROVIDER, JWT_SECRET, PLATFORM_SERVICE_URL, CORS_ORIGIN
+
+#### Auth (`backend/src/lib/auth.ts`)
+- Re-export from `@bytelyst/fastify-auth`
+- Wire auth hook in `server.ts` for protected routes
+
+#### Datastore (`backend/src/lib/datastore.ts`)
+- Re-export from `@bytelyst/datastore`
+- Support `DB_PROVIDER=memory` for dev/test and `DB_PROVIDER=cosmos` for production
+
+#### Product Config (`backend/src/lib/product-config.ts`)
+- Read `shared/product.json`
+- Export `PRODUCT_ID`, `PRODUCT_NAME`, etc.
+
+#### Request Context (`backend/src/lib/request-context.ts`)
+- `getUserId(req)` — extract userId from JWT
+- `getRequestProductId(req)` — return productId from config
+
+#### Feature Flags (`backend/src/lib/feature-flags.ts`)
+- Initialize `@bytelyst/backend-flags` with product config
+- Register product-specific flags
+
+#### Telemetry (`backend/src/lib/telemetry.ts`)
+- Initialize `@bytelyst/backend-telemetry`
+- Buffer events for platform-service ingestion
+
+#### Diagnostics (`backend/src/lib/register-diagnostics.ts`)
+- Register `/api/diagnostics/flags`, `/api/diagnostics/events` routes
+- Health endpoint at `GET /health`
+
+### 3. Web Integration
+
+#### Auth (`web/src/lib/auth.ts`)
+```typescript
+import { createAuthContext } from '@bytelyst/react-auth';
+export const { AuthProvider, useAuth } = createAuthContext({
+  platformUrl: process.env.NEXT_PUBLIC_PLATFORM_SERVICE_URL || 'http://localhost:4003',
+  productId: '<product_id>',
+});
+```
+
+#### API Client (`web/src/lib/api-helpers.ts`)
+```typescript
+import { createApiClient } from '@bytelyst/api-client';
+export function createProductClient(getToken: () => string | null) {
+  return createApiClient({
+    baseUrl: process.env.NEXT_PUBLIC_API_URL || 'http://localhost:<port>',
+    getToken,
+  });
+}
+```
+
+#### Design Tokens (`web/src/app/globals.css` or `client/src/index.css`)
+- Import `@bytelyst/design-tokens` CSS
+- Use product namespace: `--<prefix>-*` custom properties
+- Never hardcode hex colors
+
+#### Platform Clients
+- `@bytelyst/feature-flag-client` — feature gating
+- `@bytelyst/telemetry-client` — event tracking
+- `@bytelyst/kill-switch-client` — remote kill switch
+- `@bytelyst/diagnostics-client` — health monitoring
+
+### 4. Mobile Integration (if applicable)
+
+- `@bytelyst/auth-client` — login/register/token management
+- `@bytelyst/telemetry-client` — event buffering
+- `@bytelyst/feature-flag-client` — feature gating
+- `@bytelyst/kill-switch-client` — remote disable
+- `@bytelyst/offline-queue` — offline-first data sync
+
+### 5. pnpm Workspace Configuration
+
+`pnpm-workspace.yaml`:
+```yaml
+packages:
+  - 'backend'
+  - 'web'
+  - 'mobile'
+  - '../learning_ai_common_plat/packages/*'
+```
+
+`.npmrc` — sync from canonical template:
+```bash
+cd ../learning_ai_common_plat && bash scripts/sync-npmrc.sh
+```
+
+### 6. Docker Support
+
+`docker-compose.yml`:
+```yaml
+services:
+  backend:
+    build: ./backend
+    ports:
+      - "<port>:<port>"
+    env_file: ./backend/.env
+    depends_on:
+      - platform-service
+```
+
+### 7. Validation
+
+```bash
+# Backend
+cd backend && pnpm install && pnpm typecheck && pnpm test && pnpm build
+
+# Web
+cd web && pnpm install && pnpm typecheck && pnpm build
+
+# Verify auth flow
+curl -X POST http://localhost:4003/api/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"email":"test@example.com","password":"password"}'
+# Use returned token against product backend:
+curl http://localhost:<port>/health
+curl http://localhost:<port>/api/<endpoint> \
+  -H "Authorization: Bearer <token>"
+```
+
+### 8. Commit
+
+```bash
+git add .
+git commit -m "feat(platform): wire @bytelyst/* ecosystem integration
+
+- Auth: JWT via @bytelyst/fastify-auth + @bytelyst/react-auth
+- Data: @bytelyst/datastore with memory/cosmos providers
+- Flags: @bytelyst/feature-flag-client
+- Telemetry: @bytelyst/telemetry-client
+- Tokens: @bytelyst/design-tokens with --<prefix>-* namespace
+- Tests: all passing"
+git push
+```
diff --git a/AI.dev/PROMPTS/prd-to-implementation.md b/AI.dev/PROMPTS/prd-to-implementation.md
new file mode 100644
index 00000000..434cadb5
--- /dev/null
+++ b/AI.dev/PROMPTS/prd-to-implementation.md
@@ -0,0 +1,120 @@
+---
+name: prd-to-implementation
+description: 'Convert a PRD into a concrete, phased implementation plan with file-level detail and dependency ordering.'
+argument-hint: 'Path to PRD file or inline feature description, e.g. "docs/PRD.md", "add social fasting feature to NomGap"'
+agent: agent
+---
+
+# PRD → Implementation Plan Prompt
+
+Transform a Product Requirements Document into a detailed, phased implementation plan that an AI agent or developer can execute directly.
+
+## Context — ByteLyst Ecosystem
+
+You are planning implementation within the ByteLyst ecosystem (`D:\BYTELYST\CODE\`).
+
+**Architecture awareness:**
+- Products have: `backend/` (Fastify 5), `web/` (Next.js or Vite+React), `mobile/` (Expo), `shared/`
+- Backend modules follow: `types.ts` → `repository.ts` → `routes.ts`
+- All data lives in Azure Cosmos DB with `productId` multi-tenancy
+- Shared packages are `@bytelyst/*` from `learning_ai_common_plat/packages/`
+- Platform service (port 4003) handles: auth, flags, telemetry, billing, notifications
+- Design tokens provide all UI colors via CSS custom properties
+
+## Process
+
+### Step 1: PRD Analysis
+
+Read the PRD and extract:
+
+1. **Core features** — what must be built
+2. **User flows** — how users interact
+3. **Data model** — what gets stored
+4. **API surface** — endpoints needed
+5. **UI screens** — pages/components needed
+6. **Constraints** — performance, security, compatibility
+7. **Out of scope** — what to explicitly defer
+
+### Step 2: Dependency Mapping
+
+Determine what already exists:
+- Which `@bytelyst/*` packages are needed?
+- Does any sibling product have a similar pattern to reference?
+- Are new Cosmos containers needed?
+- Are new platform-service modules needed?
+- Are design token additions needed?
+
+### Step 3: Phase Decomposition
+
+Break into phases following this priority order:
+
+1. **P0 — Foundation** (always first)
+   - Data model / Cosmos containers
+   - Backend types + Zod schemas
+   - Repository layer with basic CRUD
+   - Routes with auth + validation
+   - Initial tests
+
+2. **P1 — Core Features**
+   - Primary business logic
+   - Main API endpoints
+   - Web/mobile screens for primary flows
+   - Integration tests
+
+3. **P2 — Secondary Features**
+   - Less critical endpoints
+   - Settings, admin views
+   - Edge case handling
+   - Additional tests
+
+4. **P3 — Polish**
+   - Error handling refinement
+   - Loading states, empty states
+   - Accessibility
+   - Performance optimization
+   - E2E tests
+
+### Step 4: Generate Plan Document
+
+Output a `docs/IMPLEMENTATION_PLAN.md` with:
+
+```markdown
+# <Feature Name> Implementation Plan
+
+> Generated from: <PRD path>
+> Product: <product name> (<productId>)
+> Estimated phases: N
+
+## Data Model
+
+| Container | Partition Key | Fields | Purpose |
+|-----------|--------------|--------|---------|
+
+## API Surface
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+
+## Phase Breakdown
+
+### Phase 0: Foundation
+- [ ] `backend/src/modules/<name>/types.ts` — Zod schemas
+- [ ] `backend/src/modules/<name>/repository.ts` — Cosmos CRUD
+- [ ] `backend/src/modules/<name>/routes.ts` — REST endpoints
+- [ ] `backend/src/modules/<name>/<name>.test.ts` — Unit tests
+- [ ] Register routes in `backend/src/server.ts`
+**Validation:** `pnpm --filter backend test && pnpm --filter backend typecheck`
+**Commit:** `feat(<module>): add <name> foundation (types, repo, routes, tests)`
+
+### Phase 1: Core Features
+...
+```
+
+## Guardrails
+
+- **Every phase must be independently deployable** — no half-built features
+- **Every phase includes tests** — minimum: unit tests for repository + routes
+- **Backend first, frontend second** — API must exist before UI consumes it
+- **Use existing patterns** — reference sibling product repos, don't reinvent
+- **Include validation commands** — exact `pnpm` commands for each phase
+- **Include commit messages** — pre-written conventional commits
diff --git a/AI.dev/PROMPTS/pre-release-validation.md b/AI.dev/PROMPTS/pre-release-validation.md
new file mode 100644
index 00000000..c66899f8
--- /dev/null
+++ b/AI.dev/PROMPTS/pre-release-validation.md
@@ -0,0 +1,157 @@
+---
+name: pre-release-validation
+description: 'Run comprehensive pre-release checks across one or more ByteLyst repos: build, typecheck, test, lint, security audit, and bundle analysis.'
+argument-hint: 'Repos and depth, e.g. "learning_ai_efforise full", "all backends quick", "common_plat + flowmonk"'
+agent: agent
+---
+
+# Pre-Release Validation Prompt
+
+Execute a comprehensive pre-release validation workflow across ByteLyst repos with incremental fixes and commits.
+
+## Context — ByteLyst Release Conventions
+
+- **Build order:** common_plat packages → common_plat services → product backends → web/mobile
+- **Commit after each fix:** Keep history clean, push after each phase
+- **Commit format:** `fix(scope): <issue>`, `test(scope): fix failing tests`, `style(scope): format fixes`
+
+## Validation Phases
+
+### Phase 1: Common Platform (always first)
+
+```bash
+cd learning_ai_common_plat
+
+# 1. Install & build
+pnpm install && pnpm build
+
+# 2. Type-check all packages and services
+pnpm typecheck
+# Fix → git add . && git commit -m "fix(common): type-check fixes" && git push
+
+# 3. Run all tests
+pnpm test
+# Fix → git add . && git commit -m "test(common): fix failing tests" && git push
+
+# 4. Security audit
+pnpm audit
+# Fix → git add . && git commit -m "fix(common): security updates" && git push
+```
+
+### Phase 2: Product Backend
+
+```bash
+cd <product>/backend
+
+# 1. Install & build
+pnpm install && pnpm build
+
+# 2. Type-check
+pnpm typecheck
+# Fix → git commit -m "fix(backend): type-check fixes"
+
+# 3. Tests
+pnpm test
+# Fix → git commit -m "test(backend): fix failing tests"
+
+# 4. Verify health endpoint
+# Start in background, test, stop:
+pnpm dev &
+sleep 3
+curl -s http://localhost:<port>/health | jq .
+kill %1
+```
+
+### Phase 3: Web Client
+
+```bash
+cd <product>/web  # or client/
+
+# 1. Type-check
+pnpm typecheck
+# Fix → git commit -m "fix(web): type-check fixes"
+
+# 2. Lint
+pnpm lint
+# Fix → git commit -m "fix(web): lint fixes"
+
+# 3. Build (catches runtime issues)
+pnpm build
+# Fix → git commit -m "fix(web): build fixes"
+
+# 4. Tests (if any)
+pnpm test
+# Fix → git commit -m "test(web): fix failing tests"
+```
+
+### Phase 4: Mobile (if applicable)
+
+```bash
+cd <product>/mobile
+
+# 1. Type-check
+pnpm typecheck
+# Fix → git commit -m "fix(mobile): type-check fixes"
+
+# 2. Tests (if any)
+pnpm test
+# Fix → git commit -m "test(mobile): fix failing tests"
+```
+
+### Phase 5: Integration Smoke Test
+
+```bash
+# Start all services
+cd <product> && docker compose up -d
+sleep 10
+
+# Health checks
+curl -s http://localhost:4003/health | jq .
+curl -s http://localhost:<product-port>/health | jq .
+
+# Basic auth flow
+TOKEN=$(curl -s -X POST http://localhost:4003/api/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"email":"test@test.com","password":"password"}' | jq -r '.token')
+
+curl -s http://localhost:<product-port>/api/<endpoint> \
+  -H "Authorization: Bearer $TOKEN" | jq .
+
+# Cleanup
+docker compose down
+```
+
+## Validation Matrix
+
+Check all that apply:
+
+| Check | Backend | Web | Mobile | Platform |
+|-------|---------|-----|--------|----------|
+| `pnpm install` | ☐ | ☐ | ☐ | ☐ |
+| `pnpm build` | ☐ | ☐ | ☐ | ☐ |
+| `pnpm typecheck` | ☐ | ☐ | ☐ | ☐ |
+| `pnpm test` | ☐ | ☐ | ☐ | ☐ |
+| `pnpm lint` | ☐ | ☐ | ☐ | ☐ |
+| `pnpm audit` | ☐ | ☐ | ☐ | ☐ |
+| Health endpoint | ☐ | — | — | ☐ |
+| Auth flow | ☐ | ☐ | ☐ | ☐ |
+
+## Report Format
+
+```markdown
+## Pre-Release Validation: <Product>
+
+### Results
+| Phase | Status | Issues Found | Issues Fixed | Commits |
+|-------|--------|-------------|-------------|---------|
+| Common Platform | ✅/❌ | N | N | hash1, hash2 |
+| Backend | ✅/❌ | N | N | hash3 |
+| Web | ✅/❌ | N | N | hash4 |
+| Mobile | ✅/❌ | N | N | — |
+| Integration | ✅/❌ | N | N | — |
+
+### Blockers
+- <any issues that couldn't be fixed>
+
+### Ready for Release: ✅ YES / ❌ NO
+```
diff --git a/AI.dev/PROMPTS/refactor-with-tests.md b/AI.dev/PROMPTS/refactor-with-tests.md
new file mode 100644
index 00000000..9b79a101
--- /dev/null
+++ b/AI.dev/PROMPTS/refactor-with-tests.md
@@ -0,0 +1,146 @@
+---
+name: refactor-with-tests
+description: 'Safely refactor code with test-first methodology — capture behavior, refactor, verify nothing broke.'
+argument-hint: 'Target module/file and refactor goal, e.g. "backend/src/modules/auth — extract token service", "simplify scheduler engine in FlowMonk"'
+agent: agent
+---
+
+# Refactor with Tests Prompt
+
+Safely refactor code by first capturing existing behavior in tests, then restructuring while keeping all tests green.
+
+## Context — ByteLyst Conventions
+
+- **Test runner:** Vitest (TypeScript), pytest (Python)
+- **Test location:** Same module directory or `__tests__/`
+- **Never modify tests to make them pass** — fix the code
+- **Commit format:** `refactor(scope): description`
+
+## Refactor Protocol
+
+### Step 1: Understand Current Behavior
+
+Before touching any code:
+
+1. **Read the code** — understand what it does, not just the structure
+2. **Read existing tests** — understand what's already covered
+3. **Run existing tests** — confirm they pass:
+   ```bash
+   pnpm test
+   pnpm typecheck
+   ```
+4. **Identify the API surface** — what do consumers depend on?
+   - Exported functions/types
+   - REST endpoint contracts
+   - Side effects (database writes, events emitted)
+
+### Step 2: Add Missing Tests (Before Refactoring)
+
+If test coverage is insufficient, add tests for current behavior FIRST:
+
+```typescript
+// Capture existing behavior before refactoring
+describe('<Module> — pre-refactor behavior capture', () => {
+  it('should return X when given Y', () => {
+    // Test current behavior, even if the implementation is ugly
+  });
+
+  it('should throw NotFoundError for missing items', () => {
+    // Edge cases that must be preserved
+  });
+
+  it('should include productId in all created documents', () => {
+    // Ecosystem invariants
+  });
+});
+```
+
+**Commit these tests separately:**
+```bash
+git add .
+git commit -m "test(<scope>): capture pre-refactor behavior (N tests)"
+```
+
+### Step 3: Plan the Refactor
+
+Document what will change and what must stay the same:
+
+- **Changing:** Internal structure, file organization, naming
+- **Preserving:** API surface, behavior, test contracts
+- **New patterns:** What you're moving toward (e.g., extract service class, split module)
+
+### Step 4: Refactor in Small Steps
+
+For each step:
+
+1. Make ONE structural change
+2. Run tests: `pnpm test`
+3. Run typecheck: `pnpm typecheck`
+4. If tests pass → commit
+5. If tests fail → undo and retry with smaller step
+
+```bash
+# After each small refactor step
+pnpm test && pnpm typecheck && \
+git add . && git commit -m "refactor(<scope>): <what changed>"
+```
+
+### Step 5: Verify Completeness
+
+After all refactoring:
+
+```bash
+# Full validation
+pnpm build && pnpm typecheck && pnpm test
+
+# Check no exports were broken
+# If this is a @bytelyst/* package:
+cd learning_ai_common_plat && pnpm build && pnpm test
+```
+
+### Step 6: Update Documentation
+
+If the refactor changed:
+- File locations → update AGENTS.md repo layout
+- API surface → update README.md or API docs
+- Module structure → update any roadmap or architecture docs
+
+```bash
+git add .
+git commit -m "docs(<scope>): update docs after <module> refactor"
+git push
+```
+
+## Common Refactor Patterns
+
+### Extract Service Class
+```
+Before: routes.ts has business logic mixed with HTTP handling
+After:  routes.ts → service.ts → repository.ts (routes are thin)
+```
+
+### Split Module
+```
+Before: modules/schedule/ has 500-line routes.ts
+After:  modules/schedule/ + modules/schedule-entries/ (each focused)
+```
+
+### Extract Shared Package
+```
+Before: Two products have duplicate utility code
+After:  New @bytelyst/* package consumed by both
+```
+
+### Consolidate Re-exports
+```
+Before: Each file imports from @bytelyst/* directly
+After:  src/lib/ re-exports, internal files import from src/lib/
+```
+
+## Guardrails
+
+- **Test first, refactor second.** Never refactor without test coverage.
+- **Small commits.** Each commit should be revertible without losing other changes.
+- **No behavior changes.** Refactoring changes structure, not behavior. If you're fixing bugs, that's a separate commit.
+- **No export changes** without updating all consumers.
+- **Run the full suite** after every commit, not just the changed module's tests.
diff --git a/AI.dev/PROMPTS/roadmap-execution.md b/AI.dev/PROMPTS/roadmap-execution.md
new file mode 100644
index 00000000..a060a7a1
--- /dev/null
+++ b/AI.dev/PROMPTS/roadmap-execution.md
@@ -0,0 +1,124 @@
+---
+name: roadmap-execution
+description: 'Execute a phased roadmap with checkpoint commits, incremental validation, and progress tracking.'
+argument-hint: 'Roadmap file path or inline description, e.g. "docs/ROADMAP.md", "Phase 2 of FlowMonk backend", "implement push notifications"'
+agent: agent
+---
+
+# Roadmap Execution Prompt
+
+Execute a phased implementation roadmap with disciplined checkpoint commits, incremental validation, and progress tracking.
+
+## Context — ByteLyst Ecosystem
+
+You are working in the ByteLyst multi-repo ecosystem (`D:\BYTELYST\CODE\`).
+
+**Key conventions:**
+- **Package manager:** pnpm (workspace). Never use npm or yarn.
+- **Module system:** ESM everywhere (`"type": "module"`, `.js` extensions in imports)
+- **Backend pattern:** Fastify 5 + Zod validation. Modules follow `types.ts` → `repository.ts` → `routes.ts`
+- **Shared packages:** `@bytelyst/*` in `learning_ai_common_plat/packages/`
+- **Services:** `@lysnrai/*` in `learning_ai_common_plat/services/`
+- **Product identity:** Every Cosmos document MUST include `productId` field
+- **Design tokens:** Never hardcode colors — use `@bytelyst/design-tokens` CSS custom properties
+- **Commit format:** `type(scope): description` — types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`
+- **Tests:** Vitest for TS, pytest for Python. Never modify tests to make them pass — fix the code.
+
+## Execution Protocol
+
+### Phase 0: Understand the Roadmap
+
+1. **Read the roadmap document** (if provided as file path) or parse the inline description
+2. **Identify all phases/milestones** and their dependencies
+3. **Estimate scope** for each phase (files touched, tests needed, risk level)
+4. **Create a tracker** — write a `docs/IMPLEMENTATION_TRACKER.md` with:
+   - Phase list with `[ ]` / `[/]` / `[x]` status
+   - Key files to create/modify per phase
+   - Validation criteria per phase
+   - Commit message for each checkpoint
+
+### Phase N: Execute Each Phase
+
+For each phase, follow this cycle:
+
+#### Step 1: Plan
+- List files to create or modify
+- Identify which `@bytelyst/*` packages are needed
+- Note any new dependencies
+
+#### Step 2: Implement
+- Write code following the established patterns in this repo
+- Use existing `src/lib/` re-exports for shared packages
+- Every new API endpoint gets Zod schema validation
+- Every new Cosmos container uses `productId` partition-aware queries
+
+#### Step 3: Test
+- Add tests alongside implementation (same module directory or `__tests__/`)
+- Run tests: `pnpm test` or `pnpm --filter <package> test`
+- Run typecheck: `pnpm typecheck` or `pnpm --filter <package> typecheck`
+- Fix any failures before proceeding
+
+#### Step 4: Validate
+- Verify the feature works end-to-end (API → UI if applicable)
+- Check for regressions: run the full test suite
+- Review for ecosystem compliance:
+  - ✅ `productId` on all Cosmos docs
+  - ✅ No `console.log` (use `req.log` / `app.log`)
+  - ✅ No `any` types
+  - ✅ No hardcoded colors
+  - ✅ No hardcoded secrets
+
+#### Step 5: Checkpoint Commit
+```bash
+git add .
+git commit -m "feat(<scope>): <phase-description>
+
+- <key change 1>
+- <key change 2>
+- Tests: <N> new tests, all passing"
+git push
+```
+
+#### Step 6: Update Tracker
+- Mark the phase `[x]` in `IMPLEMENTATION_TRACKER.md`
+- Add the commit hash
+- Note any deferred items or follow-ups
+
+### Completion
+
+After all phases:
+
+1. **Run full validation:**
+   ```bash
+   pnpm build && pnpm typecheck && pnpm test
+   ```
+2. **Update AGENTS.md** if the repo layout, API endpoints, or test counts changed
+3. **Update README.md** if new features, commands, or setup steps were added
+4. **Final commit:**
+   ```bash
+   git add .
+   git commit -m "docs(<scope>): update docs for <roadmap-name> completion"
+   git push
+   ```
+
+## Output Format
+
+Report progress after each phase:
+
+```
+## Phase N: <Name> ✅
+
+**Commit:** `abc1234`
+**Files changed:** 5 created, 2 modified
+**Tests:** 12 new tests, all passing
+**Validation:** typecheck ✅, lint ✅, test ✅
+**Notes:** <any deferred items or follow-ups>
+```
+
+## Guardrails
+
+- **Never skip tests.** Every phase must include test validation.
+- **Never make big-bang commits.** Each phase gets its own checkpoint.
+- **Never break existing tests.** If a test fails, fix the code, not the test.
+- **Never hardcode values.** Use config, env vars, and design tokens.
+- **Always verify before committing.** Run typecheck + test before every commit.
diff --git a/AI.dev/PROMPTS/test-gap-analysis.md b/AI.dev/PROMPTS/test-gap-analysis.md
new file mode 100644
index 00000000..81f80616
--- /dev/null
+++ b/AI.dev/PROMPTS/test-gap-analysis.md
@@ -0,0 +1,145 @@
+---
+name: test-gap-analysis
+description: 'Identify test coverage gaps in a repo, prioritize by risk, and generate targeted tests for the most critical uncovered code.'
+argument-hint: 'Repo name or path, e.g. "learning_ai_efforise", "learning_ai_flowmonk backend only", "all product backends"'
+agent: agent
+---
+
+# Test Gap Analysis Prompt
+
+Audit test coverage in a ByteLyst repo, identify the riskiest gaps, and generate high-value tests.
+
+## Context — ByteLyst Testing Conventions
+
+- **Runner:** Vitest for all TypeScript code
+- **Pattern:** Tests live in `__tests__/` or alongside source as `<module>.test.ts`
+- **Helpers:** `buildTestApp()` via `src/test-helpers.ts` for Fastify inject testing
+- **Mocks:** `@bytelyst/testing` for shared mock utilities
+- **Coverage targets:** Backend 80%, Web 70%, Shared packages 90%
+
+## Analysis Protocol
+
+### Step 1: Inventory
+
+Scan the repo and build a map:
+
+```
+Source files:      N files
+Test files:        M files
+Coverage ratio:    M/N (% of source files with tests)
+```
+
+For each source module, classify:
+- ✅ Has tests
+- ⚠️ Has partial tests (some functions uncovered)
+- ❌ No tests
+- 🔒 Low risk (config, types-only, re-exports)
+- 🔴 High risk (business logic, data mutations, auth)
+
+### Step 2: Prioritize Gaps
+
+Rank uncovered code by risk:
+
+| Priority | Category | Why |
+|----------|----------|-----|
+| **P0** | Auth/security logic | Vulnerabilities if broken |
+| **P0** | Data mutation (repository.ts) | Data corruption if broken |
+| **P1** | Business logic (services, engines) | Core features break |
+| **P1** | API routes with validation | Contract violations |
+| **P2** | Utility functions | Indirect failures |
+| **P3** | UI components (rendering) | Visual but not critical |
+| **P4** | Config, types, re-exports | Very low risk |
+
+### Step 3: Generate Tests
+
+For each P0/P1 gap, generate tests following this structure:
+
+```typescript
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+
+describe('<Module>', () => {
+  // Setup
+  beforeEach(() => {
+    // Fresh state for each test
+  });
+
+  // Happy path
+  it('should <expected behavior> when <condition>', async () => {
+    // Arrange
+    // Act
+    // Assert
+  });
+
+  // Validation
+  it('should reject invalid input', async () => {
+    // Test Zod schema validation
+  });
+
+  // Auth
+  it('should enforce user ownership', async () => {
+    // Test that user A cannot access user B's data
+  });
+
+  // Edge cases
+  it('should handle <edge case>', async () => {
+    // Empty arrays, null values, missing fields
+  });
+
+  // Error paths
+  it('should throw NotFoundError for missing <entity>', async () => {
+    // Test error handling
+  });
+});
+```
+
+### Step 4: Run & Validate
+
+```bash
+pnpm test --coverage
+pnpm typecheck
+```
+
+### Step 5: Report
+
+Output a coverage gap report:
+
+```markdown
+## Test Gap Analysis: <Repo>
+
+### Summary
+- Source files: N
+- Test files: M (before) → M+K (after)
+- Coverage: X% → Y%
+
+### Gaps Filled (this session)
+| Module | Tests Added | Risk Level |
+|--------|-------------|------------|
+
+### Remaining Gaps
+| Module | Risk Level | Effort | Suggested Next Step |
+|--------|------------|--------|---------------------|
+
+### Recommendations
+1. ...
+2. ...
+```
+
+### Step 6: Commit
+
+```bash
+git add .
+git commit -m "test(<scope>): fill coverage gaps in <modules>
+
+- Added N tests across M modules
+- Coverage: X% → Y%
+- Focus: <P0/P1 risk areas addressed>"
+git push
+```
+
+## Anti-Patterns to Avoid
+
+- ❌ Don't write snapshot tests for API responses (too brittle)
+- ❌ Don't test private implementation details (test behavior, not internals)
+- ❌ Don't mock the thing you're testing (mock dependencies only)
+- ❌ Don't write tests that always pass regardless of code changes
+- ❌ Don't chase 100% coverage — focus on high-risk code
diff --git a/AI.dev/PROMPTS/type-safety-sweep.md b/AI.dev/PROMPTS/type-safety-sweep.md
new file mode 100644
index 00000000..30827231
--- /dev/null
+++ b/AI.dev/PROMPTS/type-safety-sweep.md
@@ -0,0 +1,137 @@
+---
+name: type-safety-sweep
+description: 'Fix TypeScript errors across a repo or the full workspace with systematic triage and minimal code changes.'
+argument-hint: 'Scope, e.g. "learning_ai_flowmonk", "all backends", "common_plat packages only"'
+agent: agent
+---
+
+# Type Safety Sweep Prompt
+
+Systematically fix TypeScript errors across ByteLyst repos with minimal, safe changes.
+
+## Context — ByteLyst TypeScript Conventions
+
+- **Target:** ES2022, `moduleResolution: NodeNext`
+- **Strict mode:** `strict: true` in all repos
+- **Base config:** Extends `../../tsconfig.base.json` (from common_plat)
+- **Module system:** ESM (`"type": "module"`) with `.js` extensions in imports
+- **No `any`:** Use Zod inference, explicit types, or `unknown` with type guards
+
+## Sweep Protocol
+
+### Step 1: Run Typecheck
+
+```bash
+# Single repo
+pnpm typecheck
+
+# Workspace-wide
+cd learning_ai_common_plat && pnpm typecheck
+cd <product> && pnpm typecheck
+```
+
+### Step 2: Triage Errors
+
+Categorize each error:
+
+| Category | Fix Strategy | Risk |
+|----------|-------------|------|
+| **Missing `.js` extension** | Add `.js` to import path | Low |
+| **Implicit `any`** | Add explicit type annotation | Low |
+| **Missing property** | Add property to interface/schema | Medium |
+| **Type mismatch** | Fix the value, not the type (usually) | Medium |
+| **Package type conflict** | Check peer dep versions | High |
+| **Structural break** | Needs design decision | High |
+
+### Step 3: Fix by Category
+
+#### Low-risk fixes (do first)
+```typescript
+// Missing .js extension
+- import { foo } from './utils';
++ import { foo } from './utils.js';
+
+// Implicit any
+- function handle(req, reply) {
++ function handle(req: FastifyRequest, reply: FastifyReply) {
+
+// Unused imports
+- import { unused, used } from './types.js';
++ import { used } from './types.js';
+```
+
+#### Medium-risk fixes
+```typescript
+// Missing property — add to schema
+const schema = z.object({
+  name: z.string(),
++ description: z.string().optional(), // Was missing
+});
+
+// Type mismatch — fix the value
+- const port: number = process.env.PORT; // string assigned to number
++ const port: number = Number(process.env.PORT) || 4003;
+```
+
+#### High-risk fixes (get approval first)
+- Package version conflicts → document and propose solution
+- Structural type breaks → explain what changed and why
+
+### Step 4: Validate
+
+After each batch of fixes:
+```bash
+pnpm typecheck  # Must pass
+pnpm test        # Must still pass
+pnpm build       # Must still build
+```
+
+### Step 5: Commit
+
+Group fixes logically:
+```bash
+# Low-risk batch
+git add .
+git commit -m "fix(<scope>): resolve TypeScript errors (import extensions, explicit types)"
+
+# Medium-risk batch
+git add .
+git commit -m "fix(<scope>): fix type mismatches in <modules>"
+
+git push
+```
+
+## Common ByteLyst Type Issues
+
+### Zod version mismatch
+**Symptom:** `Type 'z.ZodString' is not assignable to type 'z.ZodString'`
+**Fix:** Services must use self-contained Zod schemas in `src/lib/config.ts`, NOT import from @bytelyst/config
+
+### Package export types
+**Symptom:** `Cannot find module '@bytelyst/errors' or its corresponding type declarations`
+**Fix:** Build the package first: `cd learning_ai_common_plat && pnpm build`
+
+### Fastify request types
+**Symptom:** `Property 'user' does not exist on type 'FastifyRequest'`
+**Fix:** Use `getUserId(req)` from `src/lib/request-context.ts` instead of `req.user`
+
+### Cosmos document types
+**Symptom:** `Type '{ name: string }' is missing ... 'productId'`
+**Fix:** Always include `productId` when creating documents
+
+## Report Format
+
+```markdown
+## Type Safety Sweep: <Repo>
+
+| Category | Count | Fixed | Remaining |
+|----------|-------|-------|-----------|
+| Import extensions | N | N | 0 |
+| Implicit any | N | N | 0 |
+| Type mismatches | N | N | M |
+| Package conflicts | N | 0 | N |
+| **Total** | **X** | **Y** | **Z** |
+
+### Deferred Issues
+- <issue>: <why deferred> (needs <decision/approval>)
+```