agentlas 1.0.28 → 1.0.35

package/engine/commands/help.cjs

@@ -5,6 +5,7 @@ const HELP = `agentlas — the operating system for agents, in your terminal
 
   agentlas                 open the terminal (REPL)
   agentlas "<task>"        run once with this project's controller
+  graph new "<what you want run for you>"   build an automation by talking it through
 
 PROJECT WORK
   run [agent] [prompt]     project-first one-shot; exact agent is an explicit advanced override
@@ -14,31 +15,35 @@ 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
+  roles [set <role> <rt>]  show or set orchestrator/worker model roles
   experience <sub>         portable Experience: list|inspect|validate|save|publish|status|export|unpublish
   variant resolve --base-release <id>   local variant selection (variant help)
 
 EXECUTE
   storm <goal>             Goal+UltraCode harness: plan → allocate → execute → verify  [--research]
   swarm <goal>             emergent agent swarm  [--parallel N]
-  workforce | network <request>   Agent Workforce Ontology route
+  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
   login | logout | whoami  Agentlas Cloud sign-in (browser flow)
   cloud <sub>              cloud assets: save|publish|package|list|restore|field-test
   automation <sub>         list|add|on|off|remove|run <id>|runs|daemon
+  graph <sub>              new "<what you want>"|list|show|run <name>|export|inspect|install
   creds <sub> · env        credentials and shared env keys
   usage · telegram · mcp   local usage · telegram bindings · MCP servers (mcp probe <id>)
   multimodal               image/video/audio provider settings
@@ -48,8 +53,9 @@ ACCOUNT & OPS
   version · help
 
 IN-REPL (agentlas → interactive, Orca multi-session)
-  /spawn <agent> [task] · /sessions · /tree · /s <n> · /steer <n> <msg> ·
-  /kill <n> · /rm <n> · /broadcast <msg> · /runtime · /model · /effort · /permission
+  /sessions · /tree · /s <n> | /switch <n> · /kill <n> · /rm <n>
+  /runtime <kind> · /model <id> · /effort <level> · /permission <level>   (applies to new sessions)
+  every command above also works as a slash command (/graph, /search, /automation, …) — /help lists them all
   typing during a running turn queues steering; ctrl-c interrupts the turn
 
 Options: -p|--print · --runtime claude-code|codex|gemini · --model <exact-id> ·
@@ -58,14 +64,86 @@ Options: -p|--print · --runtime claude-code|codex|gemini · --model <exact-id>
          --permission read|write|full
 `;
 
