# Agent Task: Wire ToastProvider into App Layouts (Task 3.5)

> **Parallel execution:** SAFE to run alongside ALL other agents.
> **Files touched:** ONLY `providers.tsx` or `layout.tsx` (root layout) + `package.json` for dep.
> **No conflicts:** Agents 1/2 touch `globals.css`, Agent 4 touches component files. This agent only touches layout/provider wiring.

---

## Pre-Flight Checklist

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

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

# 3. Verify @bytelyst/ui package exists and has ToastProvider
grep -l 'ToastProvider' /Users/sd9235/code/mygh/learning_ai_common_plat/packages/ui/src/components/Toast.tsx
```

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

---

## Context

The `@bytelyst/ui` package exports `ToastProvider`, `toast()`, `useToast()`, and `dismissToast()`. This task wires `ToastProvider` into apps that don't have any toast system.

```typescript
// Usage in any component after wiring:
import { toast } from '@bytelyst/ui';
toast({ type: 'success', title: 'Saved!', description: 'Changes saved.' });
```

---

## Step 0: Audit EVERY Repo First (DRY RUN — no edits)

**Before touching ANY file**, audit all repos to confirm which have/lack toast:

```bash
for repo in learning_ai_clock learning_ai_fastgap learning_ai_jarvis_jr learning_ai_trails learning_ai_flowmonk learning_ai_notes learning_ai_local_memory_gpt learning_ai_local_llms; do
  echo "=== $repo ==="
  if [ "$repo" = "learning_ai_local_llms" ]; then dir="dashboard"; else dir="web"; fi
  cd /Users/sd9235/code/mygh/$repo
  count=$(grep -rn 'Toast\|toast(' $dir/src/ --include='*.tsx' --include='*.ts' 2>/dev/null | grep -v node_modules | grep -v '.test.' | wc -l | tr -d ' ')
  echo "  Toast references: $count"
  if [ "$count" -gt "3" ]; then echo "  → SKIP (has custom toast)"; else echo "  → ADD ToastProvider"; fi
done
```

### Expected Results (verify before proceeding!)

| Repo                           | Expected               | Action                   |
| ------------------------------ | ---------------------- | ------------------------ |
| `learning_ai_clock`            | Has custom `Toast.tsx` | **SKIP** — keep existing |
| `learning_ai_trails`           | Has custom `Toast.tsx` | **SKIP** — keep existing |
| `learning_ai_fastgap`          | No toast               | **ADD**                  |
| `learning_ai_jarvis_jr`        | No toast               | **ADD**                  |
| `learning_ai_flowmonk`         | No toast               | **ADD**                  |
| `learning_ai_notes`            | No toast               | **ADD**                  |
| `learning_ai_local_memory_gpt` | No toast               | **ADD**                  |
| `learning_ai_local_llms`       | No toast               | **ADD**                  |

**STOP condition:** If a repo you expected to have no toast actually has one (count > 3), **SKIP it**. Do NOT replace custom toasts.

---

## Per-Repo Procedure (for repos that need ToastProvider)

### Step 1: Check if `@bytelyst/ui` is already a dependency

```bash
grep '@bytelyst/ui' web/package.json 2>/dev/null || echo "NOT FOUND"
```

If NOT FOUND, add it to `web/package.json` (or `dashboard/package.json` for local-llms):

```json
{
  "dependencies": {
    "@bytelyst/ui": "file:../../learning_ai_common_plat/packages/ui"
  }
}
```

Then install:

```bash
cd web && pnpm install
```

### Step 2: Find the right place to add ToastProvider

**Critical:** `ToastProvider` is a client component (uses `useState`/`useEffect`). You **MUST NOT** add `'use client'` to the root `layout.tsx`. Instead:

**Check for existing providers wrapper:**

```bash
ls web/src/app/providers.tsx 2>/dev/null && echo "HAS providers.tsx" || echo "NO providers.tsx"
```

**Decision tree:**

```
Has providers.tsx?
  YES → Add ToastProvider INSIDE providers.tsx (it's already 'use client')
  NO  → Create a new providers.tsx with 'use client' + ToastProvider,
        then import it in layout.tsx
```

### Step 3A: If `providers.tsx` EXISTS — add ToastProvider there

Read the existing file:

```bash
cat web/src/app/providers.tsx
```

Wrap the outermost children with `<ToastProvider>`:

```tsx
// Add this import at the top
import { ToastProvider } from '@bytelyst/ui';

// Wrap children — ToastProvider should be the OUTERMOST wrapper
export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <ToastProvider>
      {/* ...all existing providers stay here... */}
      {children}
    </ToastProvider>
  );
}
```

### Step 3B: If NO `providers.tsx` — create one + wire into layout.tsx

**Create** `web/src/app/providers.tsx`:

```tsx
'use client';

