agentlas 0.9.10 → 1.0.2

package/engine/oberon/manifest.cjs

@@ -0,0 +1,164 @@
+"use strict";
+/*
+ * oberon/manifest — 렌더 매니페스트 scaffold + 원자적 쓰기.
+ * v1 §12243-12358 (oberonSampleTitles / writeOberonManifestCli / oberonScaffold) 충실 포팅.
+ *
+ * 사용 흐름 (v1 헤더 주석 그대로):
+ *   agentlas oberon scaffold my.json      → 편집 가능한 렌더 매니페스트 생성
+ *   agentlas oberon render my.json        → 헤드리스 렌더 스폰 + 진행률 스트리밍
+ * 프롬프트는 직접 채우거나 `agentlas run oberon-film-studio "<브리프>"`로 에이전트가
+ * 채운다 (OpenMontage "어시스턴트=오케스트레이터" 스킴).
+ */
+const fs = require("node:fs");
+const path = require("node:path");
+const crypto = require("node:crypto");
+const { fail, parseFlags } = require("./common.cjs");
+
+// scaffold 기본 타이포 프리셋 (v1 oberonSampleTitles).
+// 한국어 본문/자막은 CJK 폰트를 강제한다 — 비-CJK 폰트로 한글을 태우면 두부(tofu)가 뜬다.
+function oberonSampleTitles(title) {
+  const koStyle = (over) => ({
+    fontName: "Pretendard",
+    fontStack: '"Pretendard", system-ui, sans-serif',
+    fontCategory: "humanist_sans",
+    cjk: true,
+    sizePct: 5,
+    weight: 700,
+    tracking: 0,
+    case: "none",
+    position: "center",
+    fill: "#FFFFFF",
+    safeAreaPct: 10,
+    ...over,
+  });
+  return {
+    aspectRatio: "16:9",
+    titleCard: { kind: "title", lines: [title], style: koStyle({ sizePct: 9, outline: { color: "rgba(0,0,0,0.45)", widthPx: 2 } }), bg: "#000000", durationSec: 2 },
+    endCard: { kind: "end_card", lines: ["AGENTLAS"], style: koStyle({ sizePct: 7, cjk: false }), bg: "#0A0A0A", durationSec: 1.5 },
+    lowerThirds: [],
+    subtitles: [],
+    subtitleStyle: koStyle({ sizePct: 4.6, weight: 600, position: "lower_center", boxBg: "rgba(0,0,0,0.34)", outline: { color: "rgba(0,0,0,0.9)", widthPx: 3 }, safeAreaPct: 8 }),
+    rationale: "scaffold 기본 타이포 — 한국어 본문/자막은 CJK 폰트 강제",
+  };
+}
+
+/*
+ * 원자적 no-clobber 매니페스트 쓰기 (v1 writeOberonManifestCli).
+ * 비자명 제약 — 전부 v1에서 실사고/보안 검토로 굳은 규칙:
+ *  - 심볼릭 링크를 통해 쓰지 않는다 (링크 타깃 오염 방지).
+ *  - 일반 파일이 아니면 거부.
+ *  - overwrite 아님 + 존재 → EXISTS 에러 (사용자 편집본을 조용히 덮지 않는다).
+ *  - tmp에 wx(0o600)로 쓰고 fsync 후:
+ *      overwrite → rename(2)
+ *      신규      → link(2). link(2)는 원자적 no-clobber publish다. 우리 lstat 이후
+ *                  다른 writer가 타깃을 만들었으면 EEXIST가 그 파일을 보존한다.
+ */
+function writeOberonManifest(outPath, manifest, options = {}) {
+  const overwrite = options.overwrite === true;
+  let existing = null;
+  try { existing = fs.lstatSync(outPath); } catch (error) {
+    if (!error || error.code !== "ENOENT") throw error;
+  }
+  if (existing && existing.isSymbolicLink()) {
+    const error = new Error(`Refusing to write through a symbolic link: ${outPath}`);
+    error.code = "AGENTLAS_OBERON_SYMLINK";
+    throw error;
+  }
+  if (existing && !existing.isFile()) {
+    const error = new Error(`Manifest target is not a regular file: ${outPath}`);
+    error.code = "AGENTLAS_OBERON_NOT_FILE";
+    throw error;
+  }
+  if (existing && !overwrite) {
+    const error = new Error(`Manifest already exists: ${outPath}`);
+    error.code = "AGENTLAS_OBERON_EXISTS";
+    throw error;
+  }
+
+  const dir = path.dirname(outPath);
+  const tmp = path.join(dir, `.${path.basename(outPath)}.${process.pid}.${crypto.randomBytes(6).toString("hex")}.tmp`);
+  let fd;
+  try {
+    fd = fs.openSync(tmp, "wx", 0o600);
+    fs.writeFileSync(fd, JSON.stringify(manifest, null, 2) + "\n", "utf8");
+    fs.fsyncSync(fd);
+    fs.closeSync(fd);
+    fd = null;
+    try { fs.chmodSync(tmp, 0o644); } catch { /* win32 */ }
+    if (overwrite) {
+      fs.renameSync(tmp, outPath);
+    } else {
+      // link(2) is an atomic no-clobber publish. If another writer created the
+      // target after our lstat, EEXIST preserves that file.
+      fs.linkSync(tmp, outPath);
+      fs.unlinkSync(tmp);
+    }
+  } finally {
+    if (fd != null) {
+      try { fs.closeSync(fd); } catch { /* ignore */ }
+    }
+    try { fs.unlinkSync(tmp); } catch { /* already published or never created */ }
+  }
+}
+
+// scaffold 매니페스트 본문 구성 (v1 oberonScaffold의 순수 부분 분리 — 테스트 용이성).
+function buildScaffoldManifest({ title, aspect, shotCount, provider, model, resolution, withTitles }) {
+  const shots = Array.from({ length: shotCount }, (_, i) => ({
+    shotId: `SH_${String(i + 1).padStart(3, "0")}`,
+    index: i,
+    durationSec: 4,
+    aspectRatio: aspect,
+    providerId: "google-veo",
+    providerMode: "text_to_video",
+    prompt: `((샷 ${i + 1} 프롬프트를 여기에 — 카메라/피사체/조명/무드. 'agentlas run oberon-film-studio' 로 에이전트가 채우게 할 수 있다.))`,
+    negativePrompt: "low quality, blurry, distorted text, watermark",
+  }));
+  const manifest = {
+    productionId: `oberon-${Date.now().toString(36)}`,
+    title,
+    aspectRatio: aspect,
+    maxShots: shotCount,
+    takesPerShot: 1,
+    provider,
+    model,
+    resolution,
+    shots,
+  };
+  if (withTitles) manifest.titles = oberonSampleTitles(title);
+  return manifest;
+}
+
+// `oberon scaffold [out.json] [--title T] [--aspect 16:9] [--shots N] [--titles] [--overwrite]`
+function scaffold(io, args) {
+  const { flags, rest } = parseFlags(args);
+  const outPath = path.resolve(rest[0] || "oberon-manifest.json");
+  const title = flags.title || "My Oberon Film";
+  const aspect = flags.aspect || "16:9";
+  // v1 계약: 샷 수는 1..12로 클램프, 기본 2 (Veo 폴링 비용 상한).
+  const shotCount = Math.max(1, Math.min(Number(flags.shots) || 2, 12));
+  const manifest = buildScaffoldManifest({
+    title,
+    aspect,
+    shotCount,
+    provider: flags.provider || "google-gemini-veo",
+    model: flags.model || "veo-3.1-lite-generate-001",
+    resolution: flags.resolution || "720p",
+    withTitles: !!flags.titles,
+  });
+  try {
+    writeOberonManifest(outPath, manifest, { overwrite: !!flags.overwrite });
+  } catch (error) {
+    if (error && error.code === "AGENTLAS_OBERON_EXISTS") {
+      fail(`Manifest already exists; it was not changed. Re-run with --overwrite to replace it: ${outPath}`, error.code);
+    }
+    fail((error && error.message) || String(error), error && error.code);
+  }
+  io.out(`✓ Manifest created: ${outPath}`);
+  io.out(`  · ${shotCount} shots · ${aspect} · ${manifest.provider}`);
+  io.out(`  · fill prompts, then run: agentlas oberon render ${path.basename(outPath)}`);
+  io.out(`  · or use an agent: agentlas run oberon-film-studio "30-second fragrance ad trailer"`);
+  if (!flags.titles) io.out(`  · use --titles to include title/subtitle burn-in samples`);
+  return 0;
+}
+
+module.exports = { oberonSampleTitles, writeOberonManifest, buildScaffoldManifest, scaffold };