+/*
+ * 한국어판 — 2026-08-05 감사 결함 F: ko 세션에서 /help 본문이 전부 영어였다.
+ * 명령 이름·플래그는 원문(입력 어휘) 유지, 설명만 국문. HELP(영문)와 줄 구조를
+ * 맞춰 둔다 — runForCommand는 두 판 모두에서 같은 규칙으로 행을 찾는다.
+ */
+const HELP_KO = `agentlas — 터미널 속 에이전트 운영체제
+
+  agentlas                 터미널(REPL) 열기
+  agentlas "<작업>"        이 프로젝트의 컨트롤러로 1회 실행
+  graph new "<대신 시킬 일>"   대화로 설명하면 자동화를 만들어 줍니다
+
+PROJECT WORK
+  run [agent] [prompt]     프로젝트 우선 1회 실행; 특정 에이전트 지정은 명시적 고급 경로
+  firm <firm> [task]       회사 CEO에게 위임 (--runtime · --model · --effort)
+
+AGENTS & HUB
+  search "<필요한 것>"     Hub에서 에이전트 찾기
+  install <slug>           Hub 에이전트 설치
+  plugin add <slug> · plugin list      Hub 플러그인 (MCP 서버)
+  build "<요청>"           에이전트를 로컬에서 만들고 바로 설치
+  upload <path>            Agent Cloud에 소유자 비공개 저장 (--visibility marketplace 로 발행)
+  import <path> · cd · native prepare  로컬 폴더 에이전트
+  list                     설치 에이전트/회사 + 오케스트레이터·워커 런타임
+  roles [set <role> <rt>]  오케스트레이터·워커 모델 역할 조회/설정
+  experience <sub>         이동식 Experience: list|inspect|validate|save|publish|status|export|unpublish
+  variant resolve --base-release <id>   로컬 변형 선택 (variant help)
+
+EXECUTE
+  storm <goal>             Goal+UltraCode 하니스: 계획 → 배정 → 실행 → 검증  [--research]
+  swarm <goal>             창발형 에이전트 스웜  [--parallel N]
+  workforce | network <request>   Agent Workforce Ontology 편성 (공개 Hub 메뉴)
+  hep-network "<request>"  로컬+오너 클라우드+공개 Hub 연합 편성 (로컬 Core 연합)
+  hep-local | hep-cloud | hep-hub "<request>"   같은 편성, 한 소스 스코프로 제한
+  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 <sub>            이 폴더를 프로젝트로 연결 + 순서 팀 편성 (독립)
+                           (status · init · use <에이전트> · team <에이전트>…)
+  context <sub>            의존성 지도: refresh|locate|refs|slice|impact|verify
+
+ACCOUNT & OPS
+  login | logout | whoami  Agentlas Cloud 로그인 (브라우저 플로)
+  cloud <sub>              클라우드 자산: save|publish|package|list|restore|field-test
+  automation <sub>         list|add|on|off|remove|run <id>|runs|daemon
+  graph <sub>              new "<시킬 일>"|list|show|run <이름>|export|inspect|install
+  creds <sub> · env        자격증명·공유 env 키 (creds list 로 확인)
+  usage · telegram · mcp   로컬 사용량 · 텔레그램 연결 · MCP 서버 (mcp probe <id>)
+  multimodal               이미지/영상/음성 제공자 설정
+  doctor · setup · update  건강 점검 · 첫 실행 마법사 · npm 업데이트 확인
+  oberon | film <sub>      AI 필름 렌더 (scaffold|render|list|open)
+  hep <sub…> · netadmin    Hephaestus 패스스루 · 로컬 에이전트 네트워크
+  version · help
+
+IN-REPL (agentlas → 대화형, Orca 다중 세션)
+  /sessions · /tree · /s <n> | /switch <n> · /kill <n> · /rm <n>
+  /runtime <kind> · /model <id> · /effort <level> · /permission <level>   (새 세션부터 적용)
+  위의 모든 명령은 슬래시 명령(/graph, /search, /automation, …)으로도 됩니다 — 전체 목록은 /help
+  실행 중 입력하면 조종 큐에 쌓이고, ctrl-c 로 턴을 중단합니다
+
+Options: -p|--print · --runtime claude-code|codex|gemini · --model <exact-id> ·
+         --effort none|minimal|low|medium|high|xhigh|max ·
+         --tier economy|balanced|frontier (--model 필요) ·
+         --permission read|write|full
+`;
+
+function helpText(ctx) {
+  return ctx && ctx.lang === "ko" ? HELP_KO : HELP;
+}
+
 function run(ctx) {
-  ctx.out(HELP.trimEnd());
+  ctx.out(helpText(ctx).trimEnd());
   return 0;
 }
 
 function runForCommand(ctx, command) {
   const name = String(command || "").trim();
-  const rows = HELP.split("\n")
+  const rows = helpText(ctx).split("\n")
     .map((line) => line.trim())
     .filter((line) => line && !line.endsWith(":"))
     .filter((line) => {
@@ -83,4 +161,4 @@ function runForCommand(ctx, command) {
   return 0;
 }
 
-module.exports = { run, runForCommand, HELP };
+module.exports = { run, runForCommand, HELP, HELP_KO };

package/engine/commands/hep-cloud.cjs

@@ -1,31 +1,17 @@
 "use strict";
 /*
- * hep-cloud — 로그인한 오너의 Agent Cloud 에이전트만으로 임시 태스크포스 편성.
+ * hep-cloud — 소스 스코프(cloud) 편성, 터미널 네이티브 (2026-08-05 배선).
  *
- * WHY 이 파일이 따로 있는가 (2026-07-28 수리):
- *   COMMAND_ALIASES 가 `hep-cloud → cloud` 로 접혀 있었다. `cloud` 는 이름만 같은
- *   전혀 다른 명령 — 클라우드 자산 보관함(save|publish|package|list|restore|
- *   install|delete|field-test)이다. 그래서 `agentlas hep-cloud "<과제>"` 는
- *   과제를 서브커맨드로 읽고 `usage: agentlas cloud <save|…>` 를 뱉으며 exit 1 —
- *   hep-cloud 를 한 글자도 언급하지 않는 에러라 사용자에게 다음 수가 없었다.
- *   스코프(오너 Cloud 한정)를 실제로 지키는 표면은 Hephaestus 네이티브 런타임
- *   (`hephaestus hep-cloud`)뿐이므로 build/call/legacy-network 와 동일한
- *   패스스루 계약으로 그쪽에 넘긴다. 자산 보관함은 계속 `agentlas cloud …` 다.
- *
- * v1 인자 가드 그대로: help 토큰 → usage 0, 무인자 → usage 실패 exit 1.
+ * 이 이름은 두 번의 결함을 지나 여기 도착했다:
+ *   7/28  별칭이 스코프를 버려 엉뚱한 명령으로 접힘 → 외부 CLI 1급 승격
+ *   8/5   그 외부 CLI가 exit 3 스텁임이 드러남 → 삭제 → 자기 엔진에 재배선
+ * 실행 주체는 이 터미널의 편성 루프(리더 LLM이 WorkOrder 작성·정확 릴리스 선택),
+ * 메뉴 연합은 로컬 Agentlas-OS Core. 배선 상세는 commands/workforce.cjs 참조.
  */
-const { create, usageFor, isHelpToken } = require("../hephaestus/runtime.cjs");
+const { dispatch } = require("./workforce.cjs");
 
-async function run(ctx, args) {
-  if (args.some(isHelpToken)) {
-    ctx.out(usageFor("hep-cloud", ctx.lang));
-    return 0;
-  }
-  if (!args.length) {
-    ctx.err("✖ " + usageFor("hep-cloud", ctx.lang));
-    return 1;
-  }
-  return create(ctx).cmdHep(["hep-cloud", ...args]);
+function run(ctx, args) {
+  return dispatch(ctx, "hep-cloud", args);
 }
 
 module.exports = { run };

package/engine/commands/hep-hub.cjs

@@ -1,30 +1,17 @@
 "use strict";
 /*
- * hep-hub — 공개 Agentlas Hub 에이전트만으로 임시 태스크포스 편성.
+ * hep-hub — 소스 스코프(hub) 편성, 터미널 네이티브 (2026-08-05 배선).
  *
- * WHY 이 파일이 따로 있는가 (2026-07-28 수리):
- *   COMMAND_ALIASES 가 `hep-hub → search` 로 접혀 있었다. search 는 스태핑이 아니라
- *   마켓플레이스 디렉터리 나열이고(그마저 Cloud+Hub 혼합 표면이다), 실행은 하지
- *   않는다. 그래서 `agentlas hep-hub "<과제>"` 는 과제를 검색어로 읽고 슬러그
- *   목록만 찍은 뒤 exit 0 — 아무것도 실행하지 않고 성공한 척했다(가짜 성공 금지).
- *   공개 Hub 한정 스태핑을 실제로 수행하는 표면은 Hephaestus 네이티브 런타임
- *   (`hephaestus hep-hub`)이므로 그쪽에 그대로 넘긴다. 후보만 보고 싶으면
- *   기존 `agentlas search`(=hep-search)가 그대로 남아 있다.
- *
- * v1 인자 가드 그대로: help 토큰 → usage 0, 무인자 → usage 실패 exit 1.
+ * 이 이름은 두 번의 결함을 지나 여기 도착했다:
+ *   7/28  별칭이 스코프를 버려 엉뚱한 명령으로 접힘 → 외부 CLI 1급 승격
+ *   8/5   그 외부 CLI가 exit 3 스텁임이 드러남 → 삭제 → 자기 엔진에 재배선
+ * 실행 주체는 이 터미널의 편성 루프(리더 LLM이 WorkOrder 작성·정확 릴리스 선택),
+ * 메뉴 연합은 로컬 Agentlas-OS Core. 배선 상세는 commands/workforce.cjs 참조.
  */
-const { create, usageFor, isHelpToken } = require("../hephaestus/runtime.cjs");
+const { dispatch } = require("./workforce.cjs");
 
-async function run(ctx, args) {
-  if (args.some(isHelpToken)) {
-    ctx.out(usageFor("hep-hub", ctx.lang));
-    return 0;
-  }
-  if (!args.length) {
-    ctx.err("✖ " + usageFor("hep-hub", ctx.lang));
-    return 1;
-  }
-  return create(ctx).cmdHep(["hep-hub", ...args]);
+function run(ctx, args) {
+  return dispatch(ctx, "hep-hub", args);
 }
 
 module.exports = { run };

package/engine/commands/hep-local.cjs

@@ -1,32 +1,17 @@
 "use strict";
 /*
- * hep-local — 이 머신에 등록된 Local 에이전트만으로 임시 태스크포스 편성.
+ * hep-local — 소스 스코프(local) 편성, 터미널 네이티브 (2026-08-05 배선).
  *
- * WHY 이 파일이 따로 있는가 (2026-07-28 수리):
- *   COMMAND_ALIASES 가 `hep-local → workforce` 로 접혀 있었다. 터미널 workforce 는
- *   공개 Hub 메뉴로 스태핑하는 Agent Workforce Ontology 경로이고(엔드포인트:
- *   AGENTLAS_MCP_BASE_URL, search_candidates 스키마에 sourceScope 자체가 없음),
- *   cmdWorkforce 는 스코프 플래그를 받지 않는다. 즉 "등록된 로컬만" 이라고
- *   문서화된 명령이 조용히 Local+Cloud+공개 Hub 전체로 넓혀 실행됐다 —
- *   사용자가 의도하지 않은 Hub 크레딧 소모까지 포함해서. 스코프는 이름의 전부다.
- *   스코프를 지킬 수 있는 표면은 Hephaestus 네이티브 런타임(`hephaestus hep-local`)
- *   뿐이므로, build/call/legacy-network 와 동일한 패스스루 계약으로 그쪽에 넘긴다.
- *
- * v1 인자 가드 그대로: help 토큰 → usage 0, 무인자 → usage 실패 exit 1
- * (요청 문자열 없는 호출이 자연어 라우팅으로 새는 것 방지).
+ * 이 이름은 두 번의 결함을 지나 여기 도착했다:
+ *   7/28  별칭이 스코프를 버려 엉뚱한 명령으로 접힘 → 외부 CLI 1급 승격
+ *   8/5   그 외부 CLI가 exit 3 스텁임이 드러남 → 삭제 → 자기 엔진에 재배선
+ * 실행 주체는 이 터미널의 편성 루프(리더 LLM이 WorkOrder 작성·정확 릴리스 선택),
+ * 메뉴 연합은 로컬 Agentlas-OS Core. 배선 상세는 commands/workforce.cjs 참조.
  */
-const { create, usageFor, isHelpToken } = require("../hephaestus/runtime.cjs");
+const { dispatch } = require("./workforce.cjs");
 
-async function run(ctx, args) {
-  if (args.some(isHelpToken)) {
-    ctx.out(usageFor("hep-local", ctx.lang));
-    return 0;
-  }
-  if (!args.length) {
-    ctx.err("✖ " + usageFor("hep-local", ctx.lang));
-    return 1;
-  }
-  return create(ctx).cmdHep(["hep-local", ...args]);
+function run(ctx, args) {
+  return dispatch(ctx, "hep-local", args);
 }
 
 module.exports = { run };

package/engine/commands/hep-network.cjs

@@ -1,43 +1,17 @@
 "use strict";
 /*
- * hep-network — 등록된 Local + 오너 Cloud + 공개 Hub 를 연합해 임시 태스크포스 편성.
+ * hep-network — 소스 스코프(network) 편성, 터미널 네이티브 (2026-08-05 배선).
  *
- * WHY 이 파일이 따로 있는가 (2026-07-28 수리):
- *   COMMAND_ALIASES 가 `hep-network → workforce` 로 접혀 있었다. hep-local/hep-cloud/
- *   hep-hub 와 정확히 같은 결함이다 — 별칭은 이름만 바꿔주고 스코프는 어디에도
- *   전달하지 않는다. 터미널 workforce(cmdWorkforce)는 callHubTool 로
- *   AGENTLAS_MCP_BASE_URL(기본 https://agentlas.cloud/api/mcp/v1)을 직접 치고
- *   `{workOrder}` 만 보낸다(engine/agentlas-workforce.cjs:3043). 그 서버는
- *   sourceScope 가 없으면 "hub" 로 기본값을 잡는다
- *   (agentlas/AgentsAtlas/app/src/lib/mcp/workforce.ts:228). 결과:
- *
- *     - 로컬 에이전트와 오너 Cloud 에이전트는 후보 집합에 들어간 적이 없다.
- *     - 그런데 영수증의 로스터 핀은 전부 source:"hub" 로 기록된다
- *       (engine/workforce/deps.cjs). "네트워크 전량을 봤다" 로 읽힌다.
- *
- *   연합(federation)은 Core 가 소유한다: 세 소스 메뉴를 각각 받아 출처·계보를
- *   증명하고 하나의 CandidateSet 으로 합친 뒤, 선택은 호스트 LLM 이 한다. 터미널이
- *   Hub 를 직접 치는 경로에는 그 계층이 통째로 없다. 그래서 build/call/hep-local
- *   과 동일한 패스스루 계약으로 Hephaestus 네이티브 표면에 넘긴다.
- *
- *   `agentlas workforce` 자체는 남겨둔다 — 공개 Hub 스태핑을 그 이름으로 명시해
- *   부르는 것은 정직한 사용이다. 이름이 소스 스코프를 약속하는 hep-* 만 옮긴다.
- *
- * v1 인자 가드 그대로: help 토큰 → usage 0, 무인자 → usage 실패 exit 1
- * (요청 문자열 없는 호출이 자연어 라우팅으로 새는 것 방지).
+ * 이 이름은 두 번의 결함을 지나 여기 도착했다:
+ *   7/28  별칭이 스코프를 버려 엉뚱한 명령으로 접힘 → 외부 CLI 1급 승격
+ *   8/5   그 외부 CLI가 exit 3 스텁임이 드러남 → 삭제 → 자기 엔진에 재배선
+ * 실행 주체는 이 터미널의 편성 루프(리더 LLM이 WorkOrder 작성·정확 릴리스 선택),
+ * 메뉴 연합은 로컬 Agentlas-OS Core. 배선 상세는 commands/workforce.cjs 참조.
  */
-const { create, usageFor, isHelpToken } = require("../hephaestus/runtime.cjs");
+const { dispatch } = require("./workforce.cjs");
 
-async function run(ctx, args) {
-  if (args.some(isHelpToken)) {
-    ctx.out(usageFor("hep-network", ctx.lang));
-    return 0;
-  }
-  if (!args.length) {
-    ctx.err("✖ " + usageFor("hep-network", ctx.lang));
-    return 1;
-  }
-  return create(ctx).cmdHep(["hep-network", ...args]);
+function run(ctx, args) {
+  return dispatch(ctx, "hep-network", args);
 }
 
 module.exports = { run };

package/engine/commands/index.cjs

@@ -12,6 +12,7 @@ const path = require("node:path");
 const COMMANDS = {
   version: () => require("./version.cjs"),
   list: () => require("./list.cjs"),
+  graph: () => require("./graph.cjs"),
   doctor: () => require("./doctor.cjs"),
   mcp: () => require("./mcp.cjs"),
   help: () => require("./help.cjs"),
@@ -34,22 +35,24 @@ 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"),
+  // 소스 스코프 편성 4종 — 2026-08-05 네이티브 배선(경위는 workforce.cjs 참조).
+  // 별칭이 아니라 1급인 이유는 여전하다: 별칭은 스코프를 전달하지 못한다.
+  "hep-network": () => require("./hep-network.cjs"),
+  "hep-local": () => require("./hep-local.cjs"),
+  "hep-cloud": () => require("./hep-cloud.cjs"),
+  "hep-hub": () => require("./hep-hub.cjs"),
   oberon: () => require("./oberon.cjs"),
   film: () => require("./film.cjs"),
   experience: () => require("./experience.cjs"),
   memory: () => require("./memory.cjs"),
   evolve: () => require("./evolve.cjs"),
   variant: () => require("./variant.cjs"),
+  roles: () => require("./roles.cjs"),
   hep: () => require("./hep.cjs"),
-  // 소스 스코프 스태핑 3종은 1급 명령이다 — 별칭으로 접으면 스코프가 사라진다.
-  // (아래 COMMAND_ALIASES 주석의 2026-07-28 수리 참조.)
-  "hep-network": () => require("./hep-network.cjs"),
-  "hep-local": () => require("./hep-local.cjs"),
-  "hep-cloud": () => require("./hep-cloud.cjs"),
-  "hep-hub": () => require("./hep-hub.cjs"),
   build: () => require("./build.cjs"),
   connect: () => require("./connect.cjs"),
   call: () => require("./call.cjs"),
@@ -58,7 +61,6 @@ const COMMANDS = {
   research: () => require("./research.cjs"),
   netadmin: () => require("./netadmin.cjs"),
   journal: () => require("./journal.cjs"),
-  "legacy-network": () => require("./legacy-network.cjs"),
   cloud: () => require("./cloud.cjs"),
   upload: () => require("./upload.cjs"),
   storm: () => require("./storm.cjs"),
@@ -101,6 +103,18 @@ const DESKTOP_ONLY_SURFACES = {
   one: "Agentlas One is a separate Desktop/Mobile product surface.",
 };
 
+/*
+ * (2026-08-05 이력) hep-* 편성 이름들은 하루 동안 세 상태를 지났다:
+ *   ① 외부 CLI 스텁에 배선돼 exit 3 JSON만 뱉는 죽은 메뉴 → 삭제
+ *   ② 삭제 직후 "알 수 없는 토큰"이 되어 프롬프트로 낙하, 에이전트가 실제 기동
+ *      (상위 오타 가드는 한 단어 전용) → HOST_LLM_ONLY_SURFACES fail-closed 가드
+ *   ③ 같은 날 재조사에서 편성 세 조각(4,578줄 루프·로컬 Core MCP·D.callHubTool
+ *      주입 지점)이 전부 이 머신에 있음이 확인됨 → 네이티브 배선으로 복원,
+ *      가드 폐기. 전선 계약 실측과 배선은 workforce.cjs·local-core-transport.cjs.
+ * 남는 교훈: 이름을 지울 때는 반드시 낙하 경로까지 막고, "계층이 없다"는 판정은
+ * rg 로 확인한 뒤에 한다.
+ */
+
 // 무인자 호출이 프롬프트로 오라우팅되면 안 되는 명령 (smoke 가드 대상)
 const GUARDED_NO_ARG = new Set(["search", "install", "upload"]);
 
@@ -108,24 +122,16 @@ const GUARDED_NO_ARG = new Set(["search", "install", "upload"]);
 // 스킬명과 터미널 명령이 서로 다르면 사용자가 어느 표면에 있는지에 따라 이름을
 // 바꿔 써야 한다. 같은 기능은 어디서든 같은 이름으로 부른다.
 //
-// 불변식(2026-07-28 수리): 별칭은 "같은 기능"에만 건다. 소스 스코프를 이름에
-// 달고 있는 hep-local / hep-cloud / hep-hub 는 여기 넣으면 안 된다 — 별칭은
-// 이름만 바꿔주고 스코프는 어디에도 전달되지 않기 때문이다. 실제로 그랬다:
-//   hep-cloud → cloud      : 자산 보관함 명령. 과제 문자열을 서브커맨드로 읽어
-//                            `usage: agentlas cloud <save|…>` + exit 1.
-//   hep-local → workforce  : cmdWorkforce 는 스코프 플래그를 받지 않는다(전량
-//                            공개 Hub 메뉴 스태핑). "로컬 전용"이 조용히 넓어짐.
-//   hep-hub   → search     : 디렉터리 나열만 하고 아무것도 실행하지 않음.
-// 세 명령은 스코프를 실제로 지키는 Hephaestus 네이티브 표면으로 가는 1급 명령
-// (COMMANDS 의 hep-local/hep-cloud/hep-hub)으로 승격했다.
-//
-// 같은 이유로 hep-network 도 별칭에서 뺐다(2026-07-28). 이름은 "Local + owner
-// Cloud + public Hub"인데 cmdWorkforce 는 스코프를 어디에도 싣지 않고
-// agentlas.cloud/api/mcp/v1 을 직접 친다. 그 서버는 sourceScope 가 없으면 "hub"
-// 로 기본값을 잡으므로(agentlas/.../lib/mcp/workforce.ts:228) 로컬·클라우드
-// 에이전트는 후보에 들어간 적이 없는데 결과는 네트워크 전량을 본 것처럼 남았다.
-// 연합은 Core 가 소유한다 — 네이티브 표면으로 넘긴다.
+// 불변식: 별칭은 "같은 기능"에만 건다. 이름이 소스 스코프를 약속하는데 별칭이
+// 스코프를 버리면 제품이 거짓말을 한다 — 2026-07-28 에 실제로 그랬다
+// (hep-cloud→cloud 자산 보관함, hep-local→workforce 전량 Hub, hep-hub→search).
+// hep-network/hep-local/hep-cloud/hep-hub 는 그래서 여기 없다 — 스코프를 실제로
+// 관통시키는 1급 명령(COMMANDS)이다. 경위(스텁→삭제→네이티브 배선)는 위
+// 2026-08-05 이력 주석 참조.
 const COMMAND_ALIASES = {
+  // legacy-network는 역사적으로 hep-network를 뜻했다(v1 호환 탈출구). 이제
+  // hep-network가 네이티브이므로 같은 기능 별칭이 성립한다 — 스코프도 동일(network).
+  "legacy-network": "hep-network",
   "hep-build": "build",
   "hep-call": "call",
   "hep-search": "search",
@@ -139,6 +145,20 @@ function resolveCommandName(cmd) {
   return COMMAND_ALIASES[cmd] || cmd;
 }
 
+/**
+ * 자기 도움말을 직접 가진 명령들 — `<명령> --help` 는 이들에게 그대로 넘어간다.
+ *
+ * ★배경(실사용 실측 2026-08-06): 라우터가 `--help`를 가로채 도움말 표에서 한 줄을
+ *   긁어 보여줘서, `agentlas graph --help` 는 "Usage: agentlas graph [options]" 두 줄이
+ *   전부였다. 정작 `graph help` 에는 하위 명령 8개를 설명하는 제대로 된 안내가 있는데
+ *   **사용자가 가장 먼저 치는 철자(`--help`)로는 영원히 닿지 못했다.**
+ *
+ * 목록으로 두는 이유: 모든 명령에 "help"를 넘기면, 자기 도움말이 없는 명령은 그것을
+ * 인자로 읽는다(`agentlas run --help` 가 "help"라는 이름을 찾는 식). 추측하지 않는다.
+ * `test/command-help-contract.cjs` 가 이 목록과 실제 분기를 대조한다.
+ */
+const SELF_HELP_COMMANDS = new Set(["graph", "plugin", "billing", "roles", "native"]);
+
 function dispatch(ctx, argv) {
   const [rawCmd, ...rest] = argv;
   if (!rawCmd) return null; // 엔진이 REPL로 진입
@@ -164,6 +184,11 @@ function dispatch(ctx, argv) {
    * 이라 이 경로를 못 받는다. 여기가 유일한 차단 지점이므로 arity를 보지 않는다.
    * 진짜 작업이면 안내대로 따옴표로 묶어 하나의 프롬프트로 넘긴다.
    */
+  // (2026-08-05) HOST_LLM_ONLY_SURFACES 가드가 여기 있었다 — hep-* 네이티브
+  // 배선으로 표가 비면서 분기도 제거했다. 등록 명령을 지울 일이 다시 생기면
+  // 낙하 가드부터 만들 것: 상위 오타 가드는 한 단어 전용이라 인자가 붙은
+  // 삭제 이름은 프롬프트로 흘러 에이전트를 기동한다(실측·토큰 소모).
+
   if (DESKTOP_ONLY_SURFACES[cmd]) {
     const asTask = [rawCmd, ...rest].join(" ");
     ctx.err(`${DESKTOP_ONLY_SURFACES[cmd]}\nIt was not run as a prompt — rerun with quotes if you meant a task: agentlas "${asTask}"`);
@@ -182,4 +207,4 @@ function dispatch(ctx, argv) {
   return undefined; // 알 수 없는 토큰 — 엔진이 에이전트 이름/프롬프트로 해석 시도
 }
 
-module.exports = { dispatch, COMMANDS, COMMAND_ALIASES, resolveCommandName, NOT_YET_PORTED, GUARDED_NO_ARG, DESKTOP_ONLY_SURFACES };
+module.exports = { dispatch, COMMANDS, COMMAND_ALIASES, resolveCommandName, SELF_HELP_COMMANDS, NOT_YET_PORTED, GUARDED_NO_ARG, DESKTOP_ONLY_SURFACES };

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/mcp.cjs

@@ -80,11 +80,15 @@ async function probe(ctx, args) {
 function run(ctx, args = []) {
   const [sub, ...rest] = args;
   if (!sub) return list(ctx);
+  // 무인자 기본 동작이 목록인데 이름으로 부르면 거부되는 비대칭이 있었다
+  // (2026-08-05 감사 결함 G): 다른 명령들(cloud list, plugin list)이 만든
+  // "list를 붙이는" 습관이 여기서만 usage 오류가 됐다.
+  if (sub === "list" || sub === "ls") return list(ctx);
   if (sub === "probe") return probe(ctx, rest);
   const en = ctx.lang === "en";
   ctx.err(en
-    ? `unknown mcp subcommand: ${sub} (available: probe)`
-    : `알 수 없는 mcp 하위 명령: ${sub} (사용 가능: probe)`);
+    ? `unknown mcp subcommand: ${sub} (available: list · probe)`
+    : `알 수 없는 mcp 하위 명령: ${sub} (사용 가능: list · probe)`);
   return 1;
 }
 

package/engine/commands/native.cjs

@@ -8,9 +8,25 @@ function run(ctx, args) {
   const sub = String(args[0] || "help");
   const query = args[1];
   if (sub === "help" || sub === "--help" || sub === "-h") {
+    // SELF_HELP_COMMANDS 계약: --help 는 스텁이 아니라 실제 안내여야 한다 —
+    // 무엇이 만들어지고 언제 필요한지까지 말한다.
     ctx.out(ko
-      ? "사용법: agentlas native prepare <에이전트>  ·  네이티브 CLI 문맥 파일을 명시적으로 생성"
-      : "usage: agentlas native prepare <agent>  ·  explicitly create native CLI context files");
+      ? [
+        "agentlas native — 네이티브 CLI 문맥 파일 관리",
+        "  native prepare <에이전트>   에이전트 폴더에 CLAUDE.md·AGENTS.md 등",
+        "                             네이티브 CLI 문맥 파일을 명시적으로 생성",
+        "",
+        "  보통은 실행 시 자동 준비됩니다. 파일을 직접 확인·수정하고 싶을 때 쓰세요.",
+        "  에이전트 이름은 agentlas list 에서 확인합니다.",
+      ].join("\n")
+      : [
+        "agentlas native — native CLI context files",
+        "  native prepare <agent>     explicitly create the native CLI context files",
+        "                             (CLAUDE.md, AGENTS.md, …) in the agent folder",
+        "",
+        "  Normally these are prepared automatically on run. Use this when you want",
+        "  to inspect or edit the files directly. Find agent names via: agentlas list",
+      ].join("\n"));
     return 0;
   }
   if (sub !== "prepare" || !query) {

package/engine/commands/plugin.cjs

@@ -159,6 +159,28 @@ async function runPluginList(ctx, args) {
 
 function run(ctx, args) {
   const action = args[0];
+  // SELF_HELP_COMMANDS 계약(index.cjs): `plugin --help` 는 여기로 ["help"] 가 되어
+  // 들어온다. help 분기가 없으면 unknown action → usage exit 1 이라, 도움말을
+  // 요청한 사용자가 오류 코드를 받는다.
+  if (action === "help" || action === "--help" || action === "-h") {
+    const ko = ctx.lang !== "en";
+    ctx.out(ko
+      ? [
+        "agentlas plugin — Hub 플러그인(MCP 서버)",
+        "  plugin list [--project <경로>]   설치 가능/설치된 플러그인 목록",
+        "  plugin add <slug>               플러그인 설치 (slug는 list에서 확인)",
+        "",
+        "  연결 확인: agentlas mcp probe <server-id>",
+      ].join("\n")
+      : [
+        "agentlas plugin — Hub plugins (MCP servers)",
+        "  plugin list [--project <path>]   list available/installed plugins",
+        "  plugin add <slug>               install a plugin (find slugs via list)",
+        "",
+        "  Check a connection with: agentlas mcp probe <server-id>",
+      ].join("\n"));
+    return 0;
+  }
   if (action === "add") {
     if (args.length !== 2) {
       ctx.err("usage: agentlas plugin add <slug>   (run agentlas plugin list first)");