# Track B: Vercel Code Readiness — Fix Repos for Deployment

> **Agent:** Any Codex agent with repo access (local or cloud)
> **Prompts:** 4 (B1–B3 run in parallel, B4 runs last after Track A completes A2)
> **Reference docs:**
>
> - [`ECOSYSTEM_WEB_APPS_INVENTORY.md`](./ECOSYSTEM_WEB_APPS_INVENTORY.md) — full Vercel audit + per-app status
> - Individual `ROADMAP_*.md` files — per-app gaps, env vars, and deployment steps

---

## Progress Tracker

| #   | Prompt                   | Repos |      Status      | Commits | Verified |
| --- | ------------------------ | :---: | :--------------: | :-----: | :------: |
| B1  | Fix `file:` refs         |   7   |   ✅ Complete    |   5/7   |    ✅    |
| B2  | Fix `output: standalone` |   4   |   ✅ Complete    |   4/4   |    ✅    |
| B3  | EffoRise `vercel.json`   |   1   |   ✅ Complete    |   1/1   |    ✅    |
| B4  | Update `.npmrc`          |  12   | ⬜ Blocked on A2 |  0/12   |    ⬜    |

**Execution order:**

```
B1: Fix file: refs ──────┐
B2: Fix standalone ──────┼──→  B4: Update .npmrc (blocked until Track A → A2 done)
B3: EffoRise vercel.json ┘
```

---

## B1: Fix `file:` References Across 7 Repos

> **Depends on:** Nothing (packages are already published to Gitea)
> **Blocks:** Nothing

### Per-Repo Checklist

| #   | Repo                           | File                     | Packages to fix   | Edited | Built | Committed | Pushed |
| --- | ------------------------------ | ------------------------ | ----------------- | :----: | :---: | :-------: | :----: |
| 1   | `learning_ai_clock`            | `web/package.json`       | design-tokens, ui |   ⬜   |  ⬜   |    ⬜     |   ⬜   |
| 2   | `learning_ai_jarvis_jr`        | `web/package.json`       | ui                |   ⬜   |  ⬜   |    ⬜     |   ⬜   |
| 3   | `learning_ai_fastgap`          | `web/package.json`       | ui                |   ⬜   |  ⬜   |    ⬜     |   ⬜   |
| 4   | `learning_ai_flowmonk`         | `web/package.json`       | ui                |   ⬜   |  ⬜   |    ⬜     |   ⬜   |
| 5   | `learning_ai_notes`            | `web/package.json`       | ui                |   ⬜   |  ⬜   |    ⬜     |   ⬜   |
| 6   | `learning_ai_local_memory_gpt` | `web/package.json`       | ui                |   ⬜   |  ⬜   |    ⬜     |   ⬜   |
| 7   | `learning_ai_local_llms`       | `dashboard/package.json` | design-tokens, ui |   ⬜   |  ⬜   |    ⬜     |   ⬜   |

### Prompt