package/engine/oberon/outputs.cjs

@@ -0,0 +1,70 @@
+"use strict";
+/*
+ * oberon/outputs — 렌더 산출물 조회/열기.
+ * v1 §12494-12540 (oberonList / oberonOpen) 충실 포팅.
+ * 산출물 홈은 <userData>/oberon/ — Desktop Oberon 렌더 잡과 같은 위치를 공유한다.
+ */
+const fs = require("node:fs");
+const path = require("node:path");
+const { spawn } = require("node:child_process");
+const { userDataDir } = require("../core/paths.cjs");
+const { fail } = require("./common.cjs");
+
+function oberonHome() {
+  return path.join(userDataDir(), "oberon");
+}
+
+// `oberon list` — 최근 렌더 산출물 15개 (mtime 내림차순).
+function list(io) {
+  const dir = oberonHome();
+  if (!fs.existsSync(dir)) {
+    io.out("No render outputs yet. Start with agentlas oberon scaffold my.json.");
+    return 0;
+  }
+  const entries = fs
+    .readdirSync(dir, { withFileTypes: true })
+    .filter((d) => d.isDirectory())
+    .map((d) => {
+      const full = path.join(dir, d.name);
+      let mtime = 0;
+      try {
+        mtime = fs.statSync(full).mtimeMs;
+      } catch {}
+      const files = (() => {
+        try {
+          return fs.readdirSync(full);
+        } catch {
+          return [];
+        }
+      })();
+      return { name: d.name, full, mtime, files };
+    })
+    .sort((a, b) => b.mtime - a.mtime)
+    .slice(0, 15);
+  if (!entries.length) {
+    io.out("No render outputs yet.");
+    return 0;
+  }
+  io.out(`Recent Oberon renders (${dir}):\n`);
+  for (const e of entries) {
+    // master/titled 최종본만 요약에 노출 (중간 클립·로그 숨김) — v1 필터 그대로.
+    const masters = e.files.filter((f) => /master|titled/.test(f) && /\.(mp4|mov)$/.test(f));
+    const when = e.mtime ? new Date(e.mtime).toISOString().slice(0, 16).replace("T", " ") : "";
+    io.out(`  ${when}  ${e.name}`);
+    if (masters.length) io.out(`            ${masters.join(", ")}`);
+  }
+  io.out(`\nOpen the folder with: agentlas oberon open`);
+  return 0;
+}
+
+// `oberon open [path]` — 산출물 폴더를 OS 파일 매니저로 연다.
+function open(io, args) {
+  const target = args[0] ? path.resolve(args[0]) : oberonHome();
+  if (!fs.existsSync(target)) fail(`Path not found: ${target}`);
+  const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "explorer" : "xdg-open";
+  spawn(opener, [target], { detached: true, stdio: "ignore" }).unref();
+  io.out(`Opening folder: ${target}`);
+  return 0;
+}
+
+module.exports = { list, open, oberonHome };

