# Agent Task: Wire Web Apps to Import Generated CSS Tokens (Task 1.3)

> **Parallel execution:** SAFE to run alongside Agents 3 and 4.
> **Conflict with Agent 2:** Agent 2 touches NomGap + NoteLett `globals.css` too.
> **Resolution:** This agent **SKIPS** `learning_ai_fastgap` and `learning_ai_notes` — Agent 2 will handle those two after this agent finishes the other 6.

---

## Pre-Flight Checklist (run BEFORE starting any repo)

```bash
# 1. Ensure git is clean in every repo you'll touch
for repo in learning_ai_flowmonk learning_ai_trails learning_ai_jarvis_jr learning_ai_local_memory_gpt learning_ai_clock learning_ai_local_llms; do
  echo "=== $repo ===" && cd /Users/sd9235/code/mygh/$repo && git status --short
done

# 2. Pull latest on all repos (other agents may have pushed)
for repo in learning_ai_flowmonk learning_ai_trails learning_ai_jarvis_jr learning_ai_local_memory_gpt learning_ai_clock learning_ai_local_llms; do
  cd /Users/sd9235/code/mygh/$repo && git pull --ff-only origin main 2>&1 | tail -1
done

# 3. Verify generated token files exist
ls /Users/sd9235/code/mygh/learning_ai_common_plat/packages/design-tokens/generated/*.css
```

**STOP condition:** If any repo has uncommitted changes, stash or commit them first. Do NOT proceed with a dirty working tree.

---

## Context

The `@bytelyst/design-tokens` package generates per-product CSS files in `packages/design-tokens/generated/`. Each file contains product-specific CSS custom properties with the correct prefix. Currently each web app hand-maintains its own vars in `globals.css`. This task replaces handwritten token vars with the canonical generated content.

## Generated Token Files

Location: `learning_ai_common_plat/packages/design-tokens/generated/`

| Product     | File              | Prefix    | Web App Repo                   | CSS Path                        |
| ----------- | ----------------- | --------- | ------------------------------ | ------------------------------- |
| FlowMonk    | `flowmonk.css`    | `--fm-*`  | `learning_ai_flowmonk`         | `web/src/app/globals.css`       |
| ActionTrail | `actiontrail.css` | `--at-*`  | `learning_ai_trails`           | `web/src/app/globals.css`       |
| JarvisJr    | `jarvisjr.css`    | `--jj-*`  | `learning_ai_jarvis_jr`        | `web/src/app/globals.css`       |
| LocalMemGPT | `localmemgpt.css` | `--lmg-*` | `learning_ai_local_memory_gpt` | `web/src/app/globals.css`       |
| ChronoMind  | `chronomind.css`  | `--cm-*`  | `learning_ai_clock`            | `web/src/app/globals.css`       |
| LocalLLMLab | `localllmlab.css` | `--llm-*` | `learning_ai_local_llms`       | `dashboard/src/app/globals.css` |

**NOT in scope:** NomGap and NoteLett — handled by Agent 2.

---

## Per-Repo Procedure (repeat for each repo)

### Step 0: Backup the current globals.css

```bash
cp web/src/app/globals.css web/src/app/globals.css.backup
```

This backup enables instant rollback. Delete it after successful push.

### Step 1: Read both files side-by-side

Read the generated CSS file for this product:

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

Read the app's current globals.css:

```bash
cat web/src/app/globals.css
```

### Step 2: Build a var inventory (DRY RUN — no edits yet)

Create two lists:

1. **OVERLAP** — vars defined in BOTH globals.css AND the generated file (these will be removed from globals.css)
2. **APP-ONLY** — vars defined in globals.css but NOT in the generated file (these MUST be kept)

```bash
# Extract var names from generated file
grep -oP '--[a-z][-a-z0-9]*' /Users/sd9235/code/mygh/learning_ai_common_plat/packages/design-tokens/generated/<product>.css | sort -u > /tmp/generated-vars.txt

# Extract var names from globals.css :root blocks
grep -oP '--[a-z][-a-z0-9]*(?=\s*:)' web/src/app/globals.css | sort -u > /tmp/app-vars.txt

# Show overlap (safe to remove from globals.css)
comm -12 /tmp/generated-vars.txt /tmp/app-vars.txt

# Show app-only (MUST KEEP)
comm -23 /tmp/app-vars.txt /tmp/generated-vars.txt
```

**STOP condition:** If the overlap list is empty (0 vars match), the generated file may use different naming. Inspect manually before proceeding.

### Step 3: Insert generated token content into globals.css

Since CSS `@import` from a sibling repo may not resolve in Next.js builds, use the **inline copy** approach — paste the generated CSS content at the TOP of globals.css in a clearly 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 CSS content here */

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

### Step 4: Remove overlapping var definitions

For each var in the OVERLAP list from Step 2, remove its definition from the app's own `:root` / `[data-theme]` blocks. **Do NOT remove:**

- Any var in the APP-ONLY list
- The `/* Focus-visible */` block
- Any `@tailwind` directives
- Any `@layer` blocks
- Any `@keyframes` or animation definitions
- Any component-specific or layout-specific CSS rules

### Step 5: Verify all var usages still resolve

```bash
# Extract all var(--xxx) usages across the web codebase
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

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

# Find vars that are USED but NOT DEFINED (potential breakage!)
comm -23 /tmp/used-vars.txt /tmp/defined-vars.txt
```

**STOP condition:** If any vars appear in usages but not in definitions, you either:

- Removed a var you shouldn't have → restore it from the backup
- The var is defined in a component-level CSS file → safe, proceed

### Step 6: Build gate (MANDATORY)

```bash
cd web && pnpm run build 2>&1 | tail -20
# or for repos using npm:
cd web && npm run build -- --webpack 2>&1 | tail -20
```

**If build fails:**

1. Read the error message
2. Most likely a missing CSS var — check Step 5 output
3. Restore from backup: `cp web/src/app/globals.css.backup web/src/app/globals.css`
4. Fix the specific issue, then retry from Step 4

**STOP condition:** If build fails more than twice, restore backup, commit nothing, and move to the next repo. Leave a TODO comment at the top of globals.css:

```css
/* TODO: Wire generated tokens — build failed, needs manual review */
```

### Step 7: Commit and push

```bash
git add web/src/app/globals.css
git commit -m "feat(design-system): wire generated CSS tokens from @bytelyst/design-tokens"
git push origin main
```

### Step 8: Cleanup

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

---

## Rollback Recipe

If anything goes wrong after commit:

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

---

## Repos to Process (in order, easiest first)

1. `learning_ai_flowmonk` — few custom vars, simple layout
2. `learning_ai_trails` — few custom vars
3. `learning_ai_jarvis_jr` — few custom vars
4. `learning_ai_local_memory_gpt` — few custom vars
5. `learning_ai_clock` — more custom vars (timer-specific)
6. `learning_ai_local_llms` — `dashboard/src/app/globals.css` (different path!)

**SKIP:** `learning_ai_fastgap` (NomGap) and `learning_ai_notes` (NoteLett) — Agent 2 handles these.

---

## Rules

- **ONLY touch `globals.css`** — no component files, no config files
- **Do NOT modify generated CSS files** in the common-plat repo
- **Keep ALL non-token CSS** (animations, keyframes, component styles, focus-visible, Tailwind directives)
- **One repo at a time** — build must pass before moving to next
- **Backup before every edit** — restore if build fails
- Commit message: `feat(design-system): wire generated CSS tokens from @bytelyst/design-tokens`
