# ByteLyst Ecosystem Consistency Audit

> **Date:** 2026-03-21
> **Scope:** All 13 repos in the ByteLyst workspace
> **Auditor:** Cascade AI

---

## 1. Product Identity (`shared/product.json`)

### Port Allocation (no collisions ✅)

| Product            | Port | Repo                                |
| ------------------ | ---- | ----------------------------------- |
| PeakPulse          | 4010 | `learning_ai_peakpulse`             |
| ChronoMind         | 4011 | `learning_ai_clock`                 |
| JarvisJr           | 4012 | `learning_ai_jarvis_jr`             |
| NomGap             | 4013 | `learning_ai_fastgap`               |
| MindLyst           | 4014 | `learning_multimodal_memory_agents` |
| LysnrAI            | 4015 | `learning_voice_ai_agent`           |
| NoteLett           | 4016 | `learning_ai_notes`                 |
| FlowMonk           | 4017 | `learning_ai_flowmonk`              |
| ActionTrail        | 4018 | `learning_ai_trails`                |
| LocalMemGPT        | 4019 | `learning_ai_local_memory_gpt`      |
| Platform-service   | 4003 | `learning_ai_common_plat`           |
| Extraction-service | 4005 | `learning_ai_common_plat`           |
| MCP-server         | 4007 | `learning_ai_common_plat`           |

### Schema Consistency

**Full schema (16 fields):** MindLyst, ChronoMind, JarvisJr, PeakPulse — ✅ consistent

**Newer schema (10 fields, uses `bundleIds` + `tagline` + `appStore`):** FlowMonk, ActionTrail, LocalMemGPT, SmartAuth — ✅ consistent among themselves

| Finding                                                                                                                                                                                                   | Severity  | Repos                     |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------------------------- |
| **F1: NomGap product.json minimal** — only 4 fields (`productId`, `displayName`, `bundleId`, `domain`), missing `backendPort`, `version`, `licensePrefix`, `configDirName`, `envVarPrefix`, `packageName` | 🟡 Medium | `learning_ai_fastgap`     |
| **F2: LysnrAI product.json missing domain/backendPort** — only 7 fields, no `domain`, `backendPort`, `description`, `cosmos`, `platforms`, `primarySurface`                                               | 🟡 Medium | `learning_voice_ai_agent` |
| **F3: NoteLett hybrid schema** — mixes old (`bundleIdSuffix`, `packageName`) and new (`backendPort`, `domain`) but missing `version`, `cosmos`, `platforms`                                               | 🟡 Medium | `learning_ai_notes`       |
| **F4: ByteLyst Auth uses `productName` instead of `displayName`**                                                                                                                                         | 🟠 Low    | `learning_ai_auth_app`    |
| **F5: Two schema patterns** — older repos use `bundleId` (object), newer use `bundleIds` (object). Not a bug but inconsistent.                                                                            | 🟢 Info   | —                         |

---

## 2. Backend Patterns (Fastify 5 + TypeScript ESM)

### Shared Package Adoption

All 10 product backends have:

- ✅ `@bytelyst/auth` — JWT utilities
- ✅ `@bytelyst/config` — env loader + product identity
- ✅ `@bytelyst/datastore` — Cosmos/memory abstraction
- ✅ `@bytelyst/errors` — typed HTTP errors
- ✅ `@bytelyst/fastify-core` — createServiceApp() factory
- ✅ `@bytelyst/fastify-auth` — auth middleware
- ✅ `@bytelyst/backend-config` — backend config helpers
- ✅ `@bytelyst/backend-flags` — feature flag server-side
- ✅ `@bytelyst/backend-telemetry` — telemetry buffer
- ✅ `product-config.ts` in `src/lib/` — all 10 backends

### Fastify Version

| Version  | Repos                                                      |
| -------- | ---------------------------------------------------------- |
| `^5.2.1` | LysnrAI, MindLyst, ChronoMind, JarvisJr, NomGap, PeakPulse |
| `5.7.4`  | FlowMonk, ActionTrail, LocalMemGPT                         |
| `^5.2.1` | NoteLett                                                   |

| Finding                                                                                    | Severity  |
| ------------------------------------------------------------------------------------------ | --------- |
| **F6: Fastify version split** — 6 repos on `^5.2.1`, 3 on `5.7.4`. Should align to latest. | 🟡 Medium |

### Field Encryption

| Finding                                                                                                                                                            | Severity |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- |
| **F7: LocalMemGPT missing @bytelyst/field-encrypt** — uses local AES-256-GCM instead of shared package. Intentional (SQLite-based, local-first app) but divergent. | 🟢 Info  |

