[Phase 1/4] Graph generation (scan + git history + batch analyze + layers/tour)...
[Phase 2/4] Domain enrichment (Claude)...
[Phase 3/4] Wiki generation (opencode + DeepSeek Flash v4)...
[Phase 4/4] HTML docs (opencode + DeepSeek Flash v4)...

TASK TYPE          → AGENT               → MODEL
──────────────────────────────────────────────────────
Scan + git history → bash/python direct  → (no LLM)
Batch file analyze → python static parse → (no LLM — PRIMARY; opencode chỉ enrich)
Merge + validate   → python inline       → (no LLM)
Layers / tour      → Claude main thread  → Sonnet (never dispatch out)
Domain reasoning   → Claude main thread  → Sonnet (never dispatch out)
Wiki / HTML render → opencode            → opencode/deepseek-v4-flash-free

opencode run "$SPEC" --model opencode/deepseek-v4-flash-free < /dev/null \

---

update_phase_status() {
  local keyword="$1"
  local status="$2"
  [ -z "$DRAFT_FILE" ] && echo "[WARN] DRAFT_FILE unset" && return 0
  local f=$(echo "$DRAFT_FILE" | tr '\\' '/')
  [ ! -f "$f" ] && echo "[WARN] DRAFT_FILE not found: $f" && return 0
  perl -i -pe "s/(\Q$keyword\E.*?)\| (?:pending|in-progress|done)/\$1| $status/g if /\Q$keyword\E/" "$f" \
    || sed -i "s/\(.*$(echo "$keyword" | sed 's/[^^]/[&]/g').*\)| [a-z-]*/\1| $status/" "$f" \
    || echo "[WARN] status update failed for: $keyword"
}

undefined

---

DATE=$(date +%d%m%y)
PROJECT_SLUG=$(basename "$PROJECT_ROOT" | tr '[:upper:]' '[:lower:]' | tr ' ' '-')
DRAFT_FILE="$PROJECT_ROOT/llmwiki/wiki/draft/orca/${DATE}-onboard-${PROJECT_SLUG}.md"

⛔ The dispatch board AND the propose file content above MUST be printed via bash (visible in terminal) — restating them only in chat or only in the draft file is NOT sufficient. The user gates orchestration based on this board + propose. The draft's Agent Task Assignment rows must match the board (e.g. if Phase 1 is rerouted to opencode for >100 files, the draft must say opencode, not agy).

Ask for confirmation before continuing.

---

mkdir -p "$PROJECT_ROOT/.overstack/graph" "$PROJECT_ROOT/.overstack/onboard/tmp"
git -C "$PROJECT_ROOT" ls-files > "$PROJECT_ROOT/.overstack/onboard/tmp/files.txt"

undefined

undefined

Áp dụng: top churn → tag node `hot`; trong recent.txt → tag `recent`; cặp co-change ≥3 → edge `related` (weight 0.5); tour + ONBOARDING ưu tiên file `hot`; recent-subjects cho mục "What's being worked on".

opencode run "$BATCH_SPEC" --model opencode/deepseek-v4-flash-free < /dev/null

`BATCH_SPEC` (inject đủ context — DeepSeek không tự đọc gì ngoài danh sách được giao):

> Analyze these files in project <name> (<description>, languages: <langs>). For EACH file produce GraphNode `{id, type, name, filePath, summary (1-2 câu), tags[]}` and GraphEdges `{source, target, type, weight}` for imports/calls/configures/documents visible in file content. Read each listed file. Write ONLY valid JSON `{"nodes":[...], "edges":[...]}` to `.overstack/onboard/tmp/batch-<i>.json`. ID convention: `file:<relpath>`, `config:<relpath>`, `document:<relpath>`. Files: <list kèm line counts>

Tối đa 5 batch song song. Batch fail → retry 1 lần → fail nữa thì bỏ qua, ghi PHASE_WARNINGS (partial graph > no graph). opencode unavailable → Claude main thread tự analyze batch.

undefined

undefined

undefined

**Durability harness:** hook SessionStart `code_graph_keeper.py` (cài kèm install-harness.sh) tự re-register repo nếu rớt registry + cảnh báo repo chưa index. Fail-open, **no-op nếu project không dùng code-graph** — điều kiện là có `.graph-agent/index.db` **dùng được** (mở được + có bảng `symbols`/`files`), không phải chỉ có file: DB rỗng từng khiến keeper ghi nhầm registry và dập tắt luôn cảnh báo "chưa index". KHÔNG reindex per-edit (watcher đã lo, debounce 2s). Sau đó ghi 1 wiki concept page `concepts/code-graph-nav.md` (cách dùng tool + ví dụ caller trace) để team biết dùng.

> Freshness sau đó tự động: edit file → watcher reindex ~2s. Không cần reindex tay trừ khi clone mới hoặc đổi hàng loạt lúc server tắt.

---

{
  "domains": [
    {
      "id": "domain:order-management",
      "name": "Order Management",
      "flows": [
        {
          "id": "flow:create-order",
          "name": "Create Order",
          "steps": [
            { "order": 0.1, "id": "step:validate-input", "file": "src/orders/validator.ts", "line": 42 },
            { "order": 0.2, "id": "step:check-inventory", "file": "src/inventory/checker.ts", "line": 15 }
          ]
        }
      ]
    }
  ]
}