```
TASK: Convert all file: references to @bytelyst/* packages into semver ^0.1.0 references across 7 web app repos.

CONTEXT:
- 7 repos have web/package.json (or dashboard/package.json) files with file: references to ../../learning_ai_common_plat/packages/*
- These fail on Vercel because the sibling repo doesn't exist during build
- The packages are already published to the Gitea npm registry
- Each fix: change "file:../../learning_ai_common_plat/packages/X" to "^0.1.0"

REPOS AND FILES TO FIX:

1. learning_ai_clock/web/package.json
   - "@bytelyst/design-tokens": "file:..." → "^0.1.0"
   - "@bytelyst/ui": "file:..." → "^0.1.0"

2. learning_ai_jarvis_jr/web/package.json
   - "@bytelyst/ui": "file:..." → "^0.1.0"

3. learning_ai_fastgap/web/package.json
   - "@bytelyst/ui": "file:..." → "^0.1.0"

4. learning_ai_flowmonk/web/package.json
   - "@bytelyst/ui": "file:..." → "^0.1.0"

5. learning_ai_notes/web/package.json
   - "@bytelyst/ui": "file:..." → "^0.1.0"

6. learning_ai_local_memory_gpt/web/package.json
   - "@bytelyst/ui": "file:..." → "^0.1.0"

7. learning_ai_local_llms/dashboard/package.json
   - "@bytelyst/design-tokens": "file:..." → "^0.1.0"
   - "@bytelyst/ui": "file:..." → "^0.1.0"

FOR EACH REPO (repeat 7 times):
- [ ] 1. Edit the package.json — replace file: refs with ^0.1.0
- [ ] 2. Run: cd web && pnpm install (or cd dashboard for LLM Lab)
- [ ] 3. Verify no file: refs remain: grep -r "file:.*common_plat" package.json
         Expected: no output
- [ ] 4. Run: pnpm build
         Expected: build succeeds with exit code 0
- [ ] 5. Commit: fix(web): convert file: refs to registry semver for Vercel compatibility
- [ ] 6. Push to origin main

VERIFICATION (after all 7 repos):
  # Confirm zero file: refs remain across all repos
  for repo in learning_ai_clock learning_ai_jarvis_jr learning_ai_fastgap learning_ai_flowmonk learning_ai_notes learning_ai_local_memory_gpt learning_ai_local_llms; do
    echo -n "$repo: "
    grep -rl "file:.*common_plat" $repo/web/package.json $repo/dashboard/package.json 2>/dev/null | wc -l | tr -d ' '
    echo " file: refs remaining"
  done
  # Expected: all show "0 file: refs remaining"

SUCCESS CRITERIA:
- All 7 repos have zero file: references in their web/dashboard package.json
- All 7 builds pass (pnpm build exits 0)
- All 7 commits pushed to origin main
- No other dependencies or source code modified

DO NOT:
- Change any other dependencies
- Modify any source code
- Skip the build verification step for any repo
```

---

## B2: Fix Hardcoded `output: standalone` in 4 Repos

> **Depends on:** Nothing
> **Blocks:** Nothing

### Per-Repo Checklist

| #   | Repo                           | File                 | Pattern               | Edited | Docker Build | Vercel Build | Committed | Pushed |
| --- | ------------------------------ | -------------------- | --------------------- | :----: | :----------: | :----------: | :-------: | :----: |
| 1   | `learning_ai_fastgap`          | `web/next.config.ts` | output + tracing root |   ⬜   |      ⬜      |      ⬜      |    ⬜     |   ⬜   |
| 2   | `learning_ai_notes`            | `web/next.config.ts` | output + tracing root |   ⬜   |      ⬜      |      ⬜      |    ⬜     |   ⬜   |
| 3   | `learning_ai_trails`           | `web/next.config.ts` | output only           |   ⬜   |      ⬜      |      ⬜      |    ⬜     |   ⬜   |
| 4   | `learning_ai_local_memory_gpt` | `web/next.config.ts` | output only           |   ⬜   |      ⬜      |      ⬜      |    ⬜     |   ⬜   |

> **Skip:** `learning_ai_local_llms/dashboard/next.config.ts` — LLM Lab not viable on Vercel (needs local Ollama)

### Prompt