All other 9 Cosmos-based backends have `@bytelyst/field-encrypt` ✅

### Advanced Packages (SSE, Events, Webhooks)

Only FlowMonk and ActionTrail have:

- `@bytelyst/fastify-sse` — SSE streaming
- `@bytelyst/event-store` — domain event persistence
- `@bytelyst/webhook-dispatch` — outbound webhook delivery

LocalMemGPT has `@bytelyst/fastify-sse` and `@bytelyst/llm-router` (unique).

Other backends may need these as they mature — not a gap yet.

---

## 3. Web Frontend Patterns

### Next.js + React Versions

| Version                             | Repos                                                |
| ----------------------------------- | ---------------------------------------------------- |
| Next.js 16.1.6 + React 19.2.3       | LysnrAI, ChronoMind, JarvisJr, FlowMonk, ActionTrail |
| Next.js 16.1.6 + React 19.2.0       | NomGap, NoteLett                                     |
| Next.js ^16.0.0 + React ^19.0.0     | MindLyst                                             |
| **Next.js ^15.3.2 + React ^19.1.0** | **LocalMemGPT**                                      |

| Finding                                                                            | Severity |
| ---------------------------------------------------------------------------------- | -------- |
| **F8: LocalMemGPT on Next.js 15** — all other repos on Next.js 16. Should upgrade. | 🟠 High  |

### TailwindCSS

| Status                      | Repos                                              |
| --------------------------- | -------------------------------------------------- |
| TailwindCSS v4 ✅           | LysnrAI, ChronoMind, NomGap, NoteLett, LocalMemGPT |
| **Missing TailwindCSS**     | **MindLyst, FlowMonk, ActionTrail**                |
| TailwindCSS v4 via JarvisJr | JarvisJr ✅                                        |

| Finding                                                                                                                      | Severity  |
| ---------------------------------------------------------------------------------------------------------------------------- | --------- |
| **F9: MindLyst uses vanilla CSS** — `--ml-*` props in `globals.css`, no Tailwind. Intentional per AGENTS.md ("NO Tailwind"). | 🟢 Info   |
| **F10: FlowMonk + ActionTrail missing TailwindCSS** — use inline styles or basic CSS. Should add for consistency.            | 🟡 Medium |

### CSS Custom Property Namespaces

| Namespace            | Product      | Status |
| -------------------- | ------------ | ------ |
| `--cm-*`             | ChronoMind   | ✅     |
| `--jj-*`             | JarvisJr     | ✅     |
| `--ng-*`             | NomGap       | ✅     |
| `--ml-*`             | MindLyst     | ✅     |
| `--fm-*`             | FlowMonk     | ✅     |
| `--at-*`             | ActionTrail  | ✅     |
| `--lmg-*`            | LocalMemGPT  | ✅     |
| **`--nl-*` MISSING** | **NoteLett** | ❌     |

| Finding                                                                                                                                               | Severity |
| ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| **F11: NoteLett globals.css has no `--nl-*` custom properties** — contrary to AGENTS.md which says "Theme tokens use `--nl-*` CSS custom properties". | 🟠 High  |

### Web Auth Pattern (`@bytelyst/react-auth`)

| Has `react-auth` in web deps | Has `auth.ts` using it                              |
| ---------------------------- | --------------------------------------------------- |
| LysnrAI ✅                   | LysnrAI uses custom auth-server pattern (dashboard) |
| ChronoMind ✅                | ChronoMind uses auth-client directly                |
| NomGap ✅                    | NomGap ✅ `auth.ts` uses `react-auth`               |
| NoteLett ✅                  | NoteLett ✅ `auth.ts` uses `react-auth`             |
| ActionTrail ✅               | ActionTrail ✅ `auth.ts` uses `react-auth`          |
| JarvisJr ❌                  | JarvisJr — no `react-auth` dep                      |
| FlowMonk ❌                  | FlowMonk — no `react-auth` dep                      |
| LocalMemGPT ❌               | LocalMemGPT — auth is optional (local-first)        |

| Finding                                                                                                  | Severity  |
| -------------------------------------------------------------------------------------------------------- | --------- |
| **F12: JarvisJr web missing `@bytelyst/react-auth`** — has kill-switch + telemetry but no auth provider. | 🟡 Medium |
| **F13: FlowMonk web missing `@bytelyst/react-auth`** — no auth provider in web.                          | 🟡 Medium |

### Web `product-config.ts`

| Finding                                                                       | Severity  |
| ----------------------------------------------------------------------------- | --------- |
| **F14: ChronoMind web missing `product-config.ts`** — all other webs have it. | 🟡 Medium |

---

