agentlas 1.0.29 → 1.0.35

package/engine/commands/connect.cjs

@@ -1,20 +1,173 @@
 "use strict";
 /*
- * connect — Telegram 등 플랫폼 연결 (hep-connect 라우트).
+ * connect — Telegram 연결·조종 (2026-08-06 독립화).
  *
- * v1 디스패처 매핑 그대로:
- *   `agentlas connect <sub…>` → cmdHep(["hep-connect", ...rest])
- *   무인자 connect는 v1에서 fail이 아니라 usage 안내 후 exit 0이었다
- *   (topLevelCommandUsage("connect") 특례) — 그대로 보존.
+ * 오너 원칙: 데스크탑에서 쉽게 되는 telegram 연결이 터미널에서도 돼야 한다.
+ * 데스크탑 electron/telegram/connect.ts 의 실제 연결 코어는 순수 HTTPS
+ * (api.telegram.org)이고 Electron 이 필요 없다 — 브라우저 자동 조종은 봇 자동
+ * 생성 편의일 뿐. 그 코어를 engine/telegram/connect.cjs 로 이식했다. 여기서는
+ * CLI 표면만 배선한다.
+ *
+ * 이전: connect 는 hep-connect 플러그인 패스스루라 라우터 원시 JSON 을 덤프했다.
+ *
+ * 하위 명령:
+ *   connect                           상태 표
+ *   connect telegram <agent|firm>     이 대상에 봇을 연결(토큰 stdin) + 방 페어링
+ *   connect test <id>                 연결된 방에 확인 메시지
+ *   connect remove <id>               연결 제거(토큰 파일도 삭제)
  */