```
TASK: Make the Next.js output mode Vercel-aware in 4 repos that currently hardcode output: 'standalone'.

CONTEXT:
- Vercel manages its own output mode — hardcoded standalone breaks Vercel builds
- The fix: wrap standalone output in a process.env.VERCEL conditional
- Docker builds (which don't set VERCEL env var) will still get standalone mode

REPOS AND EXACT CHANGES:

1. learning_ai_fastgap/web/next.config.ts
   Change:
     output: "standalone",
     outputFileTracingRoot: path.join(process.cwd(), ".."),
   To:
     ...(process.env.VERCEL ? {} : {
       output: "standalone",
       outputFileTracingRoot: path.join(process.cwd(), ".."),
     }),

2. learning_ai_notes/web/next.config.ts
   Same pattern as #1 (output + outputFileTracingRoot).

3. learning_ai_trails/web/next.config.ts
   Change:
     output: 'standalone',
   To:
     ...(process.env.VERCEL ? {} : { output: 'standalone' }),

4. learning_ai_local_memory_gpt/web/next.config.ts
   Same pattern as #3 (output only).

FOR EACH REPO (repeat 4 times):
- [ ] 1. Edit next.config.ts with the VERCEL conditional
- [ ] 2. Verify Docker build still works (standalone activates without VERCEL env):
         cd web && pnpm build
         # Check output: look for "Creating an optimized production build" + ".next/standalone/" dir
         ls -d .next/standalone/ && echo "PASS: standalone created" || echo "FAIL"
- [ ] 3. Verify Vercel-mode build works (standalone skipped with VERCEL env):
         cd web && VERCEL=1 pnpm build
         # Check output: .next/standalone/ should NOT exist
         ls -d .next/standalone/ 2>/dev/null && echo "FAIL: standalone still created" || echo "PASS: no standalone"
- [ ] 4. Commit: fix(web): make output mode Vercel-aware — conditional standalone
- [ ] 5. Push to origin main

VERIFICATION (after all 4 repos):
  for repo in learning_ai_fastgap learning_ai_notes learning_ai_trails learning_ai_local_memory_gpt; do
    echo "=== $repo ==="
    cd $repo/web
    grep -c "process.env.VERCEL" next.config.ts
    # Expected: 1 (the conditional)
    cd ../..
  done

SUCCESS CRITERIA:
- All 4 next.config.ts files contain process.env.VERCEL conditional
- Docker build (no VERCEL env) produces .next/standalone/
- Vercel build (VERCEL=1) does NOT produce .next/standalone/
- All 4 commits pushed to origin main
- No other config options changed

DO NOT:
- Change any other config options in next.config.ts
- Remove the standalone output entirely — Docker builds still need it
- Touch the LLM Lab dashboard (not viable on Vercel)
```

---

## B3: Create vercel.json for EffoRise (Vite SPA)

> **Depends on:** Nothing
> **Blocks:** Nothing

### Checklist

| Step | Description               | Done |
| ---- | ------------------------- | :--: |
| 1    | Create `vercel.json`      |  ⬜  |
| 2    | Verify local build        |  ⬜  |
| 3    | Verify SPA routing config |  ⬜  |
| 4    | Commit + push             |  ⬜  |

### Prompt

```
TASK: Create a vercel.json file for the EffoRise Vite SPA to handle client-side routing and API proxy configuration.

CONTEXT:
- EffoRise is a Vite + React 19 SPA (NOT Next.js) in the learning_ai_efforise repo
- The Vite config is at the repo root (client/ directory has the SPA)
- Build output goes to dist/public/ (custom, not default dist/)
- Uses wouter for client-side routing — all routes must serve index.html
- The backend API is at https://api.bytelyst.com/efforise
- Currently uses a dev proxy /api → localhost:4020

TASK LIST:
- [ ] 1. Create client/vercel.json with:
         {
           "$schema": "https://openapi.vercel.sh/vercel.json",
           "framework": "vite",
           "buildCommand": "pnpm build",
           "outputDirectory": "dist/public",
           "rewrites": [
             { "source": "/api/(.*)", "destination": "https://api.bytelyst.com/efforise/$1" },
             { "source": "/(.*)", "destination": "/index.html" }
           ]
         }
- [ ] 2. Verify local build: cd client && pnpm build
         Expected: exit code 0, dist/public/index.html exists
- [ ] 3. Verify vercel.json is valid JSON: cat client/vercel.json | jq .
         Expected: formatted JSON output, no parse errors
- [ ] 4. Commit: feat(web): add vercel.json for Vite SPA deployment
- [ ] 5. Push to origin main

VERIFICATION:
  # Build works
  cd client && pnpm build && echo "BUILD: PASS" || echo "BUILD: FAIL"

  # Output directory exists
  ls client/dist/public/index.html && echo "OUTPUT: PASS" || echo "OUTPUT: FAIL"

  # vercel.json valid
  jq '.rewrites | length' client/vercel.json
  # Expected: 2

SUCCESS CRITERIA:
- client/vercel.json exists with correct framework, build command, output directory, and rewrites
- Local build still produces dist/public/index.html
- vercel.json is valid JSON
- Commit pushed to origin main

DO NOT:
- Modify vite.config.ts
- Change any source code
- Add Vercel-specific code to the application
```

---

## B4: Update .npmrc Across All Product Repos

> **Depends on:** Track A → A2 complete (`gitea.bytelyst.com` live + verified)
> **Blocks:** All Vercel deployments (this is the final gate)

### Pre-flight Check (must pass before starting)