import { ToastProvider } from '@bytelyst/ui';

export function Providers({ children }: { children: React.ReactNode }) {
  return <ToastProvider>{children}</ToastProvider>;
}
```

**Then edit** `web/src/app/layout.tsx` to wrap `{children}` with `<Providers>`:

Read the current layout first:

```bash
cat web/src/app/layout.tsx
```

Add the import and wrap:

```tsx
import { Providers } from './providers';

// Inside the <body> tag, wrap children:
<body>
  <Providers>{children}</Providers>
</body>;
```

**Critical:** Do NOT remove any existing content from `layout.tsx`. Only add the `Providers` import and wrapper.

### Step 4: Build Gate (MANDATORY)

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

**Common errors and fixes:**

| Error                                             | Fix                                                                                                |
| ------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `Cannot find module '@bytelyst/ui'`               | Run `pnpm install` — the dep wasn't installed                                                      |
| `'use client' must be at the top`                 | Ensure `'use client'` is the very first line in providers.tsx                                      |
| `Server component cannot import client component` | You accidentally imported ToastProvider directly in layout.tsx — use providers.tsx wrapper instead |

**If build fails:**

1. Read the error carefully
2. If it's a provider ordering issue, adjust the wrapper nesting
3. If it's unrelated to your change, check `git diff` to ensure you only changed what you intended

**STOP condition:** If build fails 3 times, revert changes:

```bash
git checkout -- web/src/app/layout.tsx web/src/app/providers.tsx web/package.json
```

### Step 5: Verify ToastProvider is actually rendering

Quick sanity check — the providers file should export something that wraps children:

```bash
grep -c 'ToastProvider' web/src/app/providers.tsx  # Must be >= 1
```

### Step 6: Commit and push

```bash
git add web/src/app/providers.tsx web/src/app/layout.tsx web/package.json pnpm-lock.yaml 2>/dev/null
git commit -m "feat(design-system): wire ToastProvider from @bytelyst/ui into root layout"
git push origin main
```

---

## Rollback Recipe

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

---

## Order (easiest first)

1. `learning_ai_flowmonk` — simple layout, no providers.tsx
2. `learning_ai_jarvis_jr` — simple layout
3. `learning_ai_notes` — has KeyboardShortcuts in app layout
4. `learning_ai_fastgap` — has providers.tsx (check)
5. `learning_ai_local_memory_gpt` — has providers.tsx (check)
6. `learning_ai_local_llms` — `dashboard/` path, adjust accordingly

Complete each repo fully (install → wire → build → commit → push) before moving to the next.

---

## Rules

- **NEVER replace custom toast implementations** — if a repo already has toast UI, SKIP it entirely
- **NEVER add `'use client'` to layout.tsx** — use a providers.tsx wrapper
- **NEVER remove existing providers** — only ADD ToastProvider as an outer wrapper
- **ONLY touch:** `providers.tsx`, `layout.tsx` (import line only), `package.json` (dep only)
- **Backup before edits** — `git stash` or copy files
- **Build must pass** before committing
- Commit message: `feat(design-system): wire ToastProvider from @bytelyst/ui into root layout`
