@team-semicolon/semo-cli 4.12.0 → 4.15.0

package/dist/commands/service.js

@@ -0,0 +1,283 @@
+"use strict";
+/**
+ * semo service — 서비스 관리
+ *
+ * semo service migrate --domain {name}    — 특정 서비스 이식
+ * semo service migrate --all              — 미등록 전체 이식
+ * semo service migrate --all --dry-run    — 미리보기
+ * semo service list                       — 등록/미등록 서비스 목록
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerServiceCommands = registerServiceCommands;
+const chalk_1 = __importDefault(require("chalk"));
+const ora_1 = __importDefault(require("ora"));
+const database_1 = require("../database");
+const service_migrate_1 = require("../service-migrate");
+function registerServiceCommands(program) {
+    const service = program
+        .command("service")
+        .description("서비스 관리 — 이식, 목록 조회, 진단, 업데이트");
+    // ── semo service migrate ──
+    service
+        .command("migrate")
+        .description("기존 서비스를 services 테이블에 이식")
+        .option("--domain <name>", "특정 서비스 도메인")
+        .option("--all", "미등록 서비스 전체 이식")
+        .option("--dry-run", "미리보기 (DB 변경 없음)")
+        .action(async (options) => {
+        if (!options.domain && !options.all) {
+            console.log(chalk_1.default.yellow("--domain <name> 또는 --all 옵션이 필요합니다."));
+            await (0, database_1.closeConnection)();
+            return;
+        }
+        const pool = (0, database_1.getPool)();
+        const spinner = (0, ora_1.default)("서비스 이식 준비 중...").start();
+        try {
+            // 1. 미등록 서비스 조회
+            const unregistered = await (0, service_migrate_1.getUnregisteredServices)(pool);
+            if (unregistered.length === 0) {
+                spinner.succeed("모든 서비스가 이미 등록되어 있습니다.");
+                await (0, database_1.closeConnection)();
+                return;
+            }
+            // 2. 대상 필터링
+            let targets = unregistered;
+            if (options.domain) {
+                targets = unregistered.filter((s) => s.domain === options.domain);
+                if (targets.length === 0) {
+                    // 도메인이 있는데 미등록 목록에 없으면 → 이미 등록됨 또는 미존재
+                    const registered = await (0, service_migrate_1.getRegisteredServices)(pool);
+                    if (registered.includes(options.domain)) {
+                        spinner.info(`'${options.domain}'은(는) 이미 services에 등록되어 있습니다.`);
+                    }
+                    else {
+                        spinner.fail(`'${options.domain}'은(는) 온톨로지에 service 타입으로 등록되지 않았습니다.`);
+                    }
+                    await (0, database_1.closeConnection)();
+                    return;
+                }
+            }
+            spinner.text = `${targets.length}개 서비스 감사(audit) 중...`;
+            // 3. 각 서비스 audit
+            const results = [];
+            for (const svc of targets) {
+                const audit = await (0, service_migrate_1.auditServiceKBEntries)(pool, svc.domain, svc.description, svc.created_at);
+                if (options.dryRun) {
+                    results.push({ domain: svc.domain, action: "skipped", audit });
+                    continue;
+                }
+                // 4. INSERT
+                try {
+                    const row = (0, service_migrate_1.buildServiceProjectRow)(audit);
+                    // KB 엔트리 수 조회
+                    const countResult = await pool.query("SELECT COUNT(*)::int as cnt FROM semo.knowledge_base WHERE domain = $1", [svc.domain]);
+                    const kbEntryCount = countResult.rows[0]?.cnt ?? 0;
+                    const projectId = await (0, service_migrate_1.insertServiceProject)(pool, row);
+                    // 5. pm-summary projection 쓰기
+                    await (0, service_migrate_1.writePmSummaryToKB)(pool, svc.domain, projectId, row, kbEntryCount);
+                    results.push({
+                        domain: svc.domain,
+                        action: "created",
+                        projectId,
+                        audit,
+                    });
+                }
+                catch (err) {
+                    results.push({
+                        domain: svc.domain,
+                        action: "error",
+                        audit,
+                        error: err.message,
+                    });
+                }
+            }
+            spinner.stop();
+            // 6. 결과 리포트
+            if (options.dryRun) {
+                (0, service_migrate_1.printDryRunReport)(results);
+            }
+            else {
+                (0, service_migrate_1.printAuditReport)(results);
+            }
+        }
+        catch (err) {
+            spinner.fail(`이식 실패: ${err.message}`);
+        }
+        finally {
+            await (0, database_1.closeConnection)();
+        }
+    });
+    // ── semo service list ──
+    service
+        .command("list")
+        .description("서비스 목록 (등록/미등록 상태 포함)")
+        .action(async () => {
+        const pool = (0, database_1.getPool)();
+        try {
+            const registered = await (0, service_migrate_1.getRegisteredServices)(pool);
+            const unregistered = await (0, service_migrate_1.getUnregisteredServices)(pool);
+            console.log(chalk_1.default.cyan.bold("\n📋 서비스 목록\n"));
+            if (registered.length > 0) {
+                console.log(chalk_1.default.green(`  ✓ 등록됨 (${registered.length}개):`));
+                for (const d of registered.sort()) {
+                    console.log(chalk_1.default.gray(`    ${d}`));
+                }
+            }
+            if (unregistered.length > 0) {
+                console.log(chalk_1.default.yellow(`\n  ○ 미등록 (${unregistered.length}개):`));
+                for (const s of unregistered) {
+                    const desc = s.description ? chalk_1.default.gray(` — ${s.description.substring(0, 60)}`) : "";
+                    console.log(`    ${s.domain}${desc}`);
+                }
+            }
+            console.log();
+        }
+        finally {
+            await (0, database_1.closeConnection)();
+        }
+    });
+    // ── semo service diagnose ──
+    service
+        .command("diagnose")
+        .description("서비스 KB ↔ services 교차 진단")
+        .requiredOption("--domain <name>", "진단할 서비스 도메인")
+        .action(async (options) => {
+        const pool = (0, database_1.getPool)();
+        const spinner = (0, ora_1.default)("서비스 진단 중...").start();
+        try {
+            const result = await (0, service_migrate_1.diagnoseServiceStatus)(pool, options.domain);
+            spinner.stop();
+            console.log(chalk_1.default.cyan.bold(`\n🔍 서비스 진단: ${result.domain}\n`));
+            // KB 상태
+            if (result.kbEntryCount > 0) {
+                console.log(chalk_1.default.bold("  ┌─ KB ─────────────────────────────┐"));
+                console.log(`  │ 도메인: ${result.domain} (service)`);
+                console.log(`  │ KB 엔트리: ${result.kbEntryCount}개`);
+                console.log(`  │ 키: ${result.kbKeys.join(", ")}`);
+                if (result.missingRequired.length > 0) {
+                    console.log(chalk_1.default.yellow(`  │ 필수 키 누락: ${result.missingRequired.join(", ")}`));
+                }
+                console.log(chalk_1.default.bold("  └──────────────────────────────────┘\n"));
+            }
+            else {
+                console.log(chalk_1.default.yellow("  KB 도메인 없음\n"));
+            }
+            // services 상태
+            const sp = result.serviceProject;
+            if (sp) {
+                console.log(chalk_1.default.bold("  ┌─ services ───────────────────────┐"));
+                console.log(`  │ service_id: ${sp.service_id}`);
+                console.log(`  │ project_name: ${sp.project_name}`);
+                console.log(`  │ owner_name: ${sp.owner_name}`);
+                console.log(`  │ lifecycle: ${sp.lifecycle}`);
+                console.log(`  │ current_phase: ${sp.current_phase}`);
+                console.log(`  │ status: ${sp.status}`);
+                if (sp.launched_at) {
+                    console.log(`  │ launched_at: ${sp.launched_at}`);
+                }
+                console.log(chalk_1.default.bold("  └─────────────────────────────────┘\n"));
+            }
+            else {
+                console.log(chalk_1.default.yellow("  services 미등록\n"));
+            }
+            // 교차 검증
+            if (result.mismatches.length > 0) {
+                console.log(chalk_1.default.bold("  ┌─ 교차 검증 ──────────────────────┐"));
+                for (const m of result.mismatches) {
+                    console.log(chalk_1.default.yellow(`  │ ⚠️  ${m.field}: KB=${m.kbValue}, SP=${m.spValue}`));
+                    console.log(chalk_1.default.gray(`  │    기대값: ${m.expected}`));
+                }
+                console.log(chalk_1.default.bold("  └─────────────────────────────────┘\n"));
+            }
+            // Verdict
+            const verdictMap = {
+                healthy: chalk_1.default.green("✅ HEALTHY — 정합성 양호"),
+                mismatch: chalk_1.default.yellow(`⚠️  MISMATCH (${result.mismatches.length}건)`),
+                "kb-only": chalk_1.default.yellow("⚠️  KB-ONLY — services 미등록"),
+                "sp-only": chalk_1.default.red("❌ SP-ONLY — KB 도메인 없음 (비정상)"),
+                missing: chalk_1.default.red("❌ MISSING — KB, services 모두 없음"),
+            };
+            console.log(`  결과: ${verdictMap[result.verdict] ?? result.verdict}\n`);
+        }
+        catch (err) {
+            spinner.fail(`진단 실패: ${err.message}`);
+        }
+        finally {
+            await (0, database_1.closeConnection)();
+        }
+    });
+    // ── semo service update ──
+    service
+        .command("update")
+        .description("services 레코드 업데이트")
+        .requiredOption("--domain <name>", "대상 서비스 도메인")
+        .option("--status <status>", "서비스 상태 (active|paused|completed)")
+        .option("--lifecycle <lifecycle>", "라이프사이클 (build|ops|sunset)")
+        .option("--phase <number>", "현재 phase (0-9)", parseInt)
+        .option("--name <projectName>", "프로젝트명")
+        .option("--owner <ownerName>", "오너명")
+        .action(async (options) => {
+        const pool = (0, database_1.getPool)();
+        const spinner = (0, ora_1.default)("서비스 업데이트 중...").start();
+        try {
+            // Validate enum values
+            const validStatuses = ["active", "paused", "completed"];
+            if (options.status && !validStatuses.includes(options.status)) {
+                spinner.fail(`잘못된 status: '${options.status}' (허용: ${validStatuses.join(", ")})`);
+                await (0, database_1.closeConnection)();
+                return;
+            }
+            const validLifecycles = ["build", "ops", "sunset"];
+            if (options.lifecycle && !validLifecycles.includes(options.lifecycle)) {
+                spinner.fail(`잘못된 lifecycle: '${options.lifecycle}' (허용: ${validLifecycles.join(", ")})`);
+                await (0, database_1.closeConnection)();
+                return;
+            }
+            if (options.phase !== undefined && (options.phase < 0 || options.phase > 9)) {
+                spinner.fail(`잘못된 phase: ${options.phase} (허용: 0-9)`);
+                await (0, database_1.closeConnection)();
+                return;
+            }
+            const updates = {};
+            if (options.status)
+                updates.status = options.status;
+            if (options.lifecycle)
+                updates.lifecycle = options.lifecycle;
+            if (options.phase !== undefined)
+                updates.current_phase = options.phase;
+            if (options.name)
+                updates.project_name = options.name;
+            if (options.owner)
+                updates.owner_name = options.owner;
+            if (Object.keys(updates).length === 0) {
+                spinner.info("업데이트할 항목이 없습니다. --status, --lifecycle, --phase 등을 지정하세요.");
+                await (0, database_1.closeConnection)();
+                return;
+            }
+            const result = await (0, service_migrate_1.updateServiceProject)(pool, options.domain, updates);
+            if (!result) {
+                spinner.fail(`'${options.domain}'은(는) services에 등록되지 않았습니다.`);
+                await (0, database_1.closeConnection)();
+                return;
+            }
+            spinner.succeed(`'${options.domain}' 업데이트 완료`);
+            console.log(chalk_1.default.gray(`  project_name: ${result.project_name}\n` +
+                `  owner_name: ${result.owner_name}\n` +
+                `  lifecycle: ${result.lifecycle}\n` +
+                `  current_phase: ${result.current_phase}\n` +
+                `  status: ${result.status}\n` +
+                `  launched_at: ${result.launched_at ?? "(없음)"}\n` +
+                `  updated_at: ${result.updated_at}`));
+            console.log();
+        }
+        catch (err) {
+            spinner.fail(`업데이트 실패: ${err.message}`);
+        }
+        finally {
+            await (0, database_1.closeConnection)();
+        }
+    });
+}

package/dist/commands/sessions.js

@@ -492,4 +492,160 @@ function registerSessionsCommands(program) {
             await (0, database_1.closeConnection)();
         }
     });
+    // ── semo sessions digest ──────────────────────────────────────────────────
+    sessionsCmd
+        .command("digest")
+        .description("세션 transcript에서 미기록 의사결정 추출")
+        .option("--transcript <path>", "transcript JSONL 파일 경로")
+        .option("--session-dir <dir>", "세션 디렉토리 (최신 transcript 자동 선택)")
+        .option("--hours <n>", "최근 N시간 내 transcript만 (session-dir 사용 시)", "24")
+        .option("--format <type>", "출력 형식 (table|json)", "table")
+        .option("--output <path>", "결과를 파일로 출력")
+        .action(async (options) => {
+        // transcript 파일 찾기
+        let transcripts = [];
+        if (options.transcript) {
+            if (!fs.existsSync(options.transcript)) {
+                console.error(chalk_1.default.red(`❌ 파일 없음: ${options.transcript}`));
+                process.exit(1);
+            }
+            transcripts = [options.transcript];
+        }
+        else if (options.sessionDir) {
+            const dir = options.sessionDir;
+            if (!fs.existsSync(dir)) {
+                console.error(chalk_1.default.red(`❌ 디렉토리 없음: ${dir}`));
+                process.exit(1);
+            }
+            const hours = parseInt(options.hours) || 24;
+            const cutoff = Date.now() - hours * 60 * 60 * 1000;
+            const files = fs.readdirSync(dir)
+                .filter(f => f.endsWith(".jsonl"))
+                .map(f => ({ name: f, path: path.join(dir, f), mtime: fs.statSync(path.join(dir, f)).mtimeMs }))
+                .filter(f => f.mtime > cutoff)
+                .sort((a, b) => b.mtime - a.mtime);
+            transcripts = files.map(f => f.path);
+        }
+        else {
+            // 기본: 현재 semo 프로젝트의 세션 디렉토리
+            const semoSessionDir = path.join(os.homedir(), ".claude", "projects", "-Users-reus-Desktop-Sources-semicolon-projects-semo");
+            if (fs.existsSync(semoSessionDir)) {
+                const hours = parseInt(options.hours) || 24;
+                const cutoff = Date.now() - hours * 60 * 60 * 1000;
+                const files = fs.readdirSync(semoSessionDir)
+                    .filter(f => f.endsWith(".jsonl"))
+                    .map(f => ({ name: f, path: path.join(semoSessionDir, f), mtime: fs.statSync(path.join(semoSessionDir, f)).mtimeMs }))
+                    .filter(f => f.mtime > cutoff)
+                    .sort((a, b) => b.mtime - a.mtime);
+                transcripts = files.map(f => f.path);
+            }
+        }
+        if (transcripts.length === 0) {
+            console.log(chalk_1.default.yellow("⚠ 분석할 transcript가 없습니다."));
+            process.exit(0);
+        }
+        // 의사결정 키워드 패턴
+        const decisionRe = /(?:도입했|폐기했|전환했|적용했|배포했|마이그레이션|변경했|합의했|결정했|도입합니다|폐기합니다|전환합니다|적용합니다|배포합니다|도입 완료|폐기 완료|전환 완료|적용 완료|배포 완료|표준화했|통합했|분리했|추가했|제거했|Phase \d+ 완료|설정을? 변경|규칙을? 변경|프로세스를? 변경|NON-NEGOTIABLE|신규 생성|전체 배포)/g;
+        const kbRecordRe = /KB 기록:|semo kb upsert|KB upsert 완료|답변근거: KB/;
+        const candidates = [];
+        for (const tPath of transcripts) {
+            const lines = fs.readFileSync(tPath, "utf-8").split("\n").filter(l => l.trim());
+            let lastKbUpsertLine = -1;
+            for (let i = 0; i < lines.length; i++) {
+                try {
+                    const entry = JSON.parse(lines[i]);
+                    const msg = entry.message ?? entry;
+                    // KB upsert tool call 추적
+                    if (msg.role === "assistant") {
+                        const content = msg.content ?? [];
+                        for (const block of content) {
+                            if (block?.type === "tool_use") {
+                                const inp = JSON.stringify(block.input ?? {});
+                                if (inp.includes("kb upsert") || inp.includes("kb_upsert")) {
+                                    lastKbUpsertLine = i;
+                                }
+                            }
+                        }
+                    }
+                    // tool result에서 upsert 완료 추적
+                    if (msg.role === "tool") {
+                        const content = Array.isArray(msg.content)
+                            ? msg.content.map((c) => typeof c === "string" ? c : c?.text ?? "").join(" ")
+                            : String(msg.content ?? "");
+                        if (content.includes("upsert 완료")) {
+                            lastKbUpsertLine = i;
+                        }
+                    }
+                    // assistant 텍스트에서 의사결정 키워드 탐지
+                    if (msg.role === "assistant") {
+                        const content = msg.content ?? [];
+                        for (const block of content) {
+                            if (block?.type !== "text")
+                                continue;
+                            let text = block.text ?? "";
+                            // 코드 블록 제거
+                            text = text.replace(/```[\s\S]*?```/g, "").replace(/`[^`\n]+`/g, "");
+                            const matches = text.match(decisionRe);
+                            if (matches && matches.length > 0) {
+                                const hasKbInText = kbRecordRe.test(text);
+                                // 같은 턴(±5줄 이내)에 KB upsert가 있었는지
+                                const hasKbNearby = Math.abs(i - lastKbUpsertLine) <= 10;
+                                candidates.push({
+                                    file: path.basename(tPath),
+                                    lineNum: i,
+                                    text: text.slice(0, 200).replace(/\n/g, " "),
+                                    keywords: [...new Set(matches)].slice(0, 3),
+                                    hasKbRecord: hasKbInText || hasKbNearby,
+                                    timestamp: entry.timestamp ? new Date(entry.timestamp).toLocaleString("ko-KR") : undefined,
+                                });
+                            }
+                        }
+                    }
+                }
+                catch { /* skip */ }
+            }
+        }
+        // 미기록 건만 필터
+        const unrecorded = candidates.filter(c => !c.hasKbRecord);
+        const recorded = candidates.filter(c => c.hasKbRecord);
+        if (options.format === "json") {
+            const result = { total: candidates.length, recorded: recorded.length, unrecorded: unrecorded.length, items: unrecorded };
+            const out = JSON.stringify(result, null, 2);
+            if (options.output) {
+                fs.writeFileSync(options.output, out);
+                console.log(chalk_1.default.green(`✔ 결과 저장: ${options.output}`));
+            }
+            else {
+                console.log(out);
+            }
+        }
+        else {
+            console.log(chalk_1.default.cyan.bold(`\n📋 세션 의사결정 다이제스트\n`));
+            console.log(chalk_1.default.gray(`  transcript: ${transcripts.length}개 | 총 감지: ${candidates.length}건 | 기록됨: ${recorded.length}건 | 미기록: ${unrecorded.length}건\n`));
+            if (unrecorded.length === 0) {
+                console.log(chalk_1.default.green("  ✅ 미기록 의사결정 없음\n"));
+            }
+            else {
+                console.log(chalk_1.default.yellow.bold("  ⚠ 미기록 의사결정:\n"));
+                for (const c of unrecorded) {
+                    console.log(chalk_1.default.yellow(`  [${c.file}:${c.lineNum}]`) + chalk_1.default.gray(c.timestamp ? ` ${c.timestamp}` : ""));
+                    console.log(chalk_1.default.white(`    키워드: ${c.keywords.join(", ")}`));
+                    console.log(chalk_1.default.gray(`    "${c.text.slice(0, 120)}..."\n`));
+                }
+            }
+            if (options.output) {
+                const lines = [`# 세션 의사결정 다이제스트`, ``, `총 감지: ${candidates.length}건 | 기록됨: ${recorded.length}건 | 미기록: ${unrecorded.length}건`, ``];
+                if (unrecorded.length > 0) {
+                    lines.push(`## 미기록 의사결정`, ``);
+                    for (const c of unrecorded) {
+                        lines.push(`- **[${c.file}:${c.lineNum}]** ${c.keywords.join(", ")}`);
+                        lines.push(`  > ${c.text.slice(0, 150)}...`);
+                        lines.push(``);
+                    }
+                }
+                fs.writeFileSync(options.output, lines.join("\n"));
+                console.log(chalk_1.default.green(`✔ 결과 저장: ${options.output}`));
+            }
+        }
+    });
 }