## 4. Mobile / Native Patterns

### iOS Platform SDK (`Platform/` directory)

| App        | Platform/ dir                                          | Status                                |
| ---------- | ------------------------------------------------------ | ------------------------------------- |
| LysnrAI    | `mobile_app/ios/LysnrAI/Platform/`                     | ✅                                    |
| MindLyst   | `mindlyst-native/iosApp/Platform/`                     | ✅                                    |
| ChronoMind | `ios/ChronoMind/Shared/Cloud/` + `Shared/Diagnostics/` | ⚠️ Different (valid for multi-target) |
| JarvisJr   | `ios/JarvisJr/Platform/`                               | ✅                                    |
| PeakPulse  | `ios/PeakPulse/Platform/`                              | ✅                                    |

### Android Kotlin Platform SDK

All 3 Android apps (ChronoMind, MindLyst, LysnrAI) have `includeBuild` for `kotlin-platform-sdk` ✅

JarvisJr Android exists but is Phase 4 (minimal). NomGap uses Expo (no native SDK needed).

---

## 5. Design Tokens

`@bytelyst/design-tokens` generates:

- `tokens.css` — web CSS vars
- `tokens.ts` — TypeScript constants
- `MindLystTokens.kt` — Android tokens
- `MindLystTheme.swift` — iOS tokens

| Finding                                                                                                                         | Severity  |
| ------------------------------------------------------------------------------------------------------------------------------- | --------- |
| **F15: Only 3 webs import `@bytelyst/design-tokens`** — LysnrAI, NomGap, NoteLett. Other webs define CSS custom props manually. | 🟡 Medium |

---

## 6. CI/CD & Docker

### GitHub Actions

| Status          | Repos                                                                                 |
| --------------- | ------------------------------------------------------------------------------------- |
| Active `ci.yml` | ChronoMind, JarvisJr, NomGap, PeakPulse, FlowMonk, NoteLett, ActionTrail, LocalMemGPT |
| Disabled        | LysnrAI (`disabled.yml`), MindLyst (`disabled.yml`)                                   |
| No CI           | ByteLyst Auth App                                                                     |

| Finding                                                                                                   | Severity  |
| --------------------------------------------------------------------------------------------------------- | --------- |
| **F16: LysnrAI + MindLyst CI disabled** — mature repos with extensive test suites should have CI enabled. | 🟡 Medium |
| **F17: ByteLyst Auth App has no CI** — no `.github/workflows/` at all.                                    | 🟡 Medium |

### Docker

| Has docker-compose + Dockerfiles         | Repos                                                   |
| ---------------------------------------- | ------------------------------------------------------- |
| ✅ Full stack                            | NomGap, NoteLett, ActionTrail, LocalMemGPT              |
| docker-compose only (references sibling) | LysnrAI                                                 |
| **No Docker**                            | **MindLyst, ChronoMind, JarvisJr, PeakPulse, FlowMonk** |

| Finding                                                                     | Severity |
| --------------------------------------------------------------------------- | -------- |
| **F18: 5 repos have no Docker configs** — makes local/CI deployment harder. | 🟢 Info  |

---

## 7. Agent Documentation

> **Migrated (May 2026) to single-source-of-truth pattern.** Behavior rules
> live in one canonical file:
> `learning_ai_common_plat/AI.dev/SKILLS/agent-behavior-guidelines.md`.
> Per-repo `AGENTS.md` references it via an auto-managed pointer block.
> Legacy files (`CLAUDE.md`, `.cursorrules`, `.windsurfrules`, `.clinerules`)
> have been deleted across all repos — they duplicated AGENTS.md content and
> drifted.

### File Presence Matrix (post-migration)

| File                              | Present (of 17 active) | Notes                                       |
| --------------------------------- | ---------------------- | ------------------------------------------- |
| `AGENTS.md`                       | 17/17 ✅                | Hand-maintained; canonical pointer prepended |
| `.github/copilot-instructions.md` | 17/17 ✅                | Thin pointer, auto-generated                |
| `.aider.conf.yml`                 | 17/17 ✅                | Aider config, auto-generated                |
| `.editorconfig`                   | 17/17 ✅                | Auto-generated                              |
| `CLAUDE.md`                       | 0/17 ✅                 | **Deprecated** (deleted)                    |
| `.cursorrules`                    | 0/17 ✅                 | **Deprecated** (deleted)                    |
| `.windsurfrules`                  | 0/17 ✅                 | **Deprecated** (deleted)                    |
| `.clinerules`                     | 0/17 ✅                 | **Deprecated** (deleted)                    |

