[codex] Document source startup requirements

README.md

@@ -32,13 +32,17 @@ AgentForge turns agent work into a visible local workflow: queue tasks, watch li
 
 ```bash
 git clone https://github.com/hetaoBackend/agentforge.git
-cd agentforge/taskboard-electron
+cd agentforge
 
-bun install --ignore-scripts
+cd backend
+bun install --frozen-lockfile
+
+cd ../taskboard-electron
+bun install --frozen-lockfile
 bun run start
 ```
 
-The Electrobun dev command builds the renderer, starts the Bun backend in the desktop host, and relaunches the app while you work.
+Install dependencies in both `backend/` and `taskboard-electron/`: the Electrobun host imports backend source directly, so the backend package dependencies must exist even when you launch the desktop app. The Electrobun dev command builds the renderer, starts the Bun backend in the desktop host, and relaunches the app while you work.
 
 ### Build A DMG
 
@@ -64,7 +68,7 @@ The packaged app is built by Electrobun. Stable macOS builds write the DMG under
 ## Requirements
 
 - macOS 12+
-- [Bun](https://bun.sh) 1.3+
+- [Bun](https://bun.sh) 1.3+ on `PATH` (`command -v bun`)
 - [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) or [OpenAI Codex CLI](https://github.com/openai/codex) on `PATH`
 
 ## Skill Library
@@ -175,10 +179,16 @@ bun taskboard.ts
 Desktop app:
 
 ```bash
-cd taskboard-electron
+cd backend
+bun install --frozen-lockfile
+
+cd ../taskboard-electron
+bun install --frozen-lockfile
 bun run start
 ```
 
+When running the desktop app, do not start `backend/taskboard.ts` separately on the same machine: the Electrobun host starts the backend in-process on `127.0.0.1:9712`.
+
 Quality gates:
 
 ```bash

README.zh.md

@@ -32,13 +32,17 @@ AgentForge 把 AI 编程智能体变成可见、可排队、可调度的本地
 
 ```bash
 git clone https://github.com/hetaoBackend/agentforge.git
-cd agentforge/taskboard-electron
+cd agentforge
 
-bun install --ignore-scripts
+cd backend
+bun install --frozen-lockfile
+
+cd ../taskboard-electron
+bun install --frozen-lockfile
 bun run start
 ```
 
-开发命令会构建 Electrobun/React 前端，在桌面宿主进程中启动 Bun 后端，并在改动后重新启动 App。
+需要分别安装 `backend/` 和 `taskboard-electron/` 的依赖：Electrobun 宿主进程会直接 import 后端源码，所以即使启动的是桌面 App，后端 package 依赖也必须存在。开发命令会构建 Electrobun/React 前端，在桌面宿主进程中启动 Bun 后端，并在改动后重新启动 App。
 
 ### 构建 DMG
 
@@ -64,7 +68,7 @@ bun run make
 ## 环境要求
 
 - macOS 12+
-- [Bun](https://bun.sh) 1.3+
+- [Bun](https://bun.sh) 1.3+，并且在 `PATH` 中可找到 (`command -v bun`)
 - [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) 或 [OpenAI Codex CLI](https://github.com/openai/codex) 在 `PATH` 中
 
 ## Skill Library
@@ -175,10 +179,16 @@ bun taskboard.ts
 桌面 App:
 
 ```bash
-cd taskboard-electron
+cd backend
+bun install --frozen-lockfile
+
+cd ../taskboard-electron
+bun install --frozen-lockfile
 bun run start
 ```
 
+运行桌面 App 时，不要在同一台机器上另外启动 `backend/taskboard.ts`：Electrobun 宿主进程会在 `127.0.0.1:9712` 上启动内置后端。
+
 质量门禁:
 
 ```bash

docs/installation-troubleshooting.md

@@ -2,6 +2,53 @@
 
 This guide covers the most common issues when installing or building AgentForge's Electrobun desktop app.
 
+## `bun: command not found`
+
+AgentForge's source workflow expects `bun` to be available on `PATH`. If Bun is installed under the default macOS location but your shell cannot find it, add this to `~/.zshrc`:
+
+```zsh
+export BUN_INSTALL="$HOME/.bun"
+case ":$PATH:" in
+  *":$BUN_INSTALL/bin:"*) ;;
+  *) export PATH="$BUN_INSTALL/bin:$PATH" ;;
+esac
+```
+
+Then reload the shell and verify:
+
+```bash
+source ~/.zshrc
+command -v bun
+bun --version
+```
+
+## Missing Backend Dependencies
+
+When running the desktop app from source, install dependencies in both packages:
+
+```bash
+cd backend
+bun install --frozen-lockfile
+
+cd ../taskboard-electron
+bun install --frozen-lockfile
+bun run start
+```
+
+The desktop host imports backend TypeScript directly. If `backend/node_modules` is missing, startup can fail with an error such as `Cannot find package 'cron-parser'`.
+
+## Port `9712` Already In Use
+
+The desktop app starts the backend in-process on `127.0.0.1:9712`. If you previously started the backend directly, stop it before launching the desktop app.
+
+Check the port with:
+
+```bash
+lsof -nP -iTCP:9712 -sTCP:LISTEN
+```
+
+If a standalone `bun taskboard.ts` process is listening there, stop that terminal process and run the desktop app again.
+
 ## `bun install` Or `bun run build:check` Hangs
 
 The first Electrobun build can download native Electrobun CLI/core artifacts from GitHub releases. On slow networks this can look idle for a few minutes.
@@ -18,12 +65,17 @@ If the build stalls while Electrobun downloads native artifacts, use a VPN or re
 
 ## Clean Install
 
+From the repository root:
+
 ```bash
-cd taskboard-electron
-rm -rf node_modules build artifacts .bun
-rm -f bun.lock
+cd backend
+rm -rf node_modules
 bun pm cache rm
-bun install
+bun install --frozen-lockfile
+
+cd ../taskboard-electron
+rm -rf node_modules build artifacts .bun
+bun install --frozen-lockfile
 ```
 
 ## Build Tools
@@ -63,7 +115,11 @@ bun upgrade
 ## Verify Installation
 
 ```bash
-cd taskboard-electron
+cd backend
+bun install --frozen-lockfile
+
+cd ../taskboard-electron
+bun install --frozen-lockfile
 bun run typecheck
 bun run build:check
 bun run start

keep_running.sh

@@ -4,6 +4,13 @@
 # MacBook 合盖保持运行脚本
 # =========================
 
+# 确保非交互 bash 也能找到通过官方安装器安装到 ~/.bun/bin 的 Bun。
+export BUN_INSTALL="$HOME/.bun"
+case ":$PATH:" in
+  *":$BUN_INSTALL/bin:"*) ;;
+  *) export PATH="$BUN_INSTALL/bin:$PATH" ;;
+esac
+
 # 1. 保持 Mac 接电源不睡眠
 echo "[INFO] 设置接电源时系统不睡眠..."
 sudo pmset -c sleep 0
@@ -13,4 +20,4 @@ sudo pmset -c displaysleep 10 # 显示器可睡眠10分钟
 
 # 2. 启动关键进程并保持唤醒
 echo "[INFO] 启动进程并保持唤醒..."
-caffeinate -dimsu bash -c "cd taskboard-electron && bun run start"
+caffeinate -dimsu bash -c "cd taskboard-electron && bun run start"