# Agent Task: Fix --ml-\* Prefix Leaks in NomGap and NoteLett (Task 1.4 + 1.3 for these 2 repos)

> **Parallel execution:** SAFE to run alongside Agents 3 and 4.
> **Conflict with Agent 1:** Agent 1 wires generated tokens into `globals.css` for OTHER repos but **SKIPS NomGap and NoteLett**.
> **This agent OWNS:** `learning_ai_fastgap` (NomGap) and `learning_ai_notes` (NoteLett) — both `globals.css` AND component files.
> **No other agent touches these two repos' CSS.**

---

## Pre-Flight Checklist

```bash
# 1. Ensure git is clean
for repo in learning_ai_fastgap learning_ai_notes; do
  echo "=== $repo ===" && cd /Users/sd9235/code/mygh/$repo && git status --short
done

# 2. Pull latest
for repo in learning_ai_fastgap learning_ai_notes; do
  cd /Users/sd9235/code/mygh/$repo && git pull --ff-only origin main 2>&1 | tail -1
done

# 3. Verify generated token files exist for both products
cat /Users/sd9235/code/mygh/learning_ai_common_plat/packages/design-tokens/generated/nomgap.css | head -5
cat /Users/sd9235/code/mygh/learning_ai_common_plat/packages/design-tokens/generated/notelett.css | head -5
```

**STOP condition:** If either repo has uncommitted changes, stash or commit them first.

---

## Context

Two apps historically inherited `--ml-*` (MindLyst) prefixed CSS vars from a shared tokens file. They should use their own product prefixes. This agent does TWO things per repo:

1. **Fix prefix leaks:** Replace all `--ml-*` references with the correct prefix
2. **Wire generated tokens:** Insert canonical generated CSS (same as Agent 1 does for other repos)

## Prefix Mapping

| App      | Repo                  | Correct Prefix | Wrong Prefix |
| -------- | --------------------- | -------------- | ------------ |
| NomGap   | `learning_ai_fastgap` | `--ng-*`       | `--ml-*`     |
| NoteLett | `learning_ai_notes`   | `--nl-*`       | `--ml-*`     |

---

## Per-Repo Procedure (do NomGap first, then NoteLett)

### Step 0: Backup

```bash
cd /Users/sd9235/code/mygh/<repo>
cp web/src/app/globals.css web/src/app/globals.css.backup
```

### Step 1: Audit — count all --ml- references (DRY RUN)

```bash
echo "=== globals.css definitions ==="
grep -c '\-\-ml-' web/src/app/globals.css

echo "=== Component/lib usages ==="
grep -rn '\-\-ml-' web/src/ --include='*.tsx' --include='*.ts' --include='*.css' | wc -l

echo "=== Full list ==="
grep -rn '\-\-ml-' web/src/ --include='*.tsx' --include='*.ts' --include='*.css'
```

Record the total count. After fixing, this count must be exactly **0**.

**STOP condition:** If the count is already 0, there are no prefix leaks. Skip to the "Wire Generated Tokens" section below.

### Step 2: Audit — check for `--ml-` in config files too

```bash
grep -rn '\-\-ml-' web/ --include='*.ts' --include='*.js' --include='*.mjs' --include='*.json' --exclude-dir=node_modules --exclude-dir=.next | grep -v 'src/'
```

This catches Tailwind config, Next.js config, or other build configs.

### Step 3: Replace prefix in globals.css DEFINITIONS

For **NomGap**: replace `--ml-` → `--ng-` in var definitions
For **NoteLett**: replace `--ml-` → `--nl-` in var definitions

Use the edit tool to make these replacements in `web/src/app/globals.css`. Only replace within `:root` and `[data-theme]` blocks.

**Critical rule:** Only replace the PREFIX, never the var name. `--ml-accent-primary` → `--ng-accent-primary` (not `--ng-primary`).

### Step 4: Replace prefix in all USAGES across component/lib files

For each `.tsx`, `.ts`, `.css` file in `web/src/` that uses `var(--ml-`:

**NomGap:** `var(--ml-` → `var(--ng-`
**NoteLett:** `var(--ml-` → `var(--nl-`

Also fix bare references (without `var()`):

- `'--ml-accent-primary'` → `'--ng-accent-primary'` (in JS string contexts)