-const { create, usageFor, isHelpToken } = require("../hephaestus/runtime.cjs");
+const { renderTelegram } = require("./telegram.cjs");
+const tg = require("../telegram/connect.cjs");
+const { findAgent } = require("../agents/registry.cjs");
+const readline = require("node:readline");
+
+function usage(ko) {
+  return ko
+    ? "사용법: agentlas connect [ status | telegram <agent|firm> [--auto] | test <id> | remove <id> ]"
+    : "Usage: agentlas connect [ status | telegram <agent|firm> [--auto] | test <id> | remove <id> ]";
+}
+
+function resolveTarget(db, token) {
+  const agent = findAgent(db, token);
+  if (agent) return { kind: "agent", id: agent.id, name: agent.name || agent.slug };
+  try {
+    const q = String(token).trim().toLowerCase();
+    const firm = db.prepare("SELECT id, slug, name FROM firms WHERE lower(id)=? OR lower(slug)=? OR lower(name)=?").get(q, q, q)
+      || db.prepare("SELECT id, slug, name FROM firms WHERE lower(slug) LIKE ? ORDER BY slug LIMIT 1").get(`%${q}%`);
+    if (firm) return { kind: "firm", id: firm.id, name: firm.name || firm.slug };
+  } catch { /* no firms table */ }
+  return null;
+}
+
+/** 봇 토큰을 stdin 에서 읽는다(비밀은 argv 금지). 파이프면 첫 줄, TTY면 숨김 안내. */
+async function readTokenFromStdin(ctx, ko) {
+  if (!process.stdin.isTTY) {
+    return new Promise((resolve) => {
+      let buf = "";
+      process.stdin.on("data", (d) => { buf += d; });
+      process.stdin.on("end", () => resolve(buf.split(/\r?\n/)[0].trim()));
+    });
+  }
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  ctx.out(ko
+    ? "@BotFather 에서 봇을 만들고 받은 토큰을 붙여넣으세요 (입력은 화면에 남습니다 — 끝나면 창을 지우세요):"
+    : "Create a bot with @BotFather and paste the token (it echoes — clear your screen after):");
+  return new Promise((resolve) => {
+    rl.question("token> ", (answer) => { rl.close(); resolve(String(answer).trim()); });
+  });
+}
+
+async function connectTelegram(ctx, targetToken, { auto = false } = {}) {
+  const ko = ctx.lang === "ko";
+  const db = ctx.db();
+  const target = resolveTarget(db, targetToken);
+  if (!target) {
+    ctx.err((ko ? "대상을 찾을 수 없습니다: " : "target not found: ") + targetToken);
+    ctx.err(ctx.ui.dim(ko ? "에이전트·회사 목록: agentlas list" : "list agents and companies: agentlas list"));
+    return 1;
+  }
+
+  let token;
+  if (auto) {
+    // --auto: 터미널이 Agentlas 브라우저(CDP)로 BotFather 를 열고 토큰을 직접 읽는다.
+    ctx.out(ko
+      ? "Agentlas 브라우저에서 BotFather 를 엽니다. 필요하면 로그인(QR)한 뒤, `/newbot` 으로 봇을 만드세요 — 토큰은 제가 화면에서 읽어옵니다."
+      : "Opening BotFather in the Agentlas browser. Log in (QR) if needed, then create a bot with `/newbot` — I'll read the token off the page.");
+    try {
+      if (typeof ctx.ui.startSpinner === "function") ctx.ui.startSpinner(ko ? "BotFather 토큰 대기 중…" : "Waiting for a BotFather token…");
+      token = await require("../telegram/connect.cjs").captureBotTokenViaBrowser({ timeoutMs: 180_000 });
+    } catch (e) {
+      if (typeof ctx.ui.stopSpinner === "function") ctx.ui.stopSpinner();
+      if (e && e.code === "cdp_unavailable") {
+        ctx.err(ko
+          ? "Agentlas 브라우저가 실행 중이 아닙니다. 먼저 `agentlas browser https://web.telegram.org` 로 브라우저를 띄운 뒤 다시 --auto 하거나, --auto 없이 토큰을 직접 붙여넣으세요."
+          : "The Agentlas browser is not running. Start it with `agentlas browser https://web.telegram.org`, then retry --auto, or paste the token without --auto.");
+        return 1;
+      }
+      ctx.err(`${ctx.ui.red("✖")} ${String((e && e.message) || e)}`);
+      return 1;
+    }
+    if (typeof ctx.ui.stopSpinner === "function") ctx.ui.stopSpinner();
+    if (!token) {
+      ctx.err(ko ? "시간 내 토큰을 못 읽었습니다(3분). 다시 시도하거나 --auto 없이 붙여넣으세요." : "No token captured in time (3 min). Retry, or paste it without --auto.");
+      return 1;
+    }
+    ctx.out(ctx.ui.dim(ko ? "토큰을 읽었습니다." : "Captured the token."));
+  } else {
+    token = await readTokenFromStdin(ctx, ko);
+    if (!token) { ctx.err(ko ? "토큰이 필요합니다." : "a bot token is required."); return 1; }
+  }
+
+  let started;
+  try {
+    if (typeof ctx.ui.startSpinner === "function") ctx.ui.startSpinner(ko ? "봇 토큰 확인 중…" : "Verifying bot token…");
+    started = await tg.startConnection(db, target.kind, target.id, token);
+  } catch (e) {
+    if (typeof ctx.ui.stopSpinner === "function") ctx.ui.stopSpinner();
+    ctx.err(`${ctx.ui.red("✖")} ${String((e && e.message) || e)}`);
+    return 1;
+  }
+  if (typeof ctx.ui.stopSpinner === "function") ctx.ui.stopSpinner();
+  const botAt = started.botUsername ? "@" + started.botUsername : "(bot)";
+  ctx.out(`${ctx.ui.green("✓")} ${ko ? "봇 확인됨" : "bot verified"}: ${botAt} → ${target.name}`);
+  ctx.out(ko
+    ? `이제 텔레그램에서 ${botAt} 에게 아무 메시지나 보내세요 (예: /start). 방을 기다립니다…`
+    : `Now message ${botAt} on Telegram (e.g. /start). Waiting for the chat…`);
+
+  let paired;
+  try {
+    if (typeof ctx.ui.startSpinner === "function") ctx.ui.startSpinner(ko ? "방 연결 대기 중…" : "Waiting for the chat…");
+    paired = await tg.pairByPolling(db, started.id, { timeoutMs: 120_000 });
+  } catch (e) {
+    if (typeof ctx.ui.stopSpinner === "function") ctx.ui.stopSpinner();
+    ctx.err(`${ctx.ui.red("✖")} ${String((e && e.message) || e)}`);
+    return 1;
+  }
+  if (typeof ctx.ui.stopSpinner === "function") ctx.ui.stopSpinner();
+
+  if (!paired) {
+    ctx.out(ctx.ui.dim(ko
+      ? `방을 못 받았습니다(2분 초과). ${botAt} 에게 메시지를 보낸 뒤 다시: agentlas connect test ${started.id}`
+      : `No chat received (2 min). Message ${botAt}, then retry: agentlas connect test ${started.id}`));
+    return 0;
+  }
+  ctx.out(`${ctx.ui.green("✓")} ${ko ? "방 연결됨" : "chat paired"}: ${paired.telegram_chat_title || paired.telegram_chat_id}`);
+  try {
+    await tg.sendTest(db, started.id, ko ? `Agentlas 연결 완료 — ${target.name}` : `Agentlas connected — ${target.name}`);
+    ctx.out(ctx.ui.dim(ko ? "확인 메시지를 보냈습니다." : "Sent a confirmation message."));
+  } catch { /* 페어링은 됐으니 테스트 실패는 치명적 아님 */ }
+  return 0;
+}
 
 async function run(ctx, args) {
-  if (args.some(isHelpToken) || !args.length) {
-    ctx.out(usageFor("connect", ctx.lang));
+  const ko = ctx.lang === "ko";
+  const sub = String(args[0] || "").toLowerCase();
+
+  if (!sub || sub === "help" || sub === "--help" || sub === "-h") { ctx.out(usage(ko)); return 0; }
+  if (sub === "status") return renderTelegram(ctx);
+  if (sub === "telegram") {
+    const rest = args.slice(1);
+    const auto = rest.includes("--auto");
+    const targetToken = rest.find((a) => a && !String(a).startsWith("-"));
+    if (!targetToken) { ctx.err(usage(ko)); return 1; }
+    return connectTelegram(ctx, targetToken, { auto });
+  }
+  if (sub === "test") {
+    if (!args[1]) { ctx.err(ko ? "사용법: agentlas connect test <id>" : "Usage: agentlas connect test <id>"); return 1; }
+    try {
+      await tg.sendTest(ctx.db(), args[1], ko ? "Agentlas 테스트 메시지" : "Agentlas test message");
+      ctx.out(`${ctx.ui.green("✓")} ${ko ? "메시지를 보냈습니다." : "message sent."}`);
+      return 0;
+    } catch (e) { ctx.err(`${ctx.ui.red("✖")} ${String((e && e.message) || e)}`); return 1; }
+  }
+  if (sub === "remove") {
+    if (!args[1]) { ctx.err(ko ? "사용법: agentlas connect remove <id>" : "Usage: agentlas connect remove <id>"); return 1; }
+    tg.removeBinding(ctx.db(), args[1]);
+    ctx.out(`${ctx.ui.green("✓")} ${ko ? "연결을 제거했습니다." : "connection removed."}`);
     return 0;
   }
-  return create(ctx).cmdHep(["hep-connect", ...args]);
+  ctx.err(usage(ko));
+  return 1;
 }
 
 module.exports = { run };

package/engine/commands/creds.cjs

@@ -191,8 +191,22 @@ async function run(ctx, args) {
   }
   const f = parseCredFlags(args.slice(1));
   const key = typeof f.key === "string" ? f.key.trim() : "";
-  const value = f.value === undefined || f.value === true ? "" : String(f.value);
-  if (!key || !value) return fail("creds save requires --key and --value");
+  let value = f.value === undefined || f.value === true ? "" : String(f.value);
+  /*
+   * 비밀은 argv에 실리면 안 된다(clig.dev: never read secrets from flags) —
+   * 셸 히스토리와 `ps` 출력에 평문으로 남는다. `--value -` 는 stdin에서 읽는다:
+   *   printf '%s' "$SECRET" | agentlas creds save --key X --value -
+   * argv로 직접 준 경우는 기존 사용을 깨지 않되, 노출 사실을 그 자리에서 알린다.
+   */
+  if (value === "-") {
+    value = fs.readFileSync(0, "utf8").replace(/\r?\n$/, "");
+    if (!value) return fail("creds save --value - expected the secret on stdin, but stdin was empty");
+  } else if (value) {
+    ctx.err(ctx.lang === "ko"
+      ? "참고: --value 로 준 비밀은 셸 히스토리·ps 에 남습니다. 다음부터는 stdin 을 쓰세요: printf '%s' \"$SECRET\" | agentlas creds save --key X --value -"
+      : "Note: a secret passed via --value lands in shell history and `ps`. Prefer stdin next time: printf '%s' \"$SECRET\" | agentlas creds save --key X --value -");
+  }
+  if (!key || !value) return fail("creds save requires --key and --value (use `--value -` to read the secret from stdin)");
   const provider = typeof f.provider === "string" && f.provider ? f.provider : key;
   const project = typeof f.project === "string" && f.project ? f.project : activeProjectPath(ctx.db());
   const targets = [];

package/engine/commands/doctor.cjs

@@ -24,8 +24,27 @@ function roleDetail(selection, role, en) {
   ].filter(Boolean).join(" · ");
 }
 