if [ "$RESUME_MODE" != "true" ] || [ "$PHASE2_STATUS" != "done" ]; then
  update_phase_status "Phase 2 —" "in-progress"
  # Claude main thread — no dispatch
  if [ "$UPDATE_MODE" = "true" ] && [ -n "$CHANGED_FILES" ]; then
    echo "[Phase 2] Update mode: re-enrich domain steps for changed files only"
    # Read existing domain-graph.json
    # Filter steps with filePath in CHANGED_FILES
    # Re-analyze those steps from ONBOARDING.md
    # Merge back into domain-graph.json (keep unchanged steps)
  else
    echo "[Phase 2] Full domain enrichment from ONBOARDING.md"
    # Read ONBOARDING.md + layers from knowledge-graph.json, write new domain-graph.json
  fi
  update_phase_status "Phase 2 —" "done"
fi

llmwiki/wiki/
├── index.md
├── concepts/          ← architecture.md, message-sync/flows, onboarding-tour.md (R5: KHÔNG tạo folder architecture/ hay tours/ — validator folder_structure chặn)
└── entities/          ← domain entities + project-structure.md

**Skip check:** `RESUME_MODE=true` + `PHASE3_STATUS=done` → skip to Phase 4.

```bash
if [ "$RESUME_MODE" != "true" ] || [ "$PHASE3_STATUS" != "done" ]; then
  update_phase_status "Phase 3 —" "in-progress"

  if [ "$UPDATE_MODE" = "true" ] && [ -n "$CHANGED_FILES" ]; then
    STALE_PAGES=$(grep -rl "$CHANGED_FILES" "$PROJECT_ROOT/llmwiki/wiki/" 2>/dev/null | tr '\n' ' ')
    if [ -n "$STALE_PAGES" ]; then
      echo "[Phase 3] Stale wiki pages: $STALE_PAGES"
      SPEC="Update these wiki pages based on changes in ONBOARDING.md: $STALE_PAGES
Changed source files: $CHANGED_FILES
Do NOT regenerate unchanged pages. Preserve existing content in unchanged pages."
    else
      echo "[Phase 3] No stale wiki pages — skipping"
      update_phase_status "Phase 3 —" "done"
    fi
  else
    SPEC="Generate wiki pages from .overstack/graph/ONBOARDING.md and .overstack/onboard/intermediate/domain-graph.json.
Create: llmwiki/wiki/index.md, llmwiki/wiki/concepts/*.md (architecture.md + flow pages + onboarding-tour.md),
llmwiki/wiki/entities/*.md (domain entities + project-structure.md).
R5: chỉ được ghi vào concepts/ hoặc entities/. R2: mọi trang có '## Origin'. R3: cập nhật index.md.
Use wikilink format [[page-name]]. Do NOT read knowledge-graph.json directly."
  fi

  opencode run "$SPEC" --model opencode/deepseek-v4-flash-free < /dev/null \
    || echo "[WARN] opencode unavailable — Claude main thread fallback for wiki"

  update_phase_status "Phase 3 —" "done"
fi

if [ "$RESUME_MODE" != "true" ] || [ "$PHASE4_STATUS" != "done" ]; then
  update_phase_status "Phase 4 —" "in-progress"

  # --- locate skeleton v2 ---
  SKELETON=$(ls ~/.agents/skills/orca-onboard/assets/docs-site-skeleton.html \
                ~/.claude/skills/orca-onboard/assets/docs-site-skeleton.html \
                "$PROJECT_ROOT/skills/orca-onboard/assets/docs-site-skeleton.html" 2>/dev/null | head -1)
  [ -z "$SKELETON" ] && echo "❌ Phase 4: skeleton v2 not found" && exit 1

  # --- detect Docker (multi-service → tab Docker; mono → docker:null, Modules:[]) ---
  DKFILE=$(ls "$PROJECT_ROOT"/docker-compose.y*ml "$PROJECT_ROOT"/compose.y*ml 2>/dev/null | head -1)
  N_SVC=0; [ -n "$DKFILE" ] && N_SVC=$(grep -cE '^  [a-zA-Z0-9_-]+:' "$DKFILE" 2>/dev/null || echo 0)
  echo "[Phase 4] skeleton=$SKELETON | compose=$DKFILE | services=$N_SVC"

  # --- STEP A: assemble ONBOARD_JSON (model emit JSON ONLY → file) ---
  JSON_OUT="$PROJECT_ROOT/.overstack/onboard/tmp/onboard.json"
  SPEC="Đọc .overstack/graph/ONBOARDING.md + .overstack/onboard/intermediate/domain-graph.json.
Phát ra MỘT object JSON (KHÔNG markdown, KHÔNG giải thích) theo ĐÚNG schema trong header của
$SKELETON, ghi vào $JSON_OUT. Yêu cầu chất lượng:
- project: name/subtitle/about thật; stack[] + versions[] từ manifest; stats[] (files, services, layers, tour steps).
- project.what = 2–4 câu LỜI THƯỜNG: dự án làm gì, cho ai, giải quyết vấn đề gì (không thuật ngữ nội bộ); project.how[] = 3–7 bước {t,d} kể luồng chạy đầu→cuối bằng lời người — hiện thành mục What & How NGAY SAU Overview.
- architecture.layers[] = layers thật; architecture.diagram.nodes[] (toạ độ trong ~760×rộng, rect≥70×30) + edges[] theo luồng.
- tour[] 5–15 bước, MỖI bước GIÀU: role(1-2 câu), file+line THẬT, in[]/out[], hot(churn), narr — KHÔNG 1–2 dòng.
- modules[] = mỗi container/image (đọc $DKFILE): name,img,meta(port/env/volume),life[[read|proc|write,desc]],arch. Repo mono ($N_SVC≤1) → modules:[].
- docker = {strategy, cmd[[text,c|p|]], table[[svc,img,cmd/port,deps]], order[]} nếu có compose; mono → docker:null."
  opencode run "$SPEC" --model opencode/deepseek-v4-flash-free < /dev/null 2>/dev/null \
    || echo "[Phase 4] opencode unavailable — Claude main thread tự assemble $JSON_OUT theo schema skeleton"
  # Nếu opencode treo/trống → Claude main thread đọc 2 nguồn trên, tự viết $JSON_OUT (reasoning OK ở đây).

  # --- STEP B: fill skeleton (python, no LLM) — thay {{TITLE}} + {{ONBOARD_JSON}} ---
  OUT="$PROJECT_ROOT/llmwiki/html/onboarding-${PROJECT_SLUG}.html"
  mkdir -p "$PROJECT_ROOT/llmwiki/html"
  python3 - "$SKELETON" "$JSON_OUT" "$OUT" <<'PY'
import json,sys,html
sk=open(sys.argv[1]).read(); data=json.load(open(sys.argv[2]))
name=(data.get("project") or {}).get("name","Project")
out=sk.replace("{{TITLE}}",html.escape(name)).replace("{{ONBOARD_JSON}}",json.dumps(data,ensure_ascii=False))
assert "{{ONBOARD_JSON}}" not in out and "{{TITLE}}" not in out, "token chưa thay hết"
open(sys.argv[3],"w").write(out); print("✅ filled →",sys.argv[3],len(out),"bytes")
PY

  ls "$OUT" && echo "✅ Phase 4 done" || echo "❌ Phase 4 FAIL: HTML not found"
  update_phase_status "Phase 4 —" "done"
fi

undefined

**After completion:**
```bash
lsof -ti :8765 >/dev/null 2>&1 || nohup npx serve -p 8765 > /tmp/serve.log 2>&1 &
echo "→ http://localhost:8765/llmwiki/html/onboarding-${PROJECT_SLUG}.html"