package/engine/oberon/render.cjs

@@ -0,0 +1,164 @@
+"use strict";
+/*
+ * oberon/render — 헤드리스 렌더 스폰 + 진행률 스트리밍.
+ * v1 §12360-12471 (oberonRender / oberonRenderLine) 충실 포팅.
+ *
+ * 렌더 경로가 실제로 필요로 하는 것 (v1 계약):
+ *  - <packageRoot>/scripts/render-oberon-live-request.cjs  (헤드리스 렌더 진입 스크립트)
+ *  - <packageRoot>/dist/electron/oberon/render.js          (Electron 렌더 빌드 산출물)
+ *  둘 다 Desktop 쪽 Electron 빌드 산출물이며 터미널 npm 패키지에는 실려 있지 않다.
+ *  v1도 fs.existsSync 검사 후 정직하게 실패했다 — 렌더를 가짜로 성공시키지 않는다.
+ *
+ * v2 seam: 렌더 진입점 해석과 spawn은 deps 파라미터로 주입 가능하다.
+ *   deps.resolveRenderEntry() → { script, builtRender }
+ *   deps.spawn / deps.execPath / deps.stdout / deps.stderr
+ *  테스트는 가짜 렌더 스크립트를 주입해 프로토콜(POLL/FILE/DELIVERY 라인)을 검증하고,
+ *  실제 배포에서는 진입점이 없으면 v1과 동일한 메시지로 정직 정지한다.
+ */
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const { spawn } = require("node:child_process");
+const { packageRoot } = require("../core/paths.cjs");
+const { fail, parseFlags, oberonBar, oberonBytes, slugifyOberon } = require("./common.cjs");
+
+// v1 oberonRepoRoot() = engine/의 부모 = 패키지 루트. v2에서는 core/paths가 정본.
+function defaultRenderEntry() {
+  const root = packageRoot();
+  return {
+    script: path.join(root, "scripts", "render-oberon-live-request.cjs"),
+    builtRender: path.join(root, "dist", "electron", "oberon", "render.js"),
+  };
+}
+
+/*
+ * 렌더 자식의 stdout 프로토콜 한 줄 처리 (v1 oberonRenderLine).
+ *   POLL status= phase= clips= percent=   → \r 진행률 바 갱신
+ *   FILE kind= name= bytes=               → 산출물 수집 (titled 요약용)
+ *   DELIVERY kind= name= path= bytes=     → 딜리버리 복사 알림
+ *   WARNINGS=                             → 경고 표시
+ *   JOB= / OUT_DIR= / *=present|missing   → 내부 추적/키 존재 점검 라인 — 숨김
+ */
+function oberonRenderLine(line, files, io) {
+  let m;
+  if ((m = line.match(/^POLL status=(\S+) phase=(\S+) clips=(\S+) percent=(\d+)/))) {
+    const [, status, phase, clips, pct] = m;
+    const bar = oberonBar(Number(pct));
+    io.write(`\r⏳ ${bar} ${String(pct).padStart(3)}%  ${phase}  clips ${clips}   `);
+    if (status === "succeeded") io.write("\n");
+    return;
+  }
+  if ((m = line.match(/^FILE kind=(\S+) name=(\S+) bytes=(\d+)/))) {
+    files.push({ kind: m[1], name: m[2], bytes: Number(m[3]) });
+    return;
+  }
+  if ((m = line.match(/^DELIVERY kind=(\S+) name=(\S+) path=(\S+) bytes=(\d+)/))) {
+    io.out(`  📦 ${m[1].padEnd(11)} ${m[2]}  (${oberonBytes(Number(m[4]))})`);
+    return;
+  }
+  if (line.startsWith("WARNINGS=")) {
+    io.out(`  ⚠ ${line.slice("WARNINGS=".length)}`);
+    return;
+  }
+  if (line.startsWith("JOB=") || line.startsWith("OUT_DIR=")) return; // 내부 추적
+  if (/=(present|missing)$/.test(line)) return; // 키 존재 점검 라인
+  if (line.trim()) io.out(`  ${line}`);
+}
+
+// `oberon render <manifest.json> [--delivery DIR] [--max-shots N] [--takes N]
+//                [--resolution R] [--max-polls N] [--poll-ms N] [--open] [--dry-run]`
+async function render(io, args, deps = {}) {
+  const { flags, rest } = parseFlags(args);
+  if (!rest[0]) fail("A manifest path is required: agentlas oberon render <manifest.json>");
+  const manifestPath = path.resolve(rest[0]);
+  if (!fs.existsSync(manifestPath)) fail(`Manifest not found: ${manifestPath}`);
+
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+  } catch (e) {
+    fail(`Failed to parse manifest JSON: ${e.message}`);
+  }
+  if (!Array.isArray(manifest.shots) || !manifest.shots.length) fail("The manifest has no shots[].");
+
+  // seam: 다른 산출물 배치(예: Desktop 동봉 빌드)가 생기면 여기만 주입 교체.
+  const { script, builtRender } = (deps.resolveRenderEntry || defaultRenderEntry)();
+  // 정직 정지 — v1과 동일한 문구. 렌더 진입점이 없으면 절대 가짜 렌더를 하지 않는다.
+  if (!fs.existsSync(script)) fail(`Headless render script not found (not included in the packaged app): ${script}`);
+  if (!fs.existsSync(builtRender)) fail(`An Electron build is required. Run npm run build:electron first (missing: ${builtRender})`);
+
+  // --max-shots 등 오버라이드가 있으면 사용자 매니페스트는 그대로 두고 임시 패치본을 만든다.
+  let reqPath = manifestPath;
+  const overrides = {};
+  if (flags["max-shots"]) overrides.maxShots = Number(flags["max-shots"]);
+  if (flags["takes"]) overrides.takesPerShot = Number(flags["takes"]);
+  if (flags["resolution"]) overrides.resolution = flags["resolution"];
+  if (Object.keys(overrides).length) {
+    const patched = { ...manifest, ...overrides };
+    reqPath = path.join(os.tmpdir(), `oberon-req-${Date.now().toString(36)}.json`);
+    fs.writeFileSync(reqPath, JSON.stringify(patched, null, 2), "utf8");
+  }
+
+  const deliveryDir = path.resolve(flags.delivery || path.join(path.dirname(manifestPath), `${slugifyOberon(manifest.title)}-delivery`));
+
+  const childEnv = { ...process.env };
+  delete childEnv.ELECTRON_RUN_AS_NODE; // full Electron으로 부팅 (Desktop execPath일 때)
+  childEnv.OBERON_LIVE_VEO = "1";
+  childEnv.OBERON_LIVE_REQUEST_FILE = reqPath;
+  childEnv.OBERON_LIVE_DELIVERY_DIR = deliveryDir;
+  if (flags["max-polls"]) childEnv.OBERON_LIVE_MAX_POLLS = String(flags["max-polls"]);
+  if (flags["poll-ms"]) childEnv.OBERON_LIVE_POLL_MS = String(flags["poll-ms"]);
+  if (flags.open) childEnv.OBERON_LIVE_OPEN_DELIVERY = "1";
+
+  io.out(`▶ Oberon render: "${manifest.title}"  (${manifest.shots.length} shots, max ${overrides.maxShots ?? manifest.maxShots ?? 3})`);
+  io.out(`  Manifest: ${manifestPath}`);
+  io.out(`  Delivery folder: ${deliveryDir}`);
+  if (manifest.titles) io.out(`  title/subtitle burn-in: enabled → generating additional *_titled.mp4`);
+
+  if (flags["dry-run"]) {
+    const execPath = deps.execPath || process.execPath;
+    io.out("\n[dry-run] Command to run:");
+    io.out(`  ${execPath} ${script}`);
+    io.out("  env: OBERON_LIVE_VEO=1");
+    io.out(`       OBERON_LIVE_REQUEST_FILE=${reqPath}`);
+    io.out(`       OBERON_LIVE_DELIVERY_DIR=${deliveryDir}`);
+    io.out("  (full Electron · GEMINI_API_KEY/GOOGLE_CLOUD_PROJECT vault required)");
+    return 0;
+  }
+
+  const doSpawn = deps.spawn || spawn;
+  const execPath = deps.execPath || process.execPath;
+  const stdoutStream = deps.stdout || process.stdout;
+  const stderrStream = deps.stderr || process.stderr;
+  const lineIo = { out: io.out, write: (s) => stdoutStream.write(s) };
+
+  return new Promise((resolve) => {
+    const child = doSpawn(execPath, [script], { env: childEnv, stdio: ["ignore", "pipe", "pipe"] });
+    const files = [];
+    let buf = "";
+    const handle = (chunk) => {
+      buf += chunk.toString();
+      let nl;
+      while ((nl = buf.indexOf("\n")) >= 0) {
+        const line = buf.slice(0, nl);
+        buf = buf.slice(nl + 1);
+        oberonRenderLine(line, files, lineIo);
+      }
+    };
+    child.stdout.on("data", handle);
+    child.stderr.on("data", (c) => stderrStream.write(c));
+    child.on("close", (code) => {
+      if (code === 0) {
+        io.out(`\n✓ Render complete — delivery folder: ${deliveryDir}`);
+        const titled = files.filter((f) => f.kind && f.kind.startsWith("titled"));
+        if (titled.length) io.out(`  title/subtitle burn-in files: ${titled.map((f) => f.name).join(", ")}`);
+        resolve(0);
+      } else {
+        stderrStream.write(`\n✖ Render failed (exit ${code})\n`);
+        resolve(code || 1); // v1은 process.exitCode 설정 — v2는 코드 반환
+      }
+    });
+  });
+}
+
+module.exports = { render, oberonRenderLine, defaultRenderEntry };