```bash
# Verify gitea.bytelyst.com is live and serving packages
curl -sf https://gitea.bytelyst.com/api/packages/ByteLyst/npm/@bytelyst%2ferrors | jq '.name'
# Expected: "@bytelyst/errors"
# If this fails, DO NOT proceed — Track A → A2 is not complete
```

### Per-Repo Checklist

| #   | Repo                                | .npmrc locations           | Updated | Install OK | Committed | Pushed |
| --- | ----------------------------------- | -------------------------- | :-----: | :--------: | :-------: | :----: |
| 1   | `learning_voice_ai_agent`           | root, user-dashboard-web/  |   ⬜    |     ⬜     |    ⬜     |   ⬜   |
| 2   | `learning_ai_clock`                 | root, web/                 |   ⬜    |     ⬜     |    ⬜     |   ⬜   |
| 3   | `learning_ai_jarvis_jr`             | root, web/                 |   ⬜    |     ⬜     |    ⬜     |   ⬜   |
| 4   | `learning_ai_fastgap`               | root, web/                 |   ⬜    |     ⬜     |    ⬜     |   ⬜   |
| 5   | `learning_ai_flowmonk`              | root, web/, mobile/        |   ⬜    |     ⬜     |    ⬜     |   ⬜   |
| 6   | `learning_ai_notes`                 | root, web/, mobile/        |   ⬜    |     ⬜     |    ⬜     |   ⬜   |
| 7   | `learning_ai_trails`                | root, web/, sdk/           |   ⬜    |     ⬜     |    ⬜     |   ⬜   |
| 8   | `learning_multimodal_memory_agents` | root, mindlyst-native/web/ |   ⬜    |     ⬜     |    ⬜     |   ⬜   |
| 9   | `learning_ai_local_memory_gpt`      | root, web/                 |   ⬜    |     ⬜     |    ⬜     |   ⬜   |
| 10  | `learning_ai_efforise`              | root, mobile/              |   ⬜    |     ⬜     |    ⬜     |   ⬜   |
| 11  | `learning_ai_local_llms`            | dashboard/                 |   ⬜    |     ⬜     |    ⬜     |   ⬜   |
| 12  | `learning_ai_peakpulse`             | root                       |   ⬜    |     ⬜     |    ⬜     |   ⬜   |

### Prompt

