learning_ai_invt_trdg/.windsurf/workflows/onboard-trading-product.md

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

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):

{
  "primary": "#5AE68C",
  "secondary": "#5A8CFF",
  "accent": "#2EE6D6",
  "background": "#06070A",
  "surface": "#121725",
  "text": "#EFF4FF",
  "error": "#FF6E6E",
  "warning": "#F59E0B",
  "success": "#34D399"
}

Features:

{
  "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):

{
  "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:

[
  { "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:

{
  "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

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

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

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

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

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

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

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

pnpm typecheck

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

14. Push both repos

git push origin main

cd ../learning_ai_common_plat && git push origin main

15. Final ecosystem check — verify all 9 products exist

// turbo

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