---
description: Onboard ByteLyst Trading into the common platform product registry and generate missing ecosystem artifacts
---

# Onboard ByteLyst Trading Product

Fully registers the `invttrdg` product in the ByteLyst ecosystem. Run this once to close the onboarding gap.

**Idempotency:** Safe to re-run — file creates are upserts, commits skip if tree is clean, push is a no-op if already up-to-date.

**Pre-requisites:**
- Both repos checked out as siblings under the same parent directory
- `learning_ai_invt_trdg` (this repo)
- `learning_ai_common_plat` (common platform)
- pnpm installed (`pnpm -v` works)

**Path variables used below:**
```
TRADING_ROOT = (this repo root — cwd for all relative commands)
COMMON_ROOT  = ../learning_ai_common_plat
```

---

## Phase 1 — Create the canonical product manifest in common platform

### 1. Confirm common-plat repo is accessible

// turbo

```bash
ls ../learning_ai_common_plat/products/ | head -5
```

Expect: Existing product directories listed (chronomind, efforise, etc.). If this fails, the sibling repo is not checked out.

### 2. Create `products/invttrdg/product.json` in the common platform

Create the file `../learning_ai_common_plat/products/invttrdg/product.json` with the full product manifest below. If the file already exists, verify it matches and update any missing fields.