package/dist/commands/skill-sync.d.ts

@@ -8,12 +8,13 @@
  * 스킬 이름은 flat (예: 'kb-manager'), metadata.bot_ids 배열로 봇 매핑.
  * 동일 스킬명이 여러 봇에 존재하면 bot_ids를 머지.
  */
-import { Pool, PoolClient } from "pg";
+import { Pool, PoolClient } from 'pg';
 export interface ScannedSkill {
     name: string;
     prompt: string;
     package: string;
     botId: string;
+    referenceFiles?: Record<string, string>;
 }
 export interface SkillSyncResult {
     botSpecific: number;

package/dist/commands/skill-sync.js

@@ -49,16 +49,16 @@ exports.syncSkillsToDB = syncSkillsToDB;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 function scanSkills(arg) {
-    if (typeof arg === "string") {
+    if (typeof arg === 'string') {
         return scanSkillsLegacy(arg);
     }
     return scanSkillsV2(arg);
 }
 function scanSkillsV2(botIds) {
     const skills = [];
-    const home = process.env.HOME || "/Users/reus";
+    const home = process.env.HOME || '/Users/reus';
     for (const botId of botIds) {
-        const skillsDir = path.join(home, `.openclaw-${botId}`, "workspace", "skills");
+        const skillsDir = path.join(home, `.openclaw-${botId}`, 'workspace', 'skills');
         if (!fs.existsSync(skillsDir))
             continue;
         let skillEntries;
@@ -71,22 +71,49 @@ function scanSkillsV2(botIds) {
         for (const skillEntry of skillEntries) {
             if (!skillEntry.isDirectory())
                 continue;
-            if (skillEntry.name.endsWith(".skill"))
+            if (skillEntry.name.endsWith('.skill'))
                 continue;
-            if (skillEntry.name.startsWith("_") || skillEntry.name.startsWith("."))
+            if (skillEntry.name.startsWith('_') || skillEntry.name.startsWith('.'))
                 continue;
-            const skillMdPath = path.join(skillsDir, skillEntry.name, "SKILL.md");
+            const skillMdPath = path.join(skillsDir, skillEntry.name, 'SKILL.md');
             if (!fs.existsSync(skillMdPath))
                 continue;
             try {
+                // Scan references/ subdirectory
+                let referenceFiles;
+                const refsDir = path.join(skillsDir, skillEntry.name, 'references');
+                if (fs.existsSync(refsDir)) {
+                    try {
+                        const refs = {};
+                        for (const refFile of fs.readdirSync(refsDir)) {
+                            const refPath = path.join(refsDir, refFile);
+                            try {
+                                if (!fs.statSync(refPath).isFile())
+                                    continue;
+                                refs[refFile] = fs.readFileSync(refPath, 'utf-8');
+                            }
+                            catch {
+                                /* skip unreadable */
+                            }
+                        }
+                        if (Object.keys(refs).length > 0)
+                            referenceFiles = refs;
+                    }
+                    catch {
+                        /* skip unreadable refs dir */
+                    }
+                }
                 skills.push({
                     name: skillEntry.name,
-                    prompt: fs.readFileSync(skillMdPath, "utf-8"),
-                    package: "openclaw",
+                    prompt: fs.readFileSync(skillMdPath, 'utf-8'),
+                    package: 'openclaw',
                     botId,
+                    referenceFiles,
                 });
             }
-            catch { /* skip unreadable */ }
+            catch {
+                /* skip unreadable */
+            }
         }
     }
     return skills;
@@ -94,34 +121,61 @@ function scanSkillsV2(botIds) {
 /** Legacy: semo-system/bot-workspaces 에서 스캔 (하위호환) */
 function scanSkillsLegacy(semoSystemDir) {
     const skills = [];
-    const workspacesDir = path.join(semoSystemDir, "bot-workspaces");
+    const workspacesDir = path.join(semoSystemDir, 'bot-workspaces');
     if (!fs.existsSync(workspacesDir))
         return skills;
     const botEntries = fs.readdirSync(workspacesDir, { withFileTypes: true });
     for (const botEntry of botEntries) {
         if (!botEntry.isDirectory())
             continue;
-        const skillsDir = path.join(workspacesDir, botEntry.name, "skills");
+        const skillsDir = path.join(workspacesDir, botEntry.name, 'skills');
         if (!fs.existsSync(skillsDir))
             continue;
         const skillEntries = fs.readdirSync(skillsDir, { withFileTypes: true });
         for (const skillEntry of skillEntries) {
             if (!skillEntry.isDirectory())
                 continue;
-            if (skillEntry.name.endsWith(".skill"))
+            if (skillEntry.name.endsWith('.skill'))
                 continue;
-            const skillMdPath = path.join(skillsDir, skillEntry.name, "SKILL.md");
+            const skillMdPath = path.join(skillsDir, skillEntry.name, 'SKILL.md');
             if (!fs.existsSync(skillMdPath))
                 continue;
             try {
+                // Scan references/ subdirectory
+                let referenceFiles;
+                const refsDir = path.join(skillsDir, skillEntry.name, 'references');
+                if (fs.existsSync(refsDir)) {
+                    try {
+                        const refs = {};
+                        for (const refFile of fs.readdirSync(refsDir)) {
+                            const refPath = path.join(refsDir, refFile);
+                            try {
+                                if (!fs.statSync(refPath).isFile())
+                                    continue;
+                                refs[refFile] = fs.readFileSync(refPath, 'utf-8');
+                            }
+                            catch {
+                                /* skip unreadable */
+                            }
+                        }
+                        if (Object.keys(refs).length > 0)
+                            referenceFiles = refs;
+                    }
+                    catch {
+                        /* skip unreadable refs dir */
+                    }
+                }
                 skills.push({
                     name: skillEntry.name,
-                    prompt: fs.readFileSync(skillMdPath, "utf-8"),
-                    package: "openclaw",
+                    prompt: fs.readFileSync(skillMdPath, 'utf-8'),
+                    package: 'openclaw',
                     botId: botEntry.name,
+                    referenceFiles,
                 });
             }
-            catch { /* skip unreadable */ }
+            catch {
+                /* skip unreadable */
+            }
         }
     }
     return skills;
@@ -131,28 +185,32 @@ function scanSkillsLegacy(semoSystemDir) {
  */
 async function getBotIds(pool) {
     try {
-        const result = await pool.query("SELECT bot_id FROM semo.bot_status ORDER BY bot_id");
+        const result = await pool.query('SELECT bot_id FROM semo.bot_status ORDER BY bot_id');
         if (result.rows.length > 0) {
             return result.rows.map((r) => r.bot_id);
         }
     }
-    catch { /* fallback to local scan */ }
+    catch {
+        /* fallback to local scan */
+    }
     // Fallback: scan ~/.openclaw-*/workspace/ directories
-    const home = process.env.HOME || "/Users/reus";
+    const home = process.env.HOME || '/Users/reus';
     const botIds = [];
     try {
         const entries = fs.readdirSync(home);
         for (const entry of entries) {
             const match = entry.match(/^\.openclaw-(.+)$/);
             if (match) {
-                const wsDir = path.join(home, entry, "workspace");
+                const wsDir = path.join(home, entry, 'workspace');
                 if (fs.existsSync(wsDir)) {
                     botIds.push(match[1]);
                 }
             }
         }
     }
-    catch { /* skip */ }
+    catch {
+        /* skip */
+    }
     return botIds.sort();
 }
 /**
@@ -163,13 +221,20 @@ async function syncSkillsToDB(client, pool) {
     const botIds = await getBotIds(pool);
     const skills = scanSkills(botIds);
     for (const skill of skills) {
+        const metadata = { bot_ids: [skill.botId] };
+        if (skill.referenceFiles)
+            metadata.reference_files = skill.referenceFiles;
         await client.query(`INSERT INTO semo.skill_definitions (name, prompt, package, metadata, is_active, office_id)
        VALUES ($1, $2, $3, $4, true, NULL)
        ON CONFLICT (name, office_id) DO UPDATE SET
          prompt = EXCLUDED.prompt,
          package = EXCLUDED.package,
          metadata = jsonb_set(
-           skill_definitions.metadata,
+           CASE
+             WHEN EXCLUDED.metadata ? 'reference_files'
+             THEN jsonb_set(skill_definitions.metadata, '{reference_files}', EXCLUDED.metadata->'reference_files')
+             ELSE skill_definitions.metadata
+           END,
            '{bot_ids}',
            (SELECT jsonb_agg(DISTINCT v)
             FROM jsonb_array_elements(
@@ -177,7 +242,7 @@ async function syncSkillsToDB(client, pool) {
               COALESCE(EXCLUDED.metadata->'bot_ids', '[]'::jsonb)
             ) AS v)
          ),
-         updated_at = NOW()`, [skill.name, skill.prompt, skill.package, JSON.stringify({ bot_ids: [skill.botId] })]);
+         updated_at = NOW()`, [skill.name, skill.prompt, skill.package, JSON.stringify(metadata)]);
     }
     return {
         botSpecific: skills.length,