```
TASK: Update .npmrc files in all product repos to point to the public Gitea npm registry at gitea.bytelyst.com.

PRE-FLIGHT (must pass before starting):
  curl -sf https://gitea.bytelyst.com/api/packages/ByteLyst/npm/@bytelyst%2ferrors | jq '.name'
  # Must return "@bytelyst/errors" — if not, STOP and report that Track A → A2 is not done

CONTEXT:
- All product repos currently have .npmrc pointing to http://localhost:3300 (local Gitea)
- Gitea is now accessible at https://gitea.bytelyst.com via Caddy reverse proxy
- The npm registry URL is: https://gitea.bytelyst.com/api/packages/ByteLyst/npm/
- Auth token is passed via GITEA_NPM_TOKEN env var
- This change enables Vercel builds to install @bytelyst/* packages

TARGET .npmrc CONTENT (same for all repos):
  @bytelyst:registry=https://gitea.bytelyst.com/api/packages/ByteLyst/npm/
  //gitea.bytelyst.com/api/packages/ByteLyst/npm/:_authToken=${GITEA_NPM_TOKEN}

REPOS TO UPDATE (12 total — see checklist above for .npmrc locations):

 1. learning_voice_ai_agent         (root .npmrc + user-dashboard-web/.npmrc)
 2. learning_ai_clock                (root + web/)
 3. learning_ai_jarvis_jr            (root + web/)
 4. learning_ai_fastgap              (root + web/)
 5. learning_ai_flowmonk             (root + web/ + mobile/)
 6. learning_ai_notes                (root + web/ + mobile/)
 7. learning_ai_trails               (root + web/ + sdk/)
 8. learning_multimodal_memory_agents (root + mindlyst-native/web/)
 9. learning_ai_local_memory_gpt     (root + web/)
10. learning_ai_efforise             (root + mobile/)
11. learning_ai_local_llms           (dashboard/)
12. learning_ai_peakpulse            (root)

FOR EACH REPO (repeat 12 times):
- [ ] 1. Find all .npmrc files: find . -name ".npmrc" -not -path "*/node_modules/*"
- [ ] 2. In each .npmrc, replace the @bytelyst registry line:
         OLD: @bytelyst:registry=http://localhost:3300/api/packages/ByteLyst/npm/
         NEW: @bytelyst:registry=https://gitea.bytelyst.com/api/packages/ByteLyst/npm/
- [ ] 3. Ensure the auth token line exists:
         //gitea.bytelyst.com/api/packages/ByteLyst/npm/:_authToken=${GITEA_NPM_TOKEN}
- [ ] 4. Verify no localhost:3300 references remain:
         grep -r "localhost:3300" . --include=".npmrc"
         Expected: no output
- [ ] 5. Verify packages resolve:
         GITEA_NPM_TOKEN=<token> pnpm install
         Expected: exit code 0, all @bytelyst/* packages resolved
- [ ] 6. Commit: chore: update .npmrc to public Gitea registry at gitea.bytelyst.com
- [ ] 7. Push to origin main

VERIFICATION (after all 12 repos — run from parent directory containing all repos):
  echo "=== .npmrc Migration Verification ==="

  # Check no localhost:3300 remains anywhere
  for repo in learning_voice_ai_agent learning_ai_clock learning_ai_jarvis_jr learning_ai_fastgap learning_ai_flowmonk learning_ai_notes learning_ai_trails learning_multimodal_memory_agents learning_ai_local_memory_gpt learning_ai_efforise learning_ai_local_llms learning_ai_peakpulse; do
    count=$(grep -rl "localhost:3300" $repo/ --include=".npmrc" 2>/dev/null | wc -l | tr -d ' ')
    echo "$repo: $count old refs remaining"
  done
  # Expected: all show "0 old refs remaining"

  # End-to-end build test on one repo
  cd learning_ai_clock/web
  GITEA_NPM_TOKEN=<token> pnpm install && pnpm build && echo "E2E: PASS" || echo "E2E: FAIL"
  # Expected: "E2E: PASS"

SUCCESS CRITERIA:
- All 12 repos have zero localhost:3300 references in .npmrc files
- All 12 repos can resolve @bytelyst/* packages via gitea.bytelyst.com
- At least one repo verified with full pnpm install + pnpm build
- All 12 commits pushed to origin main
- No package versions changed, no auth tokens hardcoded

DO NOT:
- Change any package versions
- Remove any other registry configurations (e.g., npmjs.org for non-@bytelyst packages)
- Hardcode the auth token — always use ${GITEA_NPM_TOKEN}
- Proceed if the pre-flight check fails
```

---

## Track B — Final Verification Checklist

After all 4 prompts are complete, verify the full picture:

```bash
echo "=== Track B Final Verification ==="

echo "--- B1: file: refs (7 repos) ---"
for repo in learning_ai_clock learning_ai_jarvis_jr learning_ai_fastgap learning_ai_flowmonk learning_ai_notes learning_ai_local_memory_gpt learning_ai_local_llms; do
  count=$(grep -rl "file:.*common_plat" $repo/web/package.json $repo/dashboard/package.json 2>/dev/null | wc -l | tr -d ' ')
  echo "$repo: $count file: refs"
done
# Expected: all 0

echo "--- B2: standalone conditional (4 repos) ---"
for repo in learning_ai_fastgap learning_ai_notes learning_ai_trails learning_ai_local_memory_gpt; do
  count=$(grep -c "process.env.VERCEL" $repo/web/next.config.ts 2>/dev/null)
  echo "$repo: $count VERCEL conditionals"
done
# Expected: all 1

echo "--- B3: EffoRise vercel.json ---"
jq '.rewrites | length' learning_ai_efforise/client/vercel.json 2>/dev/null
# Expected: 2

echo "--- B4: .npmrc migration (12 repos) ---"
for repo in learning_voice_ai_agent learning_ai_clock learning_ai_jarvis_jr learning_ai_fastgap learning_ai_flowmonk learning_ai_notes learning_ai_trails learning_multimodal_memory_agents learning_ai_local_memory_gpt learning_ai_efforise learning_ai_local_llms learning_ai_peakpulse; do
  count=$(grep -rl "localhost:3300" $repo/ --include=".npmrc" 2>/dev/null | wc -l | tr -d ' ')
  echo "$repo: $count old .npmrc refs"
done
# Expected: all 0
```