The manifest MUST include ALL of the following sections (derived from the trading repo's actual codebase):

**Identity:**
- `productId`: `"invttrdg"`
- `displayName`: `"ByteLyst Trading"`
- `name`: `"ByteLyst Trading"`
- `bundleId`: `{ "ios": "com.bytelyst.trading", "android": "com.bytelyst.trading" }`
- `domain`: `"trading.bytelyst.ai"`
- `description`: `"AI-assisted trading operations with automated strategies, backtesting, and portfolio management"`
- `version`: `"0.1.0"`

**Platforms:** `["web", "ios", "android"]`
- `primarySurface`: `"web"`
- `mobileCompanion`: `true`

**Theme** (ByteLyst default brand palette):
```json
{
  "primary": "#5AE68C",
  "secondary": "#5A8CFF",
  "accent": "#2EE6D6",
  "background": "#06070A",
  "surface": "#121725",
  "text": "#EFF4FF",
  "error": "#FF6E6E",
  "warning": "#F59E0B",
  "success": "#34D399"
}
```

**Features:**
```json
{
  "automatedTrading": true,
  "backtesting": true,
  "manualEntries": true,
  "capitalLedger": true,
  "strategyPresets": true,
  "tradingControls": true,
  "portfolioSnapshots": true,
  "auditTrail": true,
  "dynamicConfig": true,
  "alertFeed": true
}
```

**Cosmos containers** (13 containers from backend repository constants):
```json
{
  "containers": [
    { "name": "trade_orders", "partitionKey": "/productId" },
    { "name": "trade_history", "partitionKey": "/productId" },
    { "name": "manual_entries", "partitionKey": "/productId" },
    { "name": "reconciliation_backfill_audit", "partitionKey": "/productId" },
    { "name": "trade_profiles", "partitionKey": "/productId" },
    { "name": "trading_users", "partitionKey": "/productId" },
    { "name": "strategy_presets", "partitionKey": "/productId" },
    { "name": "capital_ledgers", "partitionKey": "/productId" },
    { "name": "bot_state_snapshots", "partitionKey": "/productId" },
    { "name": "trading_controls", "partitionKey": "/productId" },
    { "name": "audit-events", "partitionKey": "/productId" },
    { "name": "dynamic_config", "partitionKey": "/productId" },
    { "name": "runtime_locks", "partitionKey": "/productId" }
  ]
}
```

**Flags:**
```json
[
  { "key": "backtest-enabled", "defaultValue": false, "description": "Enable backtesting engine" },
  { "key": "tab-marketplace", "defaultValue": true, "description": "Show marketplace tab" },
  { "key": "tab-membership", "defaultValue": true, "description": "Show membership tab" },
  { "key": "automated-trading", "defaultValue": false, "description": "Enable automated trading strategies" }
]
```

**Ports:**
```json
{
  "service": 4018,
  "dashboard": 5173
}
```

**Legacy identity fields** (for `@bytelyst/config` `loadProductIdentity()` compatibility):
- `licensePrefix`: `"TRADING"`
- `configDirName`: `".ByteLystTrading"`
- `envVarPrefix`: `"TRADING"`
- `packageName`: `"bytelyst-trading"`

### 3. Spot-check the manifest completeness

// turbo

```bash
node -e "
  const fs = require('fs');
  const raw = fs.readFileSync('../learning_ai_common_plat/products/invttrdg/product.json', 'utf-8');
  const json = JSON.parse(raw);
  const checks = [
    ['productId=invttrdg', json.productId === 'invttrdg'],
    ['displayName', json.displayName === 'ByteLyst Trading'],
    ['containers>=13', (json.cosmos?.containers?.length || 0) >= 13],
    ['flags>=4', (json.flags?.length || 0) >= 4],
    ['features>=10', Object.keys(json.features || {}).length >= 10],
    ['theme=9keys', Object.keys(json.theme || {}).length === 9],
    ['ports.service=4018', json.ports?.service === 4018],
  ];
  checks.forEach(([k, ok]) => console.log(ok ? '✅' : '❌', k));
  if (!checks.every(([, ok]) => ok)) process.exit(1);
  console.log('All manifest checks passed');
"
```

Expect: All ✅. If any ❌, go back to Step 2 and fix the missing field.

---

## Phase 2 — Enrich the trading repo's local product.json

### 4. Update `shared/product.json` in the trading repo

Sync `shared/product.json` to match the canonical manifest from Step 2. Add the missing `theme`, `cosmos`, `flags`, `features`, and `ports` sections. Preserve the existing `productId`, `displayName`, `bundleId`, `platforms`, `licensePrefix`, `configDirName`, `envVarPrefix`, `packageName` fields.

### 5. Verify the updated local manifest

// turbo

```bash
node -e "
  const fs = require('fs');
  const raw = fs.readFileSync('shared/product.json', 'utf-8');
  const json = JSON.parse(raw);
  const checks = [
    ['productId', json.productId === 'invttrdg'],
    ['theme', Object.keys(json.theme || {}).length === 9],
    ['cosmos', (json.cosmos?.containers?.length || 0) >= 13],
    ['flags', (json.flags?.length || 0) >= 4],
    ['features', Object.keys(json.features || {}).length >= 10],
    ['ports', json.ports?.service === 4018],
  ];
  checks.forEach(([k, ok]) => console.log(ok ? '✅' : '❌', k));
  if (!checks.every(([, ok]) => ok)) { console.error('FAILED'); process.exit(1); }
  console.log('Local manifest complete');
"
```

---

## Phase 3 — Generate AGENTS.md for the trading repo

### 6. Generate AGENTS.md

Create `AGENTS.md` in the trading repo root. Use the same structure as other ByteLyst product repos (`../learning_ai_common_plat/products/` siblings like ChronoMind, NoteLett). The file MUST include these sections:

1. **Project Identity table** — productId, displayName, bundleIds, domain, ecosystem, runtime, package manager, test runner
2. **Repo Layout** — accurate tree of `backend/`, `web/`, `mobile/`, `shared/`, `scripts/`, `docs/`, `vendor/`
3. **Tech Stack table** — Fastify 5 + TypeScript ESM backend (port 4018), Vite + React 19 + TailwindCSS web, React Native + Expo mobile
4. **Coding Conventions** — MUST follow: productId in every Cosmos doc, commit format `type(scope): description`, `req.log`/`app.log` never `console.log`, ESM everywhere
5. **Build & Run Commands** — `pnpm build`, `pnpm test`, `pnpm typecheck`, `pnpm verify`, `pnpm dev`, `docker compose up`
6. **Critical Rules** — MUST NOT: hardcode colors, use npm, modify tests to make them pass, delete comments

Scan the actual repo with `find` and `ls` to populate the layout tree accurately rather than guessing. Key directories to document:
- `backend/src/config/`, `backend/src/connectors/`, `backend/src/domain/`, `backend/src/services/`, `backend/src/strategies/`, `backend/src/backtest/`
- `web/src/components/`, `web/src/views/`, `web/src/backtest/`, `web/src/assets/`
- `mobile/app/`, `mobile/components/`, `mobile/services/`
- `shared/` — product.json, feature-flags.ts, control-plane.ts, platform-clients.ts, backend-control-config.ts

### 7. Verify AGENTS.md exists and has minimum content

// turbo

```bash
test -f AGENTS.md && echo "✅ AGENTS.md exists ($(wc -l < AGENTS.md) lines)" || echo "❌ AGENTS.md missing"
head -3 AGENTS.md
```

Expect: File exists with 100+ lines. First line contains `# AGENTS.md`.

---

## Phase 4 — Update common platform ecosystem references

### 8. Add trading to the common platform AGENTS.md product consumer list

In `../learning_ai_common_plat/AGENTS.md`, locate the `Product consumers` row in the Project Identity table and append `[ByteLyst Trading](../learning_ai_invt_trdg)` to the comma-separated list.

### 9. Verify the common platform AGENTS.md update

// turbo

```bash
grep -c 'learning_ai_invt_trdg\|ByteLyst Trading' ../learning_ai_common_plat/AGENTS.md
```

Expect: At least 1 match. If 0, Step 8 was not applied correctly.

---

## Phase 5 — Commit, verify, and push

### 10. Check for unrelated uncommitted changes in both repos

// turbo

```bash
echo "=== Trading repo ===" && git status --short
echo "=== Common platform ===" && git -C ../learning_ai_common_plat status --short
```

Review output. If there are unrelated changes, stash or commit them separately before proceeding.

### 11. Commit the common platform changes

```bash
cd ../learning_ai_common_plat && git add products/invttrdg/product.json AGENTS.md && git commit -m "feat(products): onboard ByteLyst Trading (invttrdg) into product registry"
```

### 12. Commit the trading repo changes

```bash
git add shared/product.json AGENTS.md && git commit -m "feat(onboard): add full product manifest and AGENTS.md"
```

### 13. Run trading repo typecheck

// turbo

```bash
pnpm typecheck
```

Expect: Exit 0. If it fails, fix the issue before pushing.

### 14. Push both repos

```bash
git push origin main
```

```bash
cd ../learning_ai_common_plat && git push origin main
```

### 15. Final ecosystem check — verify all 9 products exist

// turbo

```bash
echo "Products in registry:" && ls -1 ../learning_ai_common_plat/products/ | sort
```

Expect: 9 directories — chronomind, efforise, invttrdg, jarvisjr, lysnrai, mindlyst, nomgap, notelett, peakpulse.

---

## Completion Checklist

After all steps pass:
- [ ] `products/invttrdg/product.json` exists in common platform with full schema (13 containers, 4 flags, 10 features, 9 theme keys, ports)
- [ ] `shared/product.json` in trading repo enriched with theme, cosmos, flags, features, ports
- [ ] `AGENTS.md` exists in trading repo root (100+ lines)
- [ ] Common platform `AGENTS.md` lists ByteLyst Trading as a product consumer
- [ ] Both repos committed and pushed cleanly
- [ ] `pnpm typecheck` passes in trading repo
- [ ] 9 total products visible in `products/` directory