-function run(ctx) {
+function run(ctx, args = []) {
   const en = ctx.lang === "en";
+  // clig.dev: 스크립트 소비자를 위한 기계 계약. 사람용 줄과 같은 사실만 담는다.
+  if (args.includes("--json")) {
+    const db = ctx.db();
+    const clis = listAvailableCliRuntimes().map((c) => ({ kind: c.kind, path: c.path, authEvidence: runtimeAuthEvidence(c.kind).status }));
+    const active = activeRuntimeRow(db);
+    return (() => {
+      ctx.out(JSON.stringify({
+        database: { path: dbPath(), exists: fs.existsSync(dbPath()) },
+        runtimes: clis,
+        activeRuntime: active ? { ...active, authEvidence: runtimeAuthEvidence(active.kind).status } : null,
+        modelRoles: {
+          orchestrator: resolvedModelRole(db, "orchestrator"),
+          worker: resolvedModelRole(db, "worker"),
+        },
+        cloudSession: Boolean(process.env.AGENTLAS_SESSION) || fs.existsSync(path.join(userDataDir(), "auth", "cli-session.v1.json")),
+      }, null, 2));
+      return 0;
+    })();
+  }
   let failures = 0;
   let warnings = 0;
   const ok = (label, detail) => ctx.out(`  ${ctx.ui.green("✓")} ${label}${detail ? ctx.ui.dim(" — " + detail) : ""}`);

package/engine/commands/document.cjs

@@ -0,0 +1,79 @@
+"use strict";
+/*
+ * document — 문서 산출(2026-08-06). 지금은 PDF 내보내기.
+ *
+ * 오너 원칙("터미널인데 모든 기능이 다 돼야"): 데스크탑 document/export-pdf.ts 는 offscreen
+ * BrowserWindow.printToPDF 로 HTML/URL 을 PDF 로 굽는다. 터미널은 같은 메커니즘을 CDP
+ * Page.printToPDF(engine/browser/cdp.cjs)로 한다 — GUI 창 없이 Agentlas 전용 Chrome 에서.
+ *
+ *   document pdf <html-file|url> [-o out.pdf] [--landscape]
+ *
+ * 로컬 HTML 파일은 file:// 로, http(s) 는 그대로 연다. 브라우저(CDP)가 없으면 정직하게
+ * 멈추고 먼저 띄우도록 안내한다(조용히 안 되는 척하지 않는다).
+ */
+const path = require("node:path");
+const fs = require("node:fs");
+const cdp = require("../browser/cdp.cjs");
+
+function usage(ko) {
+  return ko
+    ? "사용법: agentlas document pdf <html파일|url> [-o 출력.pdf] [--landscape]"
+    : "Usage: agentlas document pdf <html-file|url> [-o out.pdf] [--landscape]";
+}
+
+function toUrl(src) {
+  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(src)) return src;           // http(s):// · file:// · data:
+  return "file://" + path.resolve(src);                            // 로컬 파일
+}
+
+async function toPdf(ctx, args) {
+  const ko = ctx.lang === "ko";
+  const flags = { landscape: args.includes("--landscape") };
+  const oi = args.indexOf("-o");
+  const out = oi >= 0 && args[oi + 1] ? args[oi + 1] : null;
+  const src = args.find((a, i) => a && !String(a).startsWith("-") && (oi < 0 || i !== oi + 1));
+  if (!src) { ctx.err(usage(ko)); return 1; }
+
+  // 로컬 파일이면 존재 확인(없는 걸 조용히 빈 PDF 로 굽지 않는다).
+  if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(src) && !fs.existsSync(path.resolve(src))) {
+    ctx.err((ko ? "파일이 없습니다: " : "no such file: ") + src);
+    return 1;
+  }
+  const url = toUrl(src);
+  const outPath = path.resolve(out || (src.replace(/^https?:\/\//, "").replace(/[^\w.-]+/g, "_").replace(/\.(html?|md)$/i, "") || "document") + ".pdf");
+
+  if (!(await cdp.cdpReady())) {
+    ctx.err(ko
+      ? `Agentlas 브라우저가 실행 중이 아닙니다. 먼저 띄우세요: agentlas browser ${url}`
+      : `The Agentlas browser is not running. Start it first: agentlas browser ${url}`);
+    return 1;
+  }
+  let page;
+  try {
+    if (typeof ctx.ui.startSpinner === "function") ctx.ui.startSpinner(ko ? "PDF 굽는 중…" : "Rendering PDF…");
+    page = await cdp.attachPage();
+    await page.navigate(url, { waitMs: 1800 });
+    await page.waitFor("document.readyState === 'complete'", { timeoutMs: 8000 });
+    const r = await page.printPdf(outPath, { landscape: flags.landscape });
+    if (typeof ctx.ui.stopSpinner === "function") ctx.ui.stopSpinner();
+    ctx.out(`${ctx.ui.green("✓")} ${ko ? "PDF 를 만들었습니다" : "wrote PDF"}: ${r.path} ${ctx.ui.dim(`(${Math.round(r.bytes / 1024)} KB)`)}`);
+    return 0;
+  } catch (e) {
+    if (typeof ctx.ui.stopSpinner === "function") ctx.ui.stopSpinner();
+    ctx.err(`${ctx.ui.red("✖")} ${String((e && e.message) || e)}`);
+    return 1;
+  } finally {
+    if (page) page.close();
+  }
+}
+
+async function run(ctx, args) {
+  const ko = ctx.lang === "ko";
+  const sub = String(args[0] || "").toLowerCase();
+  if (!sub || sub === "help" || sub === "-h" || sub === "--help") { ctx.out(usage(ko)); return 0; }
+  if (sub === "pdf") return toPdf(ctx, args.slice(1));
+  ctx.err(usage(ko));
+  return 1;
+}
+
+module.exports = { run };

package/engine/commands/graph.cjs

@@ -588,7 +588,12 @@ async function newGraph(ctx, request, flags) {
 
   const interview = require("../graph/interview.cjs");
   const { askModel } = require("../graph/ask-model.cjs");
-  let state = interview.startInterview(request);
+  // 이미 저장된 자동화들을 인터뷰에 싣는다 — runGraph 단계가 이 중에서만 고르게 하려는 것.
+  //   목록이 없으면 모델이 id를 지어내고, 그 그래프는 실행 때 죽는다(데스크탑과 같은 규칙).
+  const knownGraphs = (() => {
+    try { return graphRows(ctx, db).map((r) => ({ id: r.id, name: r.name })); } catch { return []; }
+  })();
+  let state = interview.startInterview(request, { knownGraphs });
 
   // 파이프로 들어온 답은 **미리 전부 읽어 둔다.** readline은 입력 스트림이 끝나면 닫히므로,
   // 질문마다 물으면 두 번째 질문에서 "readline was closed"로 죽는다(실측).
@@ -624,9 +629,28 @@ async function newGraph(ctx, request, flags) {
       }
       const parsed = interview.parseInterviewTurn(answer.text, state);
       if (!parsed.ok) {
-        ctx.err(parsed.reason);
-        ctx.err(ctx.ui.dim(parsed.nextAction));
-        return 1;
+        /*
+         * ★모델이 형식을 틀린 것과 사람이 답을 안 준 것은 다르다.
+         *
+         * 출력이 JSON으로 안 읽히면 지금까지는 그 자리에서 인터뷰가 죽고 **사람이 준
+         * 답까지 전부 사라졌다.** 화면에는 "자동으로 돌릴 일을 한 문장으로 다시 적어
+         * 주세요"가 떴다 — 사람 문장이 틀린 것처럼(실측 2026-08-06, 연속 3회 재현).
+         * 형식 문제는 이미 스스로 고치게 하는 장치가 있다. 같은 예산 안에서 그쪽으로 보낸다.
+         */
+        const correctable = parsed.code === "INTERVIEW_OUTPUT_UNREADABLE"
+          && (state.attempts || []).length < interview.MAX_SELF_CORRECTIONS;
+        if (!correctable) {
+          ctx.err(parsed.reason);
+          ctx.err(ctx.ui.dim(parsed.nextAction));
+          return 1;
+        }
+        state.attempts = [...(state.attempts || []), {
+          round,
+          problems: [en
+            ? "The last answer did not read as a single JSON object. Return one JSON object and nothing else."
+            : "지난 답이 JSON 하나로 읽히지 않았습니다. 설명 없이 JSON 객체 하나만 내보내세요."],
+        }];
+        continue;
       }
       // ★모델이 형식을 틀렸다 — 사람이 답을 안 준 게 아니다. 무엇이 틀렸는지 돌려주고
       //   정해진 횟수만큼 스스로 고치게 한다. "구체적으로 적어 주세요"로 떠넘기면
@@ -650,7 +674,7 @@ async function newGraph(ctx, request, flags) {
         continue;
       }
       if (parsed.turn.kind === "blueprint") {
-        built = interview.buildGraphFromBlueprint(parsed.turn.blueprint, en ? "en" : "ko");
+        built = interview.buildGraphFromBlueprint(parsed.turn.blueprint, en ? "en" : "ko", { knownGraphs });
         if (!built.ok) {
           // 청사진 검증은 통과했는데 짓는 데서 걸렸다 — 이것도 형식 문제라 같은 규율.
           state.attempts = [...(state.attempts || []), { round, problems: built.problems.map((p) => p.reason) }];
@@ -753,11 +777,27 @@ async function newGraph(ctx, request, flags) {
     const target = pickDefaultAgent(ctx, db);
     const id = `graph-${crypto.randomUUID()}`;
     try {
-      db.prepare(
-        `INSERT INTO automations
-           (id, name, schedule, target_type, target_id, prompt_template, enabled, created_by, created_at, next_run_at, graph_json)
-         VALUES (?, ?, ?, 'agent', ?, ?, 0, 'user', ?, NULL, ?)`,
-      ).run(id, name, built.scheduleHuman, target, name, new Date().toISOString(), JSON.stringify(built.graph));
+      /*
+       * ★목적 문장(goal)을 함께 싣는다 — 빼면 "이 그래프가 무엇인지"를 아는 유일한 문장이
+       * 저장 순간 사라진다. 실측(2026-08-06): 터미널로 만든 그래프의 goal이 null이라
+       * Hub 발행 tagline이 한국어 하드코딩 폴백("N단계 자동화 그래프")으로 떨어졌고,
+       * 그 문장이 영문 칸에 실려 발행이 거절됐다. goal 칸은 데스크탑 스키마 백스톱이
+       * 보장하지만, 옛 DB 방어로 columnExists 가드를 둔다.
+       */
+      const hasGoal = ctx.columnExists(db, "automations", "goal");
+      if (hasGoal) {
+        db.prepare(
+          `INSERT INTO automations
+             (id, name, schedule, target_type, target_id, prompt_template, enabled, created_by, created_at, next_run_at, graph_json, goal)
+           VALUES (?, ?, ?, 'agent', ?, ?, 0, 'user', ?, NULL, ?, ?)`,
+        ).run(id, name, built.scheduleHuman, target, name, new Date().toISOString(), JSON.stringify(built.graph), (bp.goal || "").trim() || null);
+      } else {
+        db.prepare(
+          `INSERT INTO automations
+             (id, name, schedule, target_type, target_id, prompt_template, enabled, created_by, created_at, next_run_at, graph_json)
+           VALUES (?, ?, ?, 'agent', ?, ?, 0, 'user', ?, NULL, ?)`,
+        ).run(id, name, built.scheduleHuman, target, name, new Date().toISOString(), JSON.stringify(built.graph));
+      }
     } catch (err) {
       ctx.err(en ? `Could not save: ${err.message}` : `저장하지 못했습니다: ${err.message}`);
       return 1;

package/engine/commands/help.cjs

@@ -15,7 +15,7 @@ AGENTS & HUB
   search "<what you need>" discover agents in the Hub
   install <slug>           install an agent from the Hub
   plugin add <slug> · plugin list      Hub plugins (MCP servers)
-  build "<request>"        build/repair/package an agent or team
+  build "<request>"        build an installable agent locally (auto-installs)
   upload <path>            save owner-private in Agent Cloud (--visibility marketplace to publish)
   import <path> · cd · native prepare  local folder agents
   list                     installed agents/companies + orchestrator/worker runtimes
@@ -29,13 +29,14 @@ EXECUTE
   workforce | network <request>   Agent Workforce Ontology route (public Hub menu)
   hep-network "<request>"  staff across Local + owner Cloud + public Hub (local Core federation)
   hep-local | hep-cloud | hep-hub "<request>"   same, restricted to one source scope
-  call "a,b" "<ctx>" · browser · route "<req>" [--json] · research <sub>
+  call "a,b" "<ctx>" · browser <url|status|sites|login> · route "<req>" [--json] · research <sub>
 
 KNOWLEDGE
   memory import · evolve   memory & prompt-evolution proposals
   ontology · career-graph  project knowledge & source routing
   journal <sub>            Stormbreaker run journal
-  project [status|init]    private .agentlas project state (init is explicit)
+  project <sub>            connect this folder + set an ordered team, standalone
+                           (status · init · use <agent> · team <agent>…)
   context <sub>            dependency map: refresh|locate|refs|slice|impact|verify
 
 ACCOUNT & OPS
@@ -82,7 +83,7 @@ AGENTS & HUB
   search "<필요한 것>"     Hub에서 에이전트 찾기
   install <slug>           Hub 에이전트 설치
   plugin add <slug> · plugin list      Hub 플러그인 (MCP 서버)
-  build "<요청>"           에이전트·팀 제작/수리/패키징
+  build "<요청>"           에이전트를 로컬에서 만들고 바로 설치
   upload <path>            Agent Cloud에 소유자 비공개 저장 (--visibility marketplace 로 발행)
   import <path> · cd · native prepare  로컬 폴더 에이전트
   list                     설치 에이전트/회사 + 오케스트레이터·워커 런타임
@@ -96,13 +97,14 @@ EXECUTE
   workforce | network <request>   Agent Workforce Ontology 편성 (공개 Hub 메뉴)
   hep-network "<request>"  로컬+오너 클라우드+공개 Hub 연합 편성 (로컬 Core 연합)
   hep-local | hep-cloud | hep-hub "<request>"   같은 편성, 한 소스 스코프로 제한
-  call "a,b" "<ctx>" · browser · route "<req>" [--json] · research <sub>
+  call "a,b" "<ctx>" · browser <url|status|sites|login> · route "<req>" [--json] · research <sub>
 
 KNOWLEDGE
   memory import · evolve   메모리·프롬프트 진화 제안
   ontology · career-graph  프로젝트 지식·소스 라우팅
   journal <sub>            Stormbreaker 런 저널
-  project [status|init]    비공개 .agentlas 프로젝트 상태 (init은 명시적)
+  project <sub>            이 폴더를 프로젝트로 연결 + 순서 팀 편성 (독립)
+                           (status · init · use <에이전트> · team <에이전트>…)
   context <sub>            의존성 지도: refresh|locate|refs|slice|impact|verify
 
 ACCOUNT & OPS

package/engine/commands/index.cjs

@@ -35,6 +35,7 @@ const COMMANDS = {
   automation: () => require("./automation.cjs"),
   native: () => require("./native.cjs"),
   multimodal: () => require("./multimodal.cjs"),
+  document: () => require("./document.cjs"),
   workforce: () => require("./workforce.cjs"),
   network: () => require("./workforce.cjs"),
   taskforce: () => require("./workforce.cjs"),

package/engine/commands/list.cjs

@@ -24,7 +24,7 @@ function roleRuntimeLabel(selection, role, en) {
   return bits.join(" ");
 }
 
-function run(ctx) {
+function run(ctx, args = []) {
   const db = ctx.db();
   // 프라이버시 정책(웹 전용/백그라운드 제외)은 registry가 소유한다 — 직접 SQL 금지.
   const agents = listAgents(db).map((a) => ({
@@ -34,6 +34,15 @@ function run(ctx) {
     ? db.prepare("SELECT id, slug, name FROM firms ORDER BY name").all()
     : [];
 
+  // clig.dev: 스크립트 소비자는 사람용 표를 파싱하게 두지 말 것 — --json 은
+  // 사람용 출력과 같은 사실을 기계 계약으로 준다.
+  if (args.includes("--json")) {
+    const orchestrator = resolvedModelRole(db, "orchestrator");
+    const worker = resolvedModelRole(db, "worker");
+    ctx.out(JSON.stringify({ agents, firms, modelRoles: { orchestrator, worker } }, null, 2));
+    return 0;
+  }
+
   const en = ctx.lang === "en";
   ctx.out(ctx.ui.bold(en ? "Installed agents" : "설치된 에이전트"));
   if (!agents.length) {

package/engine/commands/project.cjs

@@ -1,31 +1,64 @@
 "use strict";
 /*
- * project — 명시적 프로젝트 초기화/점검 (v1 monolith 13199–13223 포팅).
+ * project — 프로젝트 상태·초기화, 그리고 순서 팀 편성 (독립).
  *
- * 0.9.10 경계: `.agentlas/` 를 만드는 유일한 진입점은 `agentlas project init` 이다.
- * `project status` 는 완전 수동(파일 생성/DB visit 기록 없음)으로 검사만 한다.
+ * 2026-08-06(오너 원칙): 데스크탑/플러그인은 산출물·설정을 공유할 뿐 선행 전제가
+ * 아니다. 그래서 `project team`·`project use`로 터미널에서 직접 폴더를 프로젝트로
+ * 연결하고 컨트롤러 팀을 정한다 — 이후 `run "<task>"`와 REPL 평문 입력이 데스크탑
+ * 없이 동작한다. 프로젝트 쓰기는 engine/project/team.cjs가 소유(스키마 공유).
  */
 const { projectCwd } = require("../project/paths.cjs");
 const {
   ensureTerminalProjectForExecutionCli,
   initializeTerminalProjectCli,
 } = require("../project/state.cjs");
+const { connectProjectTeam } = require("../project/team.cjs");
+const { resolveProjectController } = require("../project/controller.cjs");
+
+function showStatus(ctx, cwd, ko) {
+  const active = ensureTerminalProjectForExecutionCli(ctx.db(), cwd, "read", "terminal-project-status");
+  ctx.out(`${ko ? "프로젝트 폴더" : "project"}: ${cwd}`);
+  ctx.out(`${ko ? ".agentlas 상태" : "Agentlas state"}: ${active
+    ? (ko ? "초기화됨" : "initialized")
+    : (ko ? "초기화되지 않음" : "not initialized")}`);
+  // 연결된 프로젝트 + 순서 팀(컨트롤러)을 보여준다 — 데스크탑 없이도 무엇이 실행될지.
+  try {
+    const resolved = resolveProjectController(ctx.db(), cwd);
+    const pool = resolved.project?.agentPool || [];
+    ctx.out(`${ko ? "연결된 프로젝트" : "connected project"}: ${resolved.project?.name || "—"}`);
+    if (pool.length) {
+      ctx.out(ko ? "순서 팀 (0번=컨트롤러):" : "ordered team (index 0 = controller):");
+      pool.forEach((m, i) => ctx.out(`  ${i}. ${m.nameSnapshot}`));
+    }
+  } catch (e) {
+    if (e && e.code === "project_not_connected") {
+      ctx.out(ctx.ui.dim(ko
+        ? "이 폴더는 아직 프로젝트에 연결되지 않았습니다. `agentlas project use <에이전트>`로 연결하세요."
+        : "This folder is not connected to a project yet. Connect it with `agentlas project use <agent>`."));
+    } else if (e && e.honestStop) {
+      ctx.out(ctx.ui.dim(String(e.message)));
+    }
+    // 그 외 오류는 status를 막지 않는다.
+  }
+  return 0;
+}
+
+function reportTeam(ctx, result, ko) {
+  ctx.out(`${ctx.ui.green("✓")} ${ko ? "프로젝트" : "project"} ${result.created ? (ko ? "생성" : "created") : (ko ? "갱신" : "updated")}: ${result.name}`);
+  ctx.out(ko ? "순서 팀 (0번=컨트롤러):" : "ordered team (index 0 = controller):");
+  result.team.forEach((m, i) => ctx.out(`  ${i}. ${m.nameSnapshot}`));
+  ctx.out(ctx.ui.dim(ko
+    ? "이제 이 폴더에서 바로 실행: agentlas run \"<할 일>\"  또는 REPL에서 그냥 문장을 치세요."
+    : "Now run here directly: agentlas run \"<task>\"  or just type a sentence in the REPL."));
+}
 
 function run(ctx, args) {
   const action = String(args[0] || "status").toLowerCase();
   const cwd = projectCwd();
   const ko = ctx.lang === "ko";
-  if (action === "status") {
-    const active = ensureTerminalProjectForExecutionCli(ctx.db(), cwd, "read", "terminal-project-status");
-    ctx.out(`${ko ? "프로젝트" : "project"}: ${cwd}`);
-    ctx.out(`${ko ? "Agentlas 상태" : "Agentlas state"}: ${active
-      ? (ko ? "초기화됨" : "initialized")
-      : (ko ? "초기화되지 않음" : "not initialized")}`);
-    if (!active) ctx.out(ko
-      ? "비공개 .agentlas 상태와 로컬 제외 파일을 만들려면 `agentlas project init`을 실행하세요."
-      : "Run `agentlas project init` to create private .agentlas state and update local ignore files.");
-    return 0;
-  }
+
+  if (action === "status") return showStatus(ctx, cwd, ko);
+
   if (action === "init") {
     ctx.out(ko
       ? "비공개 Agentlas 프로젝트 상태를 초기화합니다. .agentlas/ 생성, .gitignore 갱신, 로컬 자격증명·서명 템플릿 추가가 포함될 수 있습니다."
@@ -33,14 +66,44 @@ function run(ctx, args) {
     try {
       initializeTerminalProjectCli(ctx.db(), cwd);
     } catch (e) {
-      // fail-closed: 프라이버시 경계(.gitignore/심볼릭 링크)를 보증 못 하면 생성 금지.
       ctx.err(String((e && e.message) || e));
       return 1;
     }
     ctx.out(`${ko ? "초기화됨" : "Initialized"}: ${cwd}`);
     return 0;
   }
-  ctx.err("Usage: agentlas project [status|init]");
+
+  /*
+   * project use <에이전트>            — 이 폴더를 프로젝트로 연결 + 단일 컨트롤러 팀
+   * project team <에이전트> [<에이전트>...] — 순서 팀 편성 (0번=컨트롤러)
+   * 둘 다 데스크탑 없이 동작한다.
+   */
+  if (action === "use" || action === "team") {
+    const tokens = args.slice(1).filter((t) => t && !String(t).startsWith("-"));
+    if (!tokens.length) {
+      ctx.err(ko
+        ? `사용법: agentlas project ${action} <에이전트> ${action === "team" ? "[<에이전트>...]" : ""}  ·  에이전트 목록: agentlas list`
+        : `Usage: agentlas project ${action} <agent> ${action === "team" ? "[<agent>...]" : ""}  ·  list agents: agentlas list`);
+      return 1;
+    }
+    try {
+      const result = connectProjectTeam(ctx.db(), cwd, tokens, {});
+      reportTeam(ctx, result, ko);
+      return 0;
+    } catch (e) {
+      if (e && e.code === "team_agent_not_found") {
+        ctx.err((ko ? "에이전트를 찾을 수 없습니다: " : "agent not found: ") + e.token);
+        ctx.err(ctx.ui.dim(ko ? "설치된 에이전트: agentlas list" : "installed agents: agentlas list"));
+        return 1;
+      }
+      ctx.err(String((e && e.message) || e));
+      return 1;
+    }
+  }
+
+  ctx.err(ko
+    ? "사용법: agentlas project [status | init | use <에이전트> | team <에이전트>...]"
+    : "Usage: agentlas project [status | init | use <agent> | team <agent>...]");
   return 1;
 }
 

package/engine/commands/roles.cjs

@@ -35,9 +35,17 @@ function fmt(selection, en) {
   return bits.filter(Boolean).join(" ");
 }
 
-function show(ctx) {
+function show(ctx, args = []) {
   const en = ctx.lang === "en";
   const db = ctx.db();
+  if (args.includes("--json")) {
+    ctx.out(JSON.stringify({
+      orchestrator: resolvedModelRole(db, "orchestrator"),
+      worker: resolvedModelRole(db, "worker"),
+      pools: { orchestrator: roleMembers(db, "orchestrator"), worker: roleMembers(db, "worker") },
+    }, null, 2));
+    return 0;
+  }
   ctx.out(ctx.ui.bold(en ? "Model roles" : "모델 역할"));
   for (const role of ["orchestrator", "worker"]) {
     const resolved = resolvedModelRole(db, role);
@@ -170,7 +178,7 @@ function set(ctx, args) {
 function run(ctx, args = []) {
   const en = ctx.lang === "en";
   const [sub, ...rest] = args;
-  if (!sub || sub === "show" || sub === "list") return show(ctx);
+  if (!sub || sub === "show" || sub === "list" || sub === "--json") return show(ctx, sub === "--json" ? ["--json"] : rest);
   if (sub === "set") return set(ctx, rest);
   if (sub === "help" || sub === "--help" || sub === "-h") {
     // SELF_HELP_COMMANDS 계약: --help 는 스텁이 아니라 실제 안내여야 한다.