---
type: draft
title: DDMMYY-<ten>
status: proposed
tags: [orca-onboard, output-report]
timestamp: YYYY-MM-DD
---

**3. Update wiki index & log:**
- `llmwiki/wiki/index.md` — append: `| [DDMMYY-<ten>](draft/orca/DDMMYY-<ten>.md) | draft | YYYY-MM-DD |`
- `llmwiki/wiki/log.md` — append: `## YYYY-MM-DD — orca-onboard — <ten>`

**4. Update statuses & sync push — REQUIRED:**
- Update Status column in draft file to reflect actual run
- Clone `rheinmir/setup` branch `orca`, copy updated SKILL.md, push:
  ```bash
  git clone git@github.com:rheinmir/setup.git /tmp/rheinmir-setup-sync -b orca --depth 1
  cp ~/.agents/skills/orca-onboard/SKILL.md /tmp/rheinmir-setup-sync/skills/orca-onboard/SKILL.md
  cd /tmp/rheinmir-setup-sync
  git add .
  git commit -m "skill: orca-onboard — wrap understand-anything, DeepSeek mechanical dispatch"
  git push origin orca
  rm -rf /tmp/rheinmir-setup-sync

---
type: draft
status: proposed
tags: [orca-onboard, output-report]
proposed: YYYY-MM-DD
---

**3. Update wiki index & log:**
- `llmwiki/wiki/index.md` — append: `| [DDMMYY-<ten>](draft/orca/DDMMYY-<ten>.md) | draft | YYYY-MM-DD |`
- `llmwiki/wiki/log.md` — append: `## YYYY-MM-DD — orca-onboard — <ten>`

**4. Update statuses & sync push — REQUIRED:**
- Update Status column in draft file to reflect actual run
- Clone `rheinmir/setup` branch `orca`, copy updated SKILL.md, push:
  ```bash
  git clone git@github.com:rheinmir/setup.git /tmp/rheinmir-setup-sync -b orca --depth 1
  cp ~/.agents/skills/orca-onboard/SKILL.md /tmp/rheinmir-setup-sync/skills/orca-onboard/SKILL.md
  cd /tmp/rheinmir-setup-sync
  git add .
  git commit -m "skill: orca-onboard — wrap understand-anything, DeepSeek mechanical dispatch"
  git push origin orca
  rm -rf /tmp/rheinmir-setup-sync