### Step 5: Verify zero --ml- references remain

```bash
count=$(grep -rn '\-\-ml-' web/src/ --include='*.tsx' --include='*.ts' --include='*.css' | wc -l | tr -d ' ')
echo "Remaining --ml- references: $count"
if [ "$count" -ne "0" ]; then echo "❌ STILL HAS LEAKS — fix them"; else echo "✅ Clean"; fi
```

**STOP condition:** If count > 0, find and fix the remaining references before proceeding.

### Step 6: Verify definitions match usages

```bash
# All vars USED in components
grep -rhoP 'var\(--[a-z][-a-z0-9]*' web/src/ --include='*.tsx' --include='*.ts' --include='*.css' | sort -u | sed 's/var(//' > /tmp/used-vars.txt

# All vars DEFINED in globals.css
grep -oP '--[a-z][-a-z0-9]*(?=\s*:)' web/src/app/globals.css | sort -u > /tmp/defined-vars.txt

# Vars used but not defined (DANGER)
echo "=== Used but not defined ==="
comm -23 /tmp/used-vars.txt /tmp/defined-vars.txt
```

**STOP condition:** If any product-prefixed vars are used but not defined, a definition was missed. Fix it before proceeding.

---

## Wire Generated Tokens (same as Agent 1 does for other repos)

After prefix leaks are fixed, also wire the canonical generated tokens:

### Step 7: Read the generated product CSS

```bash
cat /Users/sd9235/code/mygh/learning_ai_common_plat/packages/design-tokens/generated/<product>.css
```

### Step 8: Insert generated tokens at TOP of globals.css

Add the generated CSS content at the very top, in a marked block:

```css
/* ============================================================
   Design tokens — auto-generated from @bytelyst/design-tokens
   Source: packages/design-tokens/generated/<product>.css
   DO NOT EDIT — regenerate with: npx tsx packages/design-tokens/scripts/generate.ts
   ============================================================ */

/* paste generated content here */

/* === END design tokens === */
```

### Step 9: Remove duplicate definitions

Any `:root` var that now exists in BOTH the generated block AND the app's own block → remove from the app's own block. Keep app-specific vars, focus-visible CSS, animations, component styles.

---

## Build Gate (MANDATORY)

```bash
cd web && pnpm run build 2>&1 | tail -20
```

**If build fails:**

1. Check error — usually a missing var
2. Restore backup: `cp web/src/app/globals.css.backup web/src/app/globals.css`
3. Identify the specific issue, fix it, retry

**STOP condition:** If build fails 3 times, restore backup, commit nothing, leave this TODO at the top of globals.css:

```css
/* TODO: --ml-* prefix fix failed build — needs manual review */
```

## Final Verification

```bash
# Zero --ml- leaks
grep -c '\-\-ml-' web/src/app/globals.css  # Must be 0

# Has correct prefix
grep -c '\-\-ng-' web/src/app/globals.css  # NomGap: must be > 0
# or
grep -c '\-\-nl-' web/src/app/globals.css  # NoteLett: must be > 0

# Build passes
cd web && pnpm run build
```

## Commit and Push

```bash
git add -A
git commit -m "fix(design-system): replace --ml-* prefix leaks with correct product prefix and wire generated tokens"
git push origin main
```

## Cleanup

```bash
rm web/src/app/globals.css.backup
rm -f /tmp/used-vars.txt /tmp/defined-vars.txt
```

## Rollback Recipe

```bash
git revert HEAD --no-edit && git push origin main
```

---

## Order

1. **NomGap** (`learning_ai_fastgap`) first — older app, likely more leaks
2. **NoteLett** (`learning_ai_notes`) second

Complete NomGap fully (fix + wire + build + commit + push) before starting NoteLett.

---

## Rules

- **ONLY touch files in `web/src/`** — no backend, no mobile, no shared/
- **Only replace the prefix** — never rename the var stem (`accent-primary` stays `accent-primary`)
- **Both definitions AND usages must be fixed** — if you fix one side, the other breaks
- **Keep ALL non-token CSS** — animations, keyframes, focus-visible, Tailwind directives, component styles
- **Backup before every edit** — restore if build fails
- Commit message: `fix(design-system): replace --ml-* prefix leaks with correct product prefix and wire generated tokens`
