diff --git a/scripts/add-agent.sh b/scripts/add-agent.sh
new file mode 100755
index 0000000..a6b0000
--- /dev/null
+++ b/scripts/add-agent.sh
@@ -0,0 +1,173 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'USAGE'
+Usage:
+  scripts/add-agent.sh <agent-id> [--display-name <name>] [--openclaw-config <path>] [--dry-run]
+
+Examples:
+  scripts/add-agent.sh kimi-helper
+  scripts/add-agent.sh kimi-helper --display-name "Kimi Helper"
+  scripts/add-agent.sh kimi-helper --openclaw-config "$HOME/.openclaw/openclaw.json"
+
+What it does:
+  1) Creates agents/<agent-id>/ with AGENT-CARD.md, AGENTS.md, current.md, inbox.md, drafts/
+  2) Prints QMD path JSON snippet for OpenClaw memory.qmd.paths
+  3) If --openclaw-config is provided, appends this agent path into the config (idempotent)
+USAGE
+}
+
+if [[ $# -lt 1 ]]; then
+  usage
+  exit 1
+fi
+
+AGENT_ID="$1"
+shift
+
+if [[ ! "$AGENT_ID" =~ ^[a-z0-9][a-z0-9-]{1,62}$ ]]; then
+  echo "ERROR: agent-id must match regex: ^[a-z0-9][a-z0-9-]{1,62}$" >&2
+  exit 1
+fi
+
+DISPLAY_NAME="$AGENT_ID"
+OPENCLAW_CONFIG=""
+DRY_RUN="false"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --display-name)
+      DISPLAY_NAME="${2:-}"
+      shift 2
+      ;;
+    --openclaw-config)
+      OPENCLAW_CONFIG="${2:-}"
+      shift 2
+      ;;
+    --dry-run)
+      DRY_RUN="true"
+      shift
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "ERROR: unknown arg: $1" >&2
+      usage
+      exit 1
+      ;;
+  esac
+done
+
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+cd "$REPO_ROOT"
+
+TARGET_DIR="agents/${AGENT_ID}"
+
+if [[ -e "$TARGET_DIR" ]]; then
+  echo "ERROR: ${TARGET_DIR} already exists" >&2
+  exit 1
+fi
+
+create_files() {
+  mkdir -p "$TARGET_DIR/drafts"
+
+  cat > "$TARGET_DIR/AGENT-CARD.md" <<CARD
+# AGENT-CARD: ${AGENT_ID}
+
+- agent_id: \`${AGENT_ID}\`
+- display_name: \`${DISPLAY_NAME}\`
+- writable_scope: \`agents/${AGENT_ID}/**\`
+- query_authority: \`remote MCP/QMD\`
+- promote_target: \`shared/long-term/**\`
+CARD
+
+  cat > "$TARGET_DIR/AGENTS.md" <<GUIDE
+# AGENTS.md (agents/${AGENT_ID})
+
+## 工作根路径
+- 当前工作根路径 = 本文件所在目录（\`memory-repo/agents/${AGENT_ID}/\`）。
+- 仅在本目录维护该 agent 的私域工作记忆。
+
+## 目录类型
+- 类型：\`agent\`。
+
+## 目录作用
+- 私域工作记忆：当前上下文、待办、草稿。
+
+## 查询规则
+- 群体共享记忆查询必须走远程 MCP/QMD。
+- 本地检索仅用于未 push 草稿、故障降级、本地调试。
+
+## Git 规则
+- 修改前先 \`git fetch --prune origin\`，再 \`git pull --rebase\`。
+- 小步提交，避免跨 lane 混改。
+
+## Promote 规则
+- 稳定结论通过 task 或 promote 流程进入 \`shared/long-term/\`。
+GUIDE
+
+  cat > "$TARGET_DIR/current.md" <<CURRENT
+# current
+
+- agent_id: ${AGENT_ID}
+- focus: <当前任务焦点>
+- next_action: <下一个动作>
+CURRENT
+
+  cat > "$TARGET_DIR/inbox.md" <<INBOX
+# inbox
+
+- [ ] <待整理记忆 1>
+INBOX
+}
+
+QMD_SNIPPET=$(cat <<SNIPPET
+{
+  "path": "~/project/collective-memory-repo/agents/${AGENT_ID}",
+  "name": "collective-agent-${AGENT_ID}",
+  "pattern": "**/*.md"
+}
+SNIPPET
+)
+
+if [[ "$DRY_RUN" == "true" ]]; then
+  echo "[dry-run] would create: ${TARGET_DIR}/"
+  echo
+  echo "QMD path snippet:"
+  echo "$QMD_SNIPPET"
+  exit 0
+fi
+
+create_files
+
+echo "Created ${TARGET_DIR}"
+echo
+echo "QMD path snippet (append into memory.qmd.paths):"
+echo "$QMD_SNIPPET"
+
+if [[ -n "$OPENCLAW_CONFIG" ]]; then
+  if ! command -v jq >/dev/null 2>&1; then
+    echo "WARN: jq not found, skip updating openclaw config: ${OPENCLAW_CONFIG}" >&2
+    exit 0
+  fi
+  if [[ ! -f "$OPENCLAW_CONFIG" ]]; then
+    echo "WARN: openclaw config not found: ${OPENCLAW_CONFIG}" >&2
+    exit 0
+  fi
+
+  TMP_FILE="${OPENCLAW_CONFIG}.tmp.$$"
+  jq --arg p "~/project/collective-memory-repo/agents/${AGENT_ID}" \
+     --arg n "collective-agent-${AGENT_ID}" \
+     '
+       .memory.qmd.paths |= (
+         if any(.[]?; .path == $p and .name == $n) then .
+         else . + [{"path": $p, "name": $n, "pattern": "**/*.md"}]
+         end
+       )
+     ' "$OPENCLAW_CONFIG" > "$TMP_FILE"
+  mv "$TMP_FILE" "$OPENCLAW_CONFIG"
+  echo "Updated OpenClaw config: ${OPENCLAW_CONFIG}"
+fi
diff --git a/templates/AGENT-ONBOARDING.md b/templates/AGENT-ONBOARDING.md
new file mode 100644
index 0000000..a9e9bc9
--- /dev/null
+++ b/templates/AGENT-ONBOARDING.md
@@ -0,0 +1,45 @@
+# New Agent Onboarding Template
+
+## 1) Create agent lane
+
+```bash
+cd /Users/lingyuzeng/project/collective-memory-repo
+scripts/add-agent.sh <agent-id>
+```
+
+Example:
+
+```bash
+scripts/add-agent.sh kimi-helper
+```
+
+## 2) (Optional) Auto update OpenClaw qmd paths
+
+```bash
+scripts/add-agent.sh <agent-id> --openclaw-config ~/.openclaw/openclaw.json
+```
+
+## 3) Commit and push
+
+```bash
+git add agents/<agent-id>
+git commit -m "feat(agent): add <agent-id> memory lane"
+git push
+```
+
+## 4) Verify memory-gateway visibility
+
+```bash
+curl -fsS http://100.64.0.45:8787/health
+printf '{"branch":"main","require_latest":true}' \
+| curl -fsS -H 'content-type: application/json' -d @- \
+  http://100.64.0.45:8787/memory/status
+```
+
+## 5) Query smoke test
+
+```bash
+printf '{"query":"<agent-id>","branch":"main","require_latest":true,"top_k":3}' \
+| curl -fsS -H 'content-type: application/json' -d @- \
+  http://100.64.0.45:8787/memory/search
+```