F19 and F20 are now **resolved** by the migration — ActionTrail and ByteLyst
Auth App no longer need the legacy files. Drift is enforced via
`scripts/check-agent-docs-drift.sh`.

| Finding                                                                    | Status                |
| -------------------------------------------------------------------------- | --------------------- |
| ~~F19: ActionTrail missing CLAUDE.md~~                                     | ✅ Resolved (deleted) |
| ~~F20: ByteLyst Auth App missing CLAUDE.md, .windsurfrules, .cursorrules~~ | ✅ Resolved (deleted) |

---

## 8. Summary Scorecard

### Critical (should fix now)

| #   | Finding                                         | Fix                                      |
| --- | ----------------------------------------------- | ---------------------------------------- |
| F8  | LocalMemGPT on Next.js 15                       | Upgrade to Next.js 16                    |
| F11 | NoteLett missing `--nl-*` CSS custom properties | Add design token CSS vars to globals.css |

### Medium (should fix soon)

| #   | Finding                                         | Fix                                            |
| --- | ----------------------------------------------- | ---------------------------------------------- |
| F1  | NomGap product.json minimal (4 fields)          | Add missing fields to match ecosystem standard |
| F2  | LysnrAI product.json missing domain/backendPort | Add missing fields                             |
| F3  | NoteLett product.json hybrid schema             | Normalize to ecosystem standard                |
| F6  | Fastify version split (^5.2.1 vs 5.7.4)         | Align all to latest 5.7.x                      |
| F10 | FlowMonk + ActionTrail missing TailwindCSS      | Add TailwindCSS v4                             |
| F12 | JarvisJr web missing @bytelyst/react-auth       | Add auth provider                              |
| F13 | FlowMonk web missing @bytelyst/react-auth       | Add auth provider                              |
| F14 | ChronoMind web missing product-config.ts        | Create product-config.ts                       |
| F15 | Only 3 webs import @bytelyst/design-tokens      | Add to remaining webs                          |
| F16 | LysnrAI + MindLyst CI disabled                  | Re-enable ci.yml                               |
| ~~F20~~ | ByteLyst Auth App missing agent docs        | ✅ Resolved by single-source migration         |

### Low / Informational

| #   | Finding                                              | Notes                                       |
| --- | ---------------------------------------------------- | ------------------------------------------- |
| F4  | Auth App uses `productName` instead of `displayName` | Minor schema inconsistency                  |
| F5  | Two bundleId schema patterns                         | `bundleId` (object) vs `bundleIds` (object) |
| F7  | LocalMemGPT uses local encryption                    | Intentional — SQLite-based local-first app  |
| F9  | MindLyst no Tailwind                                 | Intentional per AGENTS.md                   |
| F17 | Auth App no CI                                       | Minimal repo, mostly native                 |
| F18 | 5 repos no Docker                                    | Not all repos need containerization yet     |
| ~~F19~~ | ActionTrail missing CLAUDE.md                    | ✅ Resolved by single-source migration       |

---

## 9. Ecosystem-Wide Consistency Checklist

| Dimension                         | Status                                           |
| --------------------------------- | ------------------------------------------------ |
| Product ID in Cosmos docs         | ✅ All backends enforce `productId`              |
| Port allocation (no collisions)   | ✅ 4010–4019 + 4003/4005/4007                    |
| Backend Fastify 5                 | ✅ All 10 backends                               |
| Backend `@bytelyst/fastify-core`  | ✅ All 10 backends                               |
| Backend `@bytelyst/field-encrypt` | ✅ 9/10 (LocalMemGPT intentionally different)    |
| Backend `product-config.ts`       | ✅ All 10 backends                               |
| Web Next.js 16                    | ⚠️ 8/9 (LocalMemGPT on 15)                       |
| Web CSS namespace `--XX-*`        | ⚠️ 7/8 (NoteLett missing)                        |
| Web `@bytelyst/react-auth`        | ⚠️ 5/8 applicable webs                           |
| Web `product-config.ts`           | ⚠️ 7/8 (ChronoMind missing)                      |
| iOS `Platform/` directory         | ✅ 4/5 (ChronoMind valid alternative)            |
| Android kotlin-platform-sdk       | ✅ All 3 Android apps                            |
| `AGENTS.md` + canonical pointer   | ✅ 17/17                                         |
| `.github/copilot-instructions.md` | ✅ 17/17 (thin pointer, auto-generated)          |
| Legacy agent files removed        | ✅ 17/17 (CLAUDE.md, .cursorrules, .windsurfrules, .clinerules) |
| GitHub Actions CI                 | ⚠️ 8/12 active                                   |
| `shared/product.json`             | ⚠️ Inconsistent schemas across older/newer repos |
