fix(dev): replace .claude/launch.json symlink with repo-local definition

[itomek]

Summary

.claude/launch.json was a dangling symlink for every contributor except the original author — the dev-server launch config added in #1039 only worked on one machine. Replaced with a real in-repo file.

Why

The symlink target ../../../../.claude/launch.json resolves to ~/.claude/launch.json on the original author's machine, but escapes the repository root. On any other clone the relative path resolves four directories above .claude/ — a broken, nonexistent target. The five GAIA dev-server configs (Agent UI, FastAPI backend, Vite hot-reload, API server, MCP bridge) were silently non-functional for every other contributor.

Linked issue

Refs #1039 (no standalone issue; corrects a side-effect of that PR's launch config addition)

Changes

• Replaced .claude/launch.json symlink (mode 120000, target ../../../../.claude/launch.json) with a regular file (mode 100644) containing the five GAIA dev-server configs inline — content identical to what the symlink resolved to on the original machine.

Test plan

• git show HEAD:.claude/launch.json | head -3 outputs { — confirms a regular file, not a symlink blob
• preview_start "Agent UI backend only (FastAPI, no frontend)" starts uvicorn on port 4200 with no errors
• curl http://127.0.0.1:4200/ returns HTTP 200
• On a fresh clone (or with no ~/.claude/launch.json), .claude/launch.json is readable without a dangling symlink

Checklist

• I have linked a GitHub issue above (Refs #1039).
• I have described why this change is being made, not just what changed.
• I have run linting and tests locally — JSON-only typechange, no code affected.
• I have updated documentation if user-visible behavior changed — no user-visible change.

[github-actions]

The symlink was genuinely broken for every contributor but the original author — replacing it with the real file is the right fix, and the content matches what's documented in CLAUDE.md. No blocking issues.

---

Summary

A dangling symlink (../../../../.claude/launch.json escaping the repo root) is replaced with the actual JSON it resolved to on the original machine. The five dev-server configs are correct: all commands are valid CLI invocations, ports match the documented dev setup, and the JSON structure is well-formed. This is a minimal, focused fix with no code changes.

---

Issues Found

🟢 Minor — CLAUDE.md CLI reference omits mcp serve

The CLAUDE.md CLI listing under "Servers & infrastructure" enumerates gaia mcp {start|stop|status|test|agent|docker|add|list|remove|tools|test-client} but doesn't include serve — even though gaia mcp serve is a real, handled subcommand (cli.py:2353, cli.py:5981) and is now referenced in the launch config. Not a blocker for this PR, but worth a follow-up doc touch.

---

Strengths

• Minimal blast radius. Only the file type changes (symlink → regular file); the content is byte-for-byte identical to what the symlink resolved to on the original machine.
• All commands validated. gaia chat --ui, python -m gaia.ui.server, npm run dev --prefix, gaia api start --port 8080, and gaia mcp serve --port 8766 all correspond to real, registered CLI paths — confirmed against cli.py:1686-1687 (api), cli.py:2353 (mcp serve), and CLAUDE.md.
• Clear PR description. The "why" (symlink target escapes the repo root on every other clone) and the test plan are both concrete and reproducible.

---

Verdict

Approve. The fix is correct and the change scope is tight. The CLAUDE.md doc gap for mcp serve is worth a follow-up but doesn't block this PR.

[itomek]

Added serve to the gaia mcp subcommand listing in CLAUDE.md (line 508).

[github-actions]

Correct fix for a real problem — the dangling symlink silently broke all five dev-server launch configs for every contributor except the original author. The new file content is identical to what the symlink resolved to on that one machine, so this is a zero-behavior-change fix for all other clones.

Summary

Two files changed: .claude/launch.json (symlink → regular file, same content) and CLAUDE.md (adds serve to the gaia mcp subcommand list, consistent with the gaia mcp serve --port 8766 entry now in launch.json). Scope is tight, description explains the root cause clearly.

Issues Found

🟢 Minor — npm run dev --prefix argument ordering (.claude/launch.json:34–37)

npm run dev --prefix src/gaia/apps/webui works, but npm treats --prefix as a prefix-for-npm-itself flag, not a "run in directory" flag — behaviour can vary across npm versions. The safer form is to pass --prefix before the script name:

      "runtimeArgs": ["run", "--prefix", "src/gaia/apps/webui", "dev"],

This matches the canonical npm --prefix <dir> run <script> invocation documented in npm's man page and avoids any version-specific argument parsing ambiguity.

---

🟢 Minor — Configs 1 and 2 share port: 4200 with autoPort: false (.claude/launch.json:22,29)

This is fine for alternative configs (not run together), but worth a brief inline comment so a future contributor doesn't wonder if it's a copy-paste error. Not blocking.

Strengths

• Root cause analysis in the PR description is precise: ../../../../.claude/launch.json escaping the repo root is exactly right, and the fix is the minimal correct solution.
• All five configs map to the actual GAIA dev commands documented in CLAUDE.md — no invented commands, no stale port numbers.
• CLAUDE.md update is scoped to exactly what's needed: adding serve to the MCP subcommand list to match the launch config entry.

Verdict

Approve — one nit on argument ordering that's worth a one-line fix but is not blocking. The symlink replacement is correct and the CLAUDE.md update is accurate.

[itomek]

Fixed the npm arg ordering (moved --prefix before dev). The duplicate port 4200 nit can't be addressed inline — JSON has no comment syntax.

[github-actions]

Correct fix — the broken symlink was silently preventing every contributor from using the five GAIA dev-server launch configs. Replacing it with an inline file is the right call.

Summary

The symlink ../../../../.claude/launch.json only resolved on the original author's machine; all other contributors had a dangling reference. The fix inlines the five dev-server configurations as a regular file, and the accompanying CLAUDE.md update adds the already-implemented gaia mcp serve subcommand to the documented command list.

I verified all five configurations against the live codebase before posting:

Config	Command	Port	Status
Agent UI combined	uv run gaia chat --ui	4200	✅
FastAPI backend	uv run python -m gaia.ui.server --port 4200 --host 127.0.0.1	4200	✅
Vite hot-reload	npm run --prefix src/gaia/apps/webui dev	5174	✅ (matches vite.config.ts)
API server	uv run gaia api start --port 8080	8080	✅ (choices=["start","stop","status"] at cli.py:1690)
MCP server	uv run gaia mcp serve --port 8766	8766	✅ (default port matches cli.py:2362)

Issues Found

None.

Strengths

• Surgical scope: touches exactly the two files required, no drive-by changes.
• PR description is clear and self-contained — the symlink path math is explained explicitly, making the root cause obvious to reviewers without reading any code.
• The three commits are logically sequenced and follow conventional-commits style.

Verdict

Approve — no blocking issues; all configs check out against the codebase.