**All checks must pass before Track B is considered complete.**

---

## After Both Tracks Complete — Vercel Project Setup (Manual)

Once Track A and Track B are both verified, the remaining work is manual in the Vercel UI:

| #   | App               | Vercel Root Dir          | Framework | Key Env Vars                                           | Roadmap                                                    |
| --- | ----------------- | ------------------------ | --------- | ------------------------------------------------------ | ---------------------------------------------------------- |
| 1   | Admin Dashboard   | `dashboards/admin-web`   | Next.js   | `COSMOS_ENDPOINT`, `COSMOS_KEY`, `JWT_SECRET`          | [ROADMAP_ADMIN_WEB.md](./ROADMAP_ADMIN_WEB.md)             |
| 2   | Tracker Dashboard | `dashboards/tracker-web` | Next.js   | `JWT_SECRET`, `PLATFORM_SERVICE_URL`                   | [ROADMAP_TRACKER_WEB.md](./ROADMAP_TRACKER_WEB.md)         |
| 3   | User Dashboard    | `user-dashboard-web`     | Next.js   | `PLATFORM_SERVICE_URL`, `ACTIONTRAIL_SERVICE_URL`      | [ROADMAP_USER_DASHBOARD.md](./ROADMAP_USER_DASHBOARD.md)   |
| 4   | ChronoMind Web    | `web`                    | Next.js   | `GITEA_NPM_TOKEN`                                      | [ROADMAP_CHRONOMIND_WEB.md](./ROADMAP_CHRONOMIND_WEB.md)   |
| 5   | JarvisJr Web      | `web`                    | Next.js   | `GITEA_NPM_TOKEN`, `NEXT_PUBLIC_PLATFORM_URL`          | [ROADMAP_JARVISJR_WEB.md](./ROADMAP_JARVISJR_WEB.md)       |
| 6   | NomGap Web        | `web`                    | Next.js   | `GITEA_NPM_TOKEN`, `NEXT_PUBLIC_BACKEND_URL`           | [ROADMAP_NOMGAP_WEB.md](./ROADMAP_NOMGAP_WEB.md)           |
| 7   | FlowMonk Web      | `web`                    | Next.js   | `GITEA_NPM_TOKEN`, `NEXT_PUBLIC_BACKEND_URL`           | [ROADMAP_FLOWMONK_WEB.md](./ROADMAP_FLOWMONK_WEB.md)       |
| 8   | NoteLett Web      | `web`                    | Next.js   | `GITEA_NPM_TOKEN`, `NEXT_PUBLIC_BACKEND_URL`           | [ROADMAP_NOTELETT_WEB.md](./ROADMAP_NOTELETT_WEB.md)       |
| 9   | ActionTrail Web   | `web`                    | Next.js   | `GITEA_NPM_TOKEN`, `NEXT_PUBLIC_BACKEND_URL`           | [ROADMAP_ACTIONTRAIL_WEB.md](./ROADMAP_ACTIONTRAIL_WEB.md) |
| 10  | MindLyst Web      | `mindlyst-native/web`    | Next.js   | `GITEA_NPM_TOKEN`, `COSMOS_ENDPOINT`, `OPENAI_API_KEY` | [ROADMAP_MINDLYST_WEB.md](./ROADMAP_MINDLYST_WEB.md)       |
| 11  | LocalMemGPT Web   | `web`                    | Next.js   | `GITEA_NPM_TOKEN`, `NEXT_PUBLIC_BACKEND_URL`           | [ROADMAP_LOCALMEMGPT_WEB.md](./ROADMAP_LOCALMEMGPT_WEB.md) |
| 12  | EffoRise Client   | `client`                 | Vite      | `GITEA_NPM_TOKEN`, `VITE_BACKEND_URL`                  | [ROADMAP_EFFORISE.md](./ROADMAP_EFFORISE.md)               |

**Every Vercel project needs `GITEA_NPM_TOKEN` set.** See individual roadmap files for the complete env var list per app.