package/engine/project/career-graph.cjs

@@ -0,0 +1,249 @@
+"use strict";
+/*
+ * project/career-graph — 커리어 그래프 소스 라우팅 (v1 monolith 8042–8252 포팅).
+ *
+ * 원칙: 그래프는 재생성 가능한 파생 인덱스다 — Markdown/JSONL/JSON 원장이 원본.
+ * 전체 인덱스 실행(ingest/query/verify/trace)은 Agentlas OS / Hephaestus 런타임
+ * (career_graph 파이썬 모듈)이 소유하고, 터미널은 소스 등록/상태만 담당한다.
+ * status/list는 비변형(초기화 안 된 프로젝트에 파일 생성 금지 — 0.9.10 경계).
+ */
+const fs = require("node:fs");
+const path = require("node:path");
+const { loadArch } = require("../core/db.cjs");
+const { initializedAgentlasProjectPathCli } = require("./state.cjs");
+const {
+  parseFlagsCli,
+  readJsonSafeCli,
+  writeJsonSafeCli,
+  listOntologyInboxCli,
+  resolveOntologyPathCli,
+  inferOntologyKindCli,
+  inferOntologyScopeCli,
+  parseOntologyNaturalArgsCli,
+  openLocalPathCli,
+} = require("./ontology.cjs");
+
+function careerGraphPathsForCli(projectPath) {
+  const arch = loadArch();
+  const root = path.resolve(projectPath || process.cwd());
+  const memoryDir = path.join(root, arch.memoryDir || ".agentlas");
+  return {
+    root,
+    memoryDir,
+    configPath: path.join(memoryDir, arch.careerGraphConfigFile || "career-graph.json"),
+    sourceManifestPath: path.join(memoryDir, arch.careerGraphSourceManifestFile || "career-graph-sources.json"),
+    inboxPath: path.join(memoryDir, arch.careerGraphInboxDir || "career-graph-inbox"),
+    dbPath: path.join(memoryDir, arch.careerGraphDbFile || "career-graph.sqlite"),
+  };
+}
+
+function careerGraphSourceManifestSkeletonCli(root) {
+  return {
+    schemaVersion: "1.0",
+    kind: "agentlas-career-graph-source-manifest",
+    projectRoot: root,
+    sources: [],
+  };
+}
+
+function ensureCareerGraphCli(projectPath, lang) {
+  const paths = careerGraphPathsForCli(projectPath);
+  if (!initializedAgentlasProjectPathCli(paths.root)) {
+    throw new Error(lang === "ko"
+      ? "Agentlas 프로젝트 상태가 초기화되지 않았습니다. 먼저 `agentlas project init`을 명시적으로 실행하세요."
+      : "Agentlas project state is not initialized. Run `agentlas project init` explicitly first.");
+  }
+  fs.mkdirSync(paths.inboxPath, { recursive: true });
+  if (!fs.existsSync(paths.sourceManifestPath)) {
+    writeJsonSafeCli(paths.sourceManifestPath, careerGraphSourceManifestSkeletonCli(paths.root));
+  }
+  return paths;
+}
+
+function readCareerGraphSourcesCli(sourceManifestPath) {
+  const manifest = readJsonSafeCli(sourceManifestPath, { sources: [] });
+  return Array.isArray(manifest.sources) ? manifest.sources : [];
+}
+
+function careerGraphUsageLinesCli(lang) {
+  if (lang === "ko") {
+    return [
+      "커리어 그래프 명령:",
+      "  career-graph status               소스 라우팅 파일과 인덱스 상태 표시",
+      "  career-graph list                 수신함 파일과 등록 소스 참조 목록",
+      "  career-graph open                 프로젝트 커리어 그래프 수신함 열기",
+      "  career-graph add ./docs           폴더를 비공개 소스 자료로 등록",
+      "",
+      "전체 그래프 인덱스 실행은 Agentlas OS / Hephaestus에서 제공합니다.",
+      "안전: 그래프는 재생성 가능하며 Markdown·JSONL·sitemap·code map이 원본입니다.",
+    ];
+  }
+  return [
+    "Career Graph commands:",
+    "  career-graph status               show source-routing files and index state",
+    "  career-graph list                 list inbox files and registered source refs",
+    "  career-graph open                 open the project career graph inbox",
+    "  career-graph add ./docs           register a folder as private source material",
+    "",
+    "Full graph index commands live in Agentlas OS / Hephaestus:",
+    "  hephaestus career-graph ingest --project .",
+    "  hephaestus career-graph query \"release failures\" --project .",
+    "  hephaestus career-graph verify --project .",
+    "",
+    "Safety: the graph is rebuildable. Markdown, JSONL ledgers, sitemap, and code map stay source of truth.",
+  ];
+}
+
+function existingCareerGraphCanonicalRefsCli(root) {
+  return [
+    ".agentlas/project-soul-memory.md",
+    ".agentlas/memory-log.jsonl",
+    ".agentlas/curator-decisions.jsonl",
+    ".agentlas/sitemap.json",
+    ".agentlas/code-map/project-map.json",
+    ".agentlas/ledgers/routing-decisions.jsonl",
+    ".agentlas/ledgers/executions.jsonl",
+    ".agentlas/ledgers/agent-evolution-proposals.jsonl",
+  ].filter((rel) => fs.existsSync(path.join(root, rel)));
+}
+
+function formatCareerGraphStatusCli(paths, lang) {
+  const ko = lang === "ko";
+  const sources = readCareerGraphSourcesCli(paths.sourceManifestPath);
+  const inbox = listOntologyInboxCli(paths.inboxPath);
+  const canonical = existingCareerGraphCanonicalRefsCli(paths.root);
+  const lines = [
+    ko ? "커리어 그래프: 활성" : "Career Graph: active",
+    `  ${ko ? "프로젝트" : "project"}: ${paths.root}`,
+    `  ${ko ? "수신함" : "inbox"}:  ${paths.inboxPath}`,
+    `  DB:     ${paths.dbPath}`,
+    `  ${ko ? "인덱스" : "index"}:  ${fs.existsSync(paths.dbPath) ? (ko ? "있음" : "present") : (ko ? "대기" : "pending")}`,
+    `  ${ko ? "정책" : "policy"}: ledger_first_derived_index`,
+    ko ? "  원본 기준: Markdown / JSONL / JSON 파일" : "  source of truth: Markdown / JSONL / JSON files",
+    "",
+    `${ko ? "기본 소스 참조" : "Canonical source refs"} (${canonical.length}):`,
+  ];
+  for (const rel of canonical) lines.push(`  ${rel}`);
+  if (!canonical.length) lines.push(ko ? "  (아직 없음)" : "  (none yet)");
+  lines.push("", `${ko ? "수신함" : "Inbox"} (${inbox.length}):`);
+  for (const item of inbox) lines.push(`  ${item.supported ? "ok" : "!"} ${item.name}  ${item.supported ? (ko ? "지원됨" : "supported") : (ko ? "어댑터 대기" : "adapter pending")}`);
+  if (!inbox.length) lines.push(ko ? "  (비어 있음)" : "  (empty)");
+  lines.push("", `${ko ? "등록된 소스 참조" : "Registered source refs"} (${sources.length}):`);
+  for (const source of sources) {
+    const sourcePath = path.resolve(String(source.path || ""));
+    lines.push(`  ${fs.existsSync(sourcePath) ? "ok" : "!"} ${sourcePath}  ${source.kind || "project"} / ${source.scope || "private"}`);
+  }
+  if (!sources.length) lines.push(ko ? "  (없음)" : "  (none)");
+  lines.push(
+    "",
+    ko ? "Agentlas OS로 파생 인덱스 만들기:" : "Build the derived index with Agentlas OS:",
+    `  hephaestus career-graph ingest --project ${JSON.stringify(paths.root)}`,
+  );
+  return lines;
+}
+
+function registerCareerGraphSourceCli(paths, source, kind, scope, cwd, lang) {
+  const ko = lang === "ko";
+  if (!source) throw new Error(ko ? "사용법: career-graph add <경로>" : "usage: career-graph add <path>");
+  const sourcePath = resolveOntologyPathCli(source, cwd || paths.root);
+  if (!fs.existsSync(sourcePath)) throw new Error(ko ? `소스를 찾지 못했습니다: ${sourcePath}` : `source not found: ${sourcePath}`);
+  const manifest = readJsonSafeCli(paths.sourceManifestPath, careerGraphSourceManifestSkeletonCli(paths.root));
+  const nextSources = (Array.isArray(manifest.sources) ? manifest.sources : [])
+    .filter((item) => path.resolve(String(item.path || "")) !== sourcePath);
+  nextSources.push({ path: sourcePath, kind, scope, registeredAt: new Date().toISOString() });
+  manifest.schemaVersion = "1.0";
+  manifest.kind = "agentlas-career-graph-source-manifest";
+  manifest.projectRoot = paths.root;
+  manifest.sources = nextSources;
+  writeJsonSafeCli(paths.sourceManifestPath, manifest);
+  return ko
+    ? [
+        `커리어 그래프 소스 등록됨: ${sourcePath}`,
+        `  종류:  ${kind}`,
+        `  범위: ${scope}`,
+        "  복사:  안 함",
+        "  스캔:  이 등록 폴더만 사용하며 홈/이웃 프로젝트는 스캔하지 않음",
+      ]
+    : [
+        `Registered Career Graph source: ${sourcePath}`,
+        `  kind:  ${kind}`,
+        `  scope: ${scope}`,
+        "  copy:  no",
+        "  scan:  only this registered folder, not home/sibling projects",
+      ];
+}
+
+function runCareerGraphCli(args, opts) {
+  opts = opts || {};
+  const ko = opts.lang === "ko";
+  const cwd = path.resolve(opts.cwd || process.cwd());
+  const projectPath = path.resolve(opts.projectPath || cwd);
+  const normalizedArgs = Array.isArray(args) ? args : [];
+  const sub = normalizedArgs[0] || "status";
+  const passivePaths = careerGraphPathsForCli(projectPath);
+  if (sub === "status" || sub === "list") {
+    if (!initializedAgentlasProjectPathCli(projectPath)) {
+      return [
+        ko ? "커리어 그래프: 초기화되지 않음" : "Career Graph: not initialized",
+        `  ${ko ? "프로젝트" : "project"}: ${projectPath}`,
+        ko ? "  생성된 파일 없음" : "  no files were created",
+        ko ? "  명시적 초기화: agentlas project init" : "  initialize explicitly: agentlas project init",
+      ];
+    }
+    return formatCareerGraphStatusCli(passivePaths, opts.lang);
+  }
+  if (sub === "help" || sub === "--help" || sub === "-h") return careerGraphUsageLinesCli(opts.lang);
+  if (["ingest", "query", "verify", "trace"].includes(String(sub))) {
+    return [
+      ko
+        ? "Career Graph 인덱스 실행은 Agentlas OS / Hephaestus에서 제공합니다."
+        : "Career Graph index execution is provided by Agentlas OS / Hephaestus.",
+      `${ko ? "실행" : "Run"}: hephaestus career-graph ${normalizedArgs.join(" ")} --project ${JSON.stringify(passivePaths.root)}`,
+    ];
+  }
+  const directCareerCommand = ["open", "add"].includes(String(sub));
+  if (!directCareerCommand) {
+    const parsed = parseOntologyNaturalArgsCli(normalizedArgs.join(" "), cwd);
+    if (!parsed) throw new Error(ko
+      ? "사용법: /career-graph status|list|open|add <경로>"
+      : "usage: /career-graph status|list|open|add <path>");
+    return runCareerGraphCli(parsed, opts);
+  }
+  const paths = ensureCareerGraphCli(projectPath, opts.lang);
+  if (sub === "open") {
+    if (!opts.noOpen) openLocalPathCli(paths.inboxPath, opts.notify);
+    return [`${ko ? "커리어 그래프 수신함을 열었습니다" : "Opened Career Graph inbox"}: ${paths.inboxPath}`];
+  }
+  if (sub === "add") {
+    const flags = parseFlagsCli(normalizedArgs.slice(1));
+    const source = flags._[0];
+    const kind = inferOntologyKindCli(flags.kind || flags._[1], normalizedArgs.join(" "));
+    const scope = inferOntologyScopeCli(flags.scope || flags._[2], normalizedArgs.join(" "), kind);
+    return registerCareerGraphSourceCli(paths, source, kind, scope, cwd, opts.lang);
+  }
+  throw new Error(ko
+    ? "사용법: /career-graph status|list|open|add <경로>"
+    : "usage: /career-graph status|list|open|add <path>");
+}
+
+function runCareerGraphNaturalCli(text, opts) {
+  const cwd = path.resolve((opts && opts.cwd) || process.cwd());
+  const parsed = parseOntologyNaturalArgsCli(text, cwd);
+  if (!parsed) throw new Error((opts && opts.lang) === "ko"
+    ? "사용법: /career-graph status|list|open|add <경로>"
+    : "usage: /career-graph status|list|open|add <path>");
+  return runCareerGraphCli(parsed, { ...(opts || {}), cwd });
+}
+
+module.exports = {
+  careerGraphPathsForCli,
+  careerGraphSourceManifestSkeletonCli,
+  ensureCareerGraphCli,
+  readCareerGraphSourcesCli,
+  careerGraphUsageLinesCli,
+  existingCareerGraphCanonicalRefsCli,
+  formatCareerGraphStatusCli,
+  registerCareerGraphSourceCli,
+  runCareerGraphCli,
+  runCareerGraphNaturalCli,
+};