# Electrobun Launch Sequence (MANDATORY)

**Use the `agor-launcher` MCP tools** for ALL app lifecycle operations. Do NOT use raw bash commands for launch/stop/rebuild.

## MCP Tools (preferred)

| Tool                                    | Use When                                                           |
| --------------------------------------- | ------------------------------------------------------------------ |
| `mcp__agor-launcher__agor-start`        | Launch the app (`clean: true` to rebuild from scratch)             |
| `mcp__agor-launcher__agor-stop`         | Stop all running instances                                         |
| `mcp__agor-launcher__agor-restart`      | Stop + start (`clean: true` for clean restart)                     |
| `mcp__agor-launcher__agor-clean`        | Remove build caches without launching                              |
| `mcp__agor-launcher__agor-rebuild`      | Full rebuild: npm install + vite build + native C lib + PTY daemon |
| `mcp__agor-launcher__agor-status`       | Check running processes, ports, window                             |
| `mcp__agor-launcher__agor-kill-stale`   | Kill accumulated stale agor-ptyd processes                         |
| `mcp__agor-launcher__agor-build-native` | Rebuild libagor-resize.so + agor-ptyd                              |

## Fallback (if MCP unavailable)

```bash
./scripts/launch.sh start          # normal launch
./scripts/launch.sh start --clean  # clean build + launch
./scripts/launch.sh stop           # stop all
./scripts/launch.sh rebuild        # full rebuild
./scripts/launch.sh status         # check state
./scripts/launch.sh kill-stale     # clean up stale ptyd
```

## What Happens If You Skip Steps

- **No PTY daemon**: App crashes with `Connection timeout (5s). Is agor-ptyd running?`
- **No Vite**: WebView loads blank page (no frontend bundle)
- **No kill first**: Duplicate windows, port conflicts

## Rules

- ALWAYS use `agor-stop` before `agor-start` when relaunching
- Use `clean: true` when `src/bun/` files changed (Electrobun caches bundles)
- Use `agor-rebuild` after dependency changes or native code changes
- Use `agor-kill-stale` periodically (ptyd accumulates across sessions)
- NEVER launch manually with raw bash — always use MCP or scripts/launch.sh