@vox-ai/cli-linux-x64 0.1.0-beta.2 → 0.1.0-beta.5

package/README.md

@@ -1,855 +1,124 @@
 # @vox-ai/cli
 
-vox.ai 에이전트 개발을 위한 CLI 워크플로우 도구입니다.
+vox.ai CLI for agent-as-code workflows.
 
-이 CLI는 넓은 API 래퍼가 아니라 에이전트 중심 워크플로우 도구입니다. North Star는 코딩 에이전트가 vox.ai agent를 코드처럼 다루게 하는 것입니다. 즉 파일을 편집하고, `vox` 명령의 `--json` 출력을 읽고, diff를 리뷰하고, git에 커밋하는 흐름을 1급으로 둡니다.
+`vox` lets you build, validate, diff, and ship [vox.ai](https://www.tryvox.co) voice agents as code. It is designed to be driven both by people in a terminal and by coding agents (Claude Code, Codex, and similar): edit JSON sources in your repo, read structured `--json` output, review diffs, and push when you are ready.
 
-## 한눈에 보기
+The CLI is the durable authoring surface — what belongs in your repo, gets reviewed, and can be reproduced or rolled back. The dashboard stays the viewer and admin surface.
 
-| 표면 | 역할 |
-| --- | --- |
-| `docs` | 현재 플랫폼 의미와 API 레퍼런스 조회 |
-| `skills` | 설계 playbook과 워크플로우 라우팅 |
-| `MCP` | stateless 조회와 일회성 작업 |
-| `vox CLI` | 레포에 남아야 하는 durable 저작, 검증, diff, push, status, delete |
-
-경계 규칙은 단순합니다. 레포에 남아야 하거나, 리뷰돼야 하거나, 재현/롤백돼야 하면 CLI를 사용합니다. 조회거나 일회성이면 MCP를 사용합니다.
-
-```text
-auth -> pull/init -> edit JSON -> doctor -> validate -> diff/status -> push -> version save -> promote -> mcp
-```
-
-## 목차
-
-- [설치와 업그레이드](#설치와-업그레이드)
-- [명령 지도](#명령-지도)
-- [Agent-as-Code](#agent-as-code)
-- [Tools-as-Code](#tools-as-code)
-- [Knowledge-as-Code](#knowledge-as-code)
-- [Flow 편집](#flow-편집)
-- [검증, diff, push](#검증-diff-push)
-- [개발](#개발)
-- [인증](#인증)
-- [MCP](#mcp)
-- [Listen / Trigger](#listen--trigger)
-
-## 설치와 업그레이드
-
-Public beta의 설치 채널은 npm과 Homebrew 두 가지입니다. npm은 Node 기반 cross-platform 채널이고, Homebrew는 macOS-first 단일 바이너리 채널입니다.
+## Install
 
 ```bash
-# npm stable
+# npm (cross-platform, requires Node >= 20.17)
 npm install -g @vox-ai/cli
 
-# npm beta
+# npm pre-release channel
 npm install -g @vox-ai/cli@beta
 
-# macOS Homebrew
+# Homebrew (macOS)
 brew install vox-public/tap/vox
 ```
 
-업그레이드는 package manager가 담당합니다.
+Verify the install:
 
 ```bash
-# npm stable
-npm install -g @vox-ai/cli@latest
-
-# npm beta
-npm install -g @vox-ai/cli@beta
-
-# Homebrew
-brew update
-brew upgrade vox-public/tap/vox
+vox --version
+vox --help
 ```
 
-`vox upgrade`는 첫 버전에서 self-update를 실행하지 않습니다. 대신 현재 설치 경로를 best-effort로 감지하고, npm registry의 `latest`/`beta` dist-tag를 확인한 뒤 실행해야 할 명령을 출력합니다.
+## Quick Start
 
 ```bash
-vox upgrade
-vox upgrade --channel beta
-vox upgrade --json
-```
-
-`--json` 출력은 코딩 에이전트가 다음 shell command를 결정할 수 있도록 `current_version`, `latest_version`, `update_available`, `install_source`, `upgrade_commands`를 포함합니다.
-
-## 명령 지도
-
-### 구현된 명령 그룹
-
-| 영역 | 명령 |
-| --- | --- |
-| Auth | `auth login`, `auth whoami`, `auth switch`, `auth logout` |
-| Config | `config get`, `config set` |
-| Health | `doctor` |
-| Init | `init` |
-| Guide / skills / docs | `guide coding-agent`, `guide flow`, `skills list`, `skills show`, `docs search`, `docs show` |
-| Sync reconciliation | `sync status`, `sync import --all` |
-| Agent authoring | `agent init`, `agent add`, `agent import`, `agent templates list`, `agent templates show`, `agent attach tool`, `agent attach knowledge`, `agent set`, `agent explain`, `agent pull`, `agent doctor`, `agent validate`, `agent diff`, `agent status`, `agent push`, `agent versions`, `agent version save`, `agent promote`, `agent delete` |
-| Agent tests | `agent test init`, `agent test list`, `agent test show`, `agent test validate` |
-| Flow authoring | `agent flow add-node`, `agent flow connect`, `agent flow set`, `agent flow set-global`, `agent flow remove-node`, `agent flow normalize`, `agent flow graph`, `agent node-types`, `agent node-schema` |
-| Tool source | `tool init`, `tool validate`, `tool explain`, `tool pull`, `tool diff`, `tool status`, `tool push`, `tool delete` |
-| Knowledge source | `knowledge init`, `knowledge add-document`, `knowledge validate`, `knowledge explain`, `knowledge pull`, `knowledge push`, `knowledge status`, `knowledge delete` |
-| Schema | `schema list`, `schema get` |
-| Chat beta | `chat` |
-| MCP | `mcp --list-tools`, `mcp --config`, `mcp --stdio` |
-| Version / upgrade | `version`, `--version`, `upgrade` |
-
-### 보류 중인 명령 그룹
-
-| 영역 | 상태 |
-| --- | --- |
-| `listen` / `trigger` | api-server SSE relay와 로컬 forwarding 구조는 확정했지만, api-server owner sync 전까지 구현은 보류합니다. |
-| runtime `test` | 현재 `agent test init/list/show/validate`는 레포에 남기는 로컬 테스트 스펙만 다룹니다. |
-
-### 명령별 도움말
-
-```bash
-vox agent --help
-vox init --help
-vox agent templates --help
-vox agent flow --help
-vox guide --help
-vox guide coding-agent --help
-vox guide flow --help
-vox docs --help
-vox docs search --help
-vox docs show --help
-vox schema --help
-vox chat --help
-vox agent doctor --help
-vox doctor --help
-vox upgrade --help
-vox agent validate --help
-vox tool --help
-vox knowledge --help
-```
-
-## Agent-as-Code
-
-### 새 agent 만들기
-
-새 프로젝트는 `vox init` 또는 `agent init`으로 만들고, 기존 프로젝트에 에이전트를 더 추가할 때는 `agent add`를 사용합니다. `vox init` / `agent init`은 root `CLAUDE.md`나 `AGENTS.md`를 만들지 않습니다. 대신 충돌이 적은 local skill bootstrap 파일을 `.claude/skills/vox-ai/SKILL.md`와 `.codex/skills/vox-ai/SKILL.md`에 생성합니다. 이미 같은 파일이 있으면 덮어쓰지 않으며, 원하지 않으면 `--no-agent-skills`를 사용합니다.
-
-```bash
-vox init --agent main --type flow
-vox agent init --agent main --type flow
-vox agent add support_router --template flow-router
-vox agent add support_api --template flow-api
-vox agent add support_api_sms --template flow-api-sms
-vox agent add support_tool --template flow-tool --tool crm_lookup
-vox agent add support_knowledge --template flow-knowledge --knowledge product_faq
-vox knowledge add-document product_faq overview --type text --text "Use dev endpoints for smoke tests."
-vox knowledge add-document product_faq docs --type webpage --url https://docs.tryvox.co
-```
-
-사용 가능한 로컬 템플릿은 다음처럼 확인합니다.
-
-```bash
-vox agent templates list
-vox agent templates show flow-api
-```
-
-현재 템플릿은 committed `agents/<name>/agent.json`을 바로 생성하는 authoring helper입니다. 원격에는 쓰지 않습니다. 원격 저장은 항상 `validate -> diff -> push` 루프를 거칩니다.
-
-`flow-api-sms`는 API 조회 성공 후 SMS 안내를 보내고, API/SMS 실패를 각각 fallback branch로 닫는 시작점입니다. `flow-tool`과 `flow-knowledge`는 `--tool` / `--knowledge`로 생성 시점에 로컬 리소스를 연결하거나, 나중에 각각 `agent attach tool --node lookup_customer`, `agent attach knowledge --node answer_with_knowledge`로 연결해 사용합니다. `--tool` / `--knowledge`를 쓰려면 해당 `tools/**/tool.json` 또는 `knowledges/**/knowledge.json` source가 먼저 있어야 합니다.
-
-### 기존 source 가져오기
-
-대시보드에서 export한 agent JSON이나 다른 레포의 CLI agent source를 현재 프로젝트로 가져올 때는 `agent import`를 사용합니다. 이 명령은 원격에 쓰지 않고 committed source 파일만 만듭니다.
-
-```bash
-vox agent import dashboard-export.json --agent support_router
-vox agent validate --agent support_router
-vox agent diff --agent support_router
-vox agent status --all --offline
-```
-
-대시보드 export envelope는 내부 `agent` payload만 `agents/<name>/agent.json`으로 정규화합니다. `vox_export_version`, `exported_at`, `source.agent_id` 같은 이전 환경의 export metadata와 remote binding은 커밋하지 않습니다. 이미 `.vox/project.json`에 remote binding이 있는 local name을 덮어쓰려면 `--force`가 필요하며, 이 경우 binding은 지워집니다.
-
-### Agent 설정 편집
-
-대시보드의 prompt, 변수, speech, call settings, webhook, post-call 같은 agent-level 설정은 committed `agent.json`의 `agent.data` 아래에 있습니다. 직접 JSON을 편집해도 되지만, 반복 작업이나 코딩 에이전트 workflow에서는 `agent set`으로 dot-path를 수정할 수 있습니다. 값은 JSON으로 파싱되고, `@file`은 프로젝트 상대 파일을 문자열로 읽습니다.
-
-```bash
-vox agent set --agent main \
-  --data prompt.prompt=@prompts/support.md \
-  --data prompt.firstLine="안녕하세요. 무엇을 도와드릴까요?" \
-  --data presetDynamicVariables.customer_tier=premium \
-  --data callSettings.callTimeoutInSeconds=600
-vox agent doctor --agent main
-vox agent validate --agent main
-vox agent diff --agent main
-```
-
-JSON 안의 특정 필드가 어떤 authoring 표면에 속하는지 확인하려면 `agent explain`, `tool explain`, `knowledge explain`을 사용합니다. 이 명령들은 원격을 호출하지 않고 committed source와 JSON Pointer만 읽습니다. 현재 값, 타입, agent flow node 또는 knowledge document context, 권장 CLI helper, 관련 검증 명령을 출력하므로 코딩 에이전트가 다음 편집을 결정하기 좋습니다.
-
-```bash
-vox agent explain /agent/data/prompt/prompt --agent main --json
-vox agent explain agents/main/agent.json /agent/flow_data/nodes/2/data --json
-vox tool explain crm_lookup /tool/response_mode --json
-vox knowledge explain product_faq /knowledge/documents/0/path --json
-```
-
-### Agent-facing guide
+# 1. Sign in (OAuth in your browser)
+vox auth login
+vox auth whoami --json
 
-`guide`는 docs/skills/schema를 매번 길게 검색하게 하지 않고, release 때 만든 압축 authoring pack과 운영 계약을 offline으로 반환합니다. 기본 목적은 사람이 아니라 코딩 에이전트가 다음 명령을 결정하도록 돕는 것입니다. 외부 repo에서 Codex/Claude가 README나 모노레포를 읽을 수 없다는 전제를 기본으로 둡니다.
+# 2. Read the operating contract (especially useful for coding agents)
+vox guide coding-agent
 
-```bash
-vox guide coding-agent --json
-vox guide coding-agent --target codex --json
-vox guide flow --list --json
-vox guide flow --topic global-node --json
-vox guide flow --task "user can quit anytime or ask for a human" --json
-vox skills list --json
-vox skills show using-vox-skills --brief --json
-vox skills show vox-flow --reference flow-guide --brief --json
-vox docs search "global node" --json
-vox docs show docs/build/flow/advanced/global-node --json
+# 3. Start a project — scaffold a new one, or import what already exists
+vox init
+# or, in an existing workspace:
 vox sync import --all --dry-run --json
-vox mcp --config --target codex --json
-vox mcp --config --target claude --json
-```
-
-`guide coding-agent` 출력은 surface split(docs/skills/MCP/CLI), 기본 Agent-as-Code 루프, repo instruction snippet, bundled guide topic 목록을 담습니다. 이것이 외부 세션의 bootstrap 명령입니다. 새 repo에 기존 workspace 전체를 처음 가져와야 한다면 `vox sync import --all --dry-run --json`으로 계획을 확인한 뒤 `vox sync import --all --json`을 실행합니다.
-
-`vox init` / `agent init`이 만든 `.claude/skills/vox-ai/SKILL.md`와 `.codex/skills/vox-ai/SKILL.md`도 같은 bootstrap 명령을 가리킵니다. Claude Code와 Codex가 각각 local skill 메커니즘으로 이 프로젝트의 vox.ai 작업 규칙을 발견하도록 하기 위한 파일이며, 고객 repo의 기존 root instruction 파일을 덮어쓰지 않습니다.
-
-`skills list/show`는 public `vox-skills` repo의 SKILL.md와 references를 release-time에 압축한 offline pack을 반환합니다. 긴 markdown을 바로 dump하지 않고 skill별 ownership, trigger, CLI-first 조건, 추천 명령, reference path, source hash를 주므로 코딩 에이전트가 먼저 어떤 playbook을 봐야 하는지 결정하기 좋습니다. 실제 긴 reference 전문이 필요하면 public skill 파일이나 docs/MCP layer로 이동합니다.
-
-`docs search/show`는 공식 docs repo를 release-time에 압축한 offline index를 반환합니다. `search`는 path/title/heading/관련 검색어/본문 excerpt를 대상으로 빠르게 후보를 찾고, `show`는 페이지 또는 섹션별 compressed excerpt와 public URL/source hash를 반환합니다. 전체 MDX 전문이나 최신 hosted 문서 확인이 필요할 때만 docs MCP 또는 웹 문서로 넘어갑니다.
-
-`guide flow` 출력은 적용 규칙, 관련 schema field, 권장 CLI 명령, 금지 패턴, 검증 명령, doctor code, source hash를 포함합니다. 예를 들어 `global-node` topic은 public skill의 global node 설계를 현재 v3 `data.globalNodeSettings` 필드와 `agent flow set-global` / `add-node --global-condition` helper로 연결합니다. 최신 hosted docs 조회가 필요하면 MCP/docs layer를 별도로 쓰고, durable source 편집은 `guide -> file edit/helper -> doctor -> validate -> diff -> push` 루프로 진행합니다.
-
-`mcp --config`는 Claude Code / Codex / generic MCP client가 `vox mcp --stdio` bridge를 등록할 수 있는 snippet을 출력합니다. 설정 파일에는 bearer token을 넣지 않습니다. 먼저 `vox auth login`으로 CLI profile/keychain에 로그인하고, agent MCP client는 로컬 stdio bridge만 실행합니다.
-
-### Chat beta
-
-`vox chat`은 dashboard/web의 LiveKit runtime 경로를 그대로 사용합니다. 기본 제품 surface는 production profile 기준이며, 일반 사용자가 dev/prod를 고르는 flag는 제공하지 않습니다. `--agent`는 원격 agent id 또는 현재 Agent-as-Code 프로젝트의 bound local agent name을 받습니다.
-
-```bash
-vox chat --agent <agent-id> --input "안녕하세요"
-vox chat --agent main --input "안녕하세요" --json
-vox chat --agent <agent-id>
-vox chat --agent <agent-id> --voice
-vox chat --agent <agent-id> --input "주문 상태 알려줘" --var customer_name=Acme --var-json order='{"id":"A-100","vip":true}'
-```
-
-`--debug`는 auth issuer, API base URL, livekit-token URL, LiveKit env, mode, agent id만 stderr에 출력합니다. OAuth access token, refresh token, LiveKit participant token은 출력하지 않습니다.
-
-`--var`와 `--var-json`은 dashboard chat의 `dynamic_variables`로 전달됩니다. `--var` 값은 문자열 그대로 보내고, `--var-json` 값은 JSON으로 파싱해 보냅니다.
-
-Voice mode uses the native LiveKit Node runtime plus SoX command-line audio I/O. On macOS, install SoX and grant Terminal microphone permission before the first smoke:
-
-```bash
-brew install sox
-vox chat --agent <agent-id> --voice --no-audio-output --debug
-```
-
-`--no-audio-output` is useful for a capture/publish smoke because it only requires microphone input. Full duplex voice playback also requires the `play` command from SoX.
-
-### Agent 테스트 스펙
-
-에이전트별 테스트 의도도 레포에 남길 수 있습니다. `agent test init`은 `agents/<agent>/tests/<name>.json`을 만들고, `agent test list` / `agent test show`는 PR 리뷰와 코딩 에이전트 탐색을 위해 로컬 테스트 스펙을 읽습니다. `agent test validate`는 그 파일의 스키마를 로컬에서 검증합니다.
-
-`agent test`는 실제 chat/voice runtime을 실행하지 않습니다. future `vox test` runner가 읽을 수 있는 durable test artifact를 먼저 남기는 용도입니다.
-
-```bash
-vox agent test init greeting_smoke --agent main \
-  --input "안녕하세요. 배송 상태를 확인하고 싶어요." \
-  --response-contains "배송" \
-  --response-not-contains "모르겠습니다" \
-  --max-turns 6
-vox agent test validate greeting_smoke --agent main
-vox agent test list --agent main
-vox agent test show greeting_smoke --agent main
-```
-
-생성되는 테스트 파일은 text scenario, preset variables, turns, assertions를 담습니다. 이 파일도 committed source이므로 PR에서 리뷰하고 CI에서 `agent test validate` 또는 `vox doctor`로 확인할 수 있습니다.
-
-`agent test list/show --json`은 테스트 이름, 파일 경로, turn/assertion 수, validation 상태를 안정적인 JSON으로 반환하므로 코딩 에이전트가 다음 작업을 결정하기 쉽습니다. `vox doctor`와 `vox agent doctor --agent <name>`도 `agents/<agent>/tests/*.json`을 함께 검사합니다. 따라서 public-skill/CI 기본 루프가 `doctor -> validate -> diff -> push`만 실행해도 깨진 테스트 스펙을 push 전에 잡을 수 있습니다.
-
-## Tools-as-Code
-
-### 로컬 tool source
-
-커스텀 도구는 `tool init`으로 로컬 source 파일을 만들고, `tool validate`로 committed JSON이 안전한지 확인합니다. `tool validate`는 서버 validate API가 아니라 CLI-local authoring validator입니다.
-
-`tool validate`는 이름/timeout처럼 서버가 확정적으로 거부하는 값과 민감 credential, placeholder URL, placeholder tool/parameter description, 그리고 `input_schema`의 root object type, `properties`, `required`, nested schema type 같은 흔한 JSON Schema authoring 오류를 먼저 잡습니다. 추가로 Draft 2020-12 meta-schema 검증을 실행해 `exclusiveMinimum`, `minItems`, `dependentSchemas` 같은 JSON Schema 키워드의 잘못된 타입/값도 원격 push 전에 잡습니다.
-
-실제 `tool push`는 placeholder URL과 placeholder tool/parameter description이 남아 있으면 원격 저장 전에 거부합니다. 또한 `response_mode: "fire_and_forget"`인 로컬 tool을 flow tool node가 결과 기반 transition 조건으로 사용 중이면 `tool push`가 원격 저장 전에 막습니다. 서버의 최종 요청 스키마와 비즈니스 방어 로직은 `tool push`의 create/update 단계에서 다시 적용됩니다.
-
-원격 tool도 agent와 같은 방식으로 `pull -> edit JSON -> validate -> diff/status -> push` 루프를 탑니다.
-
-### 지원 범위
-
-현재 CLI의 tools-as-code는 public v3 `POST /v3/tools` 계약에 맞춘 **HTTP/API 커스텀 도구**만 다룹니다.
-
-대시보드에 MCP 도구 생성 UI가 보이더라도, MCP 타입 도구는 아직 CLI 파일 리소스로 만들지 않습니다. public v3 생성/조회/수정 계약이 열리기 전에는 dashboard 또는 MCP one-off 작업으로 남기고, CLI가 v2/internal 모델을 우회 호출하지 않습니다.
-
-### Tool 워크플로우
-
-```bash
-vox tool init crm_lookup \
-  --url https://api.example.com/customers/lookup \
-  --header "content-type=application/json" \
-  --auth-type Bearer \
-  --auth-credentials '${secret:crm_api_token}' \
-  --timeout 20 \
-  --param "phone_number:string:고객 전화번호" \
-  --optional-param "customer_tier:string:고객 등급"
-vox tool validate crm_lookup
-vox tool push crm_lookup --dry-run
-vox tool push crm_lookup
-vox tool status crm_lookup
-vox agent attach tool main crm_lookup --node lookup_customer
-vox tool diff crm_lookup --offline --check
-vox tool pull <tool-id> --tool crm_lookup --update
 ```
 
-Tool source에는 literal bearer token, API key, auth credential을 넣지 마세요. 인증 값은 `${secret:crm_api_token}` 또는 `${env:CRM_API_TOKEN}` 형태의 reference로만 적어야 하며, `tool validate`가 민감 header/auth credential literal을 error로 막습니다.
+## Agent-as-Code Workflow
 
-`tool push`는 secret reference를 런타임에만 해석합니다. `--json` 출력, source file, `.vox` snapshot에는 raw secret을 쓰지 않습니다. 원격 tool ID, 마지막 원격 hash, snapshot 경로는 `.vox/project.json`의 `tool_bindings`에 저장되며 `.vox/`는 git에 커밋하지 않는 로컬 상태입니다.
-
-`tool status`는 읽기 전용 상태 점검입니다. 기본값은 원격 current tool을 조회해 local/remote drift를 나눠 보고하고, `--offline`은 인증과 네트워크를 건너뛰고 `.vox` snapshot만 기준으로 로컬 변경 여부를 봅니다. 실제 차이의 전체 JSON Pointer 목록이 필요하면 `tool diff`를 사용합니다.
-
-원격 tool을 정리할 때는 bound local name을 기준으로 삭제합니다. 실수 방지를 위해 `--yes`가 없으면 요청을 보내지 않습니다. 성공하면 원격 tool을 삭제하고 `.vox/project.json`의 binding과 snapshot만 제거하며, committed `tools/<name>/tool.json` source는 남깁니다.
-
-```bash
-vox tool delete crm_lookup --yes
-```
-
-### Agent에서 tool 참조하기
-
-Agent source에서 커스텀 tool을 참조할 때는 원격 UUID 대신 로컬 이름을 사용합니다.
-
-```json
-{
-  "type": "tool",
-  "data": {
-    "name": "Lookup Customer",
-    "toolRef": "crm_lookup"
-  }
-}
-```
-
-`agent attach tool`은 이 `toolRef`를 로컬 agent JSON에 기록합니다. `agent validate`, `agent diff`, `agent status`, `agent push`는 실행 시 `.vox/project.json`의 `tool_bindings`를 보고 `toolRef`를 실제 `toolId`로 컴파일합니다.
-
-따라서 agent source에는 org-local tool UUID를 커밋하지 않습니다. 단, `toolRef`가 가리키는 tool은 `agent validate` 또는 `agent push` 전에 `tool push`나 `tool pull`로 remote binding이 있어야 합니다.
-
-## Knowledge-as-Code
-
-### 로컬 knowledge source
-
-지식 베이스도 committed source와 로컬 바인딩을 분리합니다. `knowledge init`은 `knowledges/<name>/knowledge.json`을 만들고, `knowledge validate`는 문서 정의를 로컬에서 검증합니다. knowledge도 별도 서버 validate API를 호출하지 않습니다.
-
-`knowledge push`가 local knowledge 파일을 서버의 knowledge 생성 요청과 문서별 생성 요청으로 분해하고, 서버가 그 단계에서 최종 검증합니다.
-
-```bash
-vox knowledge init product_faq --name "Product FAQ"
-vox knowledge add-document product_faq overview --type text --name "Overview" --text "제품 FAQ 본문입니다."
-vox knowledge add-document product_faq docs --type webpage --url https://docs.tryvox.co
-vox knowledge add-document product_faq setup_guide --type file --path knowledges/product_faq/files/setup-guide.md
-vox knowledge validate product_faq
-vox knowledge push product_faq --dry-run
-vox knowledge push product_faq
-vox knowledge push product_faq --prune
-vox knowledge status product_faq
-vox agent attach knowledge main product_faq --node conversation
-```
+The core loop is a code workflow, not a sequence of dashboard clicks:
 
-이미 원격에 있는 knowledge base를 레포로 가져올 때는 별도 local name에 pull합니다.
-
-```bash
-vox knowledge pull 123 --knowledge product_faq
-vox knowledge status product_faq
-```
-
-현재 `knowledge-file.v1`은 JSON 안에 직접 담긴 `text` 문서, `webpage_urls` 문서, 그리고 레포 안의 파일을 가리키는 `file` 문서를 지원합니다. `knowledge add-document`는 세 타입의 source shape를 만들어주는 로컬 helper입니다. `file.path`는 프로젝트 루트 기준 상대 경로여야 하며, `knowledge validate`는 해당 파일이 실제로 존재하는지 확인합니다.
-
-```json
-{
-  "schema": "vox.ai.knowledge-file.v1",
-  "version": 1,
-  "knowledge": {
-    "name": "Product FAQ",
-    "documents": [
-      {
-        "local_id": "overview",
-        "name": "Overview",
-        "document_type": "text",
-        "text": "제품 FAQ 본문입니다."
-      },
-      {
-        "local_id": "docs",
-        "name": "Docs",
-        "document_type": "webpage",
-        "webpage_urls": ["https://docs.tryvox.co"]
-      },
-      {
-        "local_id": "setup_guide",
-        "name": "Setup Guide",
-        "document_type": "file",
-        "path": "knowledges/product_faq/files/setup-guide.md"
-      }
-    ]
-  }
-}
-```
-
-`knowledge push`는 remote knowledge base가 없으면 생성하고, `local_id`별 문서 hash를 `.vox/project.json`의 `knowledge_bindings`에 기록합니다. `file` 문서 hash에는 파일 내용 SHA도 포함되므로 파일 내용만 바뀌어도 `status`와 `push --dry-run`에서 변경으로 잡힙니다.
-
-바뀐 문서는 기존 remote document를 삭제한 뒤 다시 생성하고, unchanged 문서는 건너뜁니다. 기본값은 원격에만 있는 기존 문서를 보존합니다. 로컬 source에서 제거한 bound document를 원격에서도 삭제하려면 명시적으로 `--prune`을 붙입니다. 원격 knowledge ID와 document ID는 committed source에 쓰지 않습니다.
-
-`knowledge pull <knowledge-id> --knowledge <local-name>`은 대시보드나 MCP로 이미 만든 원격 knowledge base를 로컬 프로젝트에 바인딩합니다. 현재 v3 API의 document list 응답은 webpage URL summary만 원문 수준으로 복원할 수 있고, text 본문과 file binary는 반환하지 않습니다.
-
-따라서 text/file 문서가 있으면 기본값은 `KNOWLEDGE_PULL_INCOMPLETE`로 실패합니다. 원격 binding만 가져오고 복원 가능한 webpage 문서만 source에 쓰려면 명시적으로 `--allow-incomplete`를 붙입니다. 이 경우 `knowledge status`는 원격에 unmanaged document가 남아 있음을 `remote_changed`로 보여줍니다.
-
-`knowledge status`는 읽기 전용 상태 점검입니다. 기본값은 원격 document summary 목록을 조회해 바인딩된 문서가 사라졌는지, 대시보드 등에서 추가된 원격 문서가 있는지 확인합니다. `--offline`은 인증과 네트워크를 건너뛰고 `.vox/project.json`의 마지막 push hash만 기준으로 로컬 변경 여부를 봅니다. 서버 API가 document 본문을 반환하지 않기 때문에 원격 문서 내용 diff는 제공하지 않습니다.
-
-원격 knowledge base를 정리할 때도 bound local name을 기준으로 삭제합니다. 실수 방지를 위해 `--yes`가 없으면 요청을 보내지 않습니다. 성공하면 원격 knowledge base를 삭제하고 `.vox/project.json`의 knowledge/document binding만 제거하며, committed `knowledges/<name>/knowledge.json` source는 남깁니다.
-
-```bash
-vox knowledge delete product_faq --yes
-```
-
-### Agent에서 knowledge 참조하기
-
-Agent source에서 knowledge를 참조할 때는 숫자 `knowledgeIds` 대신 로컬 이름을 사용합니다.
-
-```json
-{
-  "data": {
-    "knowledge": {
-      "ragEnabled": true,
-      "knowledgeRefs": ["product_faq"]
-    }
-  }
-}
+```text
+pull / init  ->  edit JSON files  ->  doctor / validate  ->  diff / status  ->  push  ->  version save / promote
 ```
 
-flow agent는 conversation node의 `data.knowledge.knowledgeRefs`에도 같은 방식으로 기록할 수 있습니다. `agent validate`, `agent diff`, `agent status`, `agent push`는 실행 시 `.vox/project.json`의 `knowledge_bindings`를 보고 `knowledgeRefs`를 실제 `knowledgeIds`로 컴파일합니다.
+- `vox agent pull` / `vox init` — bring remote agents into local JSON source.
+- Edit the JSON files in your editor or with a coding agent.
+- `vox agent doctor` / `vox agent validate` — catch authoring risks before you push.
+- `vox agent diff` / `vox agent status` — review exactly what will change.
+- `vox agent push` — apply your local source to the remote draft.
+- `vox agent version save` / `vox agent promote` — snapshot an immutable version and promote it to production.
 
-단, `knowledgeRef`가 가리키는 지식 베이스는 `agent validate` 또는 `agent push` 전에 `knowledge push`나 `knowledge pull`로 remote binding이 있어야 합니다.
+## Commands
 
-아직 지원하지 않는 범위: 기존 remote knowledge의 display name 업데이트, text/file document 원문 pull.
+A high-level map of the public surface. Run any command with `--help` for details, or add `--json` for structured output.
 
-## Flow 편집
-
-### Mutation helper
-
-flow를 로컬에서 확장할 때는 mutation helper로 committed `agent.json`을 수정한 뒤 graph/doctor/validate로 확인합니다.
-
-```bash
-vox agent flow add-node check_account --type api \
-  --url https://api.example.com/check \
-  --method POST \
-  --header "content-type=application/json" \
-  --response-mode wait \
-  --body-file prompts/check-account-body.json \
-  --response-variable "account_status=$.status"
-vox agent flow connect --from conversation --to check_account --condition "API 조회가 필요할 때"
-vox agent flow set --node check_account --data apiConfiguration.timeoutSeconds=20
-vox agent flow add-node stop_end --type endCall \
-  --static-sentence "네, 설문을 종료하겠습니다." \
-  --global-condition "사용자가 중단, 종료, 그만, 끊기를 요청할 때"
-vox agent flow set-global --node stop_end --condition "사용자가 중단, 종료, 그만, 끊기를 요청할 때"
-vox agent flow normalize
-vox agent flow graph
-vox agent flow graph --format outline
-vox agent flow graph --format summary
-```
-
-`agent flow add-node`, `agent flow connect`, `agent flow set`, `agent flow set-global`, `agent flow remove-node`, `agent flow normalize`는 committed `agent.json`만 수정하는 로컬 mutation helper입니다.
-
-현재 `add-node`는 `conversation`, `api`, `tool`, `extraction`, `condition`, `sendSms`, `transferCall`, `transferAgent`, `endCall`, `note`를 지원합니다.
-`--global-condition`은 실행 노드의 `data.globalNodeSettings = { isGlobalNode: true, transitionCondition }`를 설정합니다. 이미 만든 노드는 `agent flow set-global --node <id> --condition <text>`로 같은 설정을 적용하고, `--clear`로 비활성화합니다. `agent doctor`는 종료/중단/상담원 연결 같은 조건이 여러 노드에서 같은 end/transfer 노드로 반복 연결되면 `GLOBAL_NODE_CANDIDATE` 경고를 냅니다.
-
-| Node | 지원 내용 |
+| Area | Commands |
 | --- | --- |
-| `conversation` | `--prompt` / `--first-message`로 dynamic node를 만들거나 `--static-sentence`로 static node를 만듭니다. |
-| `note` | `--content`로 flow authoring 메모를 남기는 비실행 노드입니다. |
-| `api` | `--header`, `--body`/`--body-file`, `--response-variable`, `--timeout`, `--auth-type`, `--auth-credentials`, `--response-mode`로 자주 쓰는 HTTP 설정을 처음부터 넣을 수 있습니다. |
-| `sendSms` | `--response-mode`, `--sms-title`, `--sms-from-number`, `--sms-image-key`를 지원합니다. |
-| `transferCall` | `--transfer-mode`, `--transfer-message-type`, `--warm-transfer-prompt`, `--warm-transfer-static-sentence`, `--displayed-caller-id`, `--sip-header`를 지원합니다. |
-| `extraction` | skip-user-response transition을 자동 생성합니다. |
-| `condition` | logical transition 골격을 만듭니다. |
-| `sendSms` / `transferCall` / `transferAgent` | canonical fallback transition을 포함합니다. |
-
-`api` node의 `--auth-credentials`와 `authorization`/`x-api-key` 같은 민감 `--header` 값은 literal secret을 받지 않고 `${env:NAME}` / `${secret:name}` reference만 허용합니다. `apiConfiguration.url`, `authCredentials`, `headers`, `body` 안의 `${env:NAME}` / `${secret:name}` reference는 `agent validate` / `agent push` 시 서버 payload에서만 실제 값으로 해석되고, committed `agent.json`, dry-run JSON, `.vox` snapshot에는 reference 형태로 복원됩니다.
-
-`transferCall`/`transferAgent`는 실제 전화/SIP 대상 또는 agent_id가 필요하므로 placeholder로 만든 경우 `agent doctor`/`agent validate`에서 반드시 교정해야 합니다.
-
-`connect`는 `--from node:transition`처럼 기존 transition handle을 쓰거나, `--condition` / `--fallback`으로 source node에 새 transition을 만들고 edge를 추가합니다. `set`은 node `data` 아래 dot-path를 수정하며 값은 JSON으로 파싱되고, `@prompts/support.md`처럼 프로젝트 상대 파일을 문자열로 읽을 수 있습니다. `remove-node`는 begin node 삭제를 막고 incident edge 및 더 이상 쓰이지 않는 source transition을 정리합니다. `normalize`는 missing position/data, edge `type: "custom"`, target handle, stale edge 같은 editor-safe 구조를 보정합니다.
-
-변경 후에는 `agent flow graph`, `agent doctor`, `agent validate` 순서로 확인하세요.
-
-### Schema introspection
-
-flow node나 agent schema 필드를 확인할 때는 스키마 introspection 명령을 사용합니다. 이 명령들은 read-only이며 원격 리소스를 생성하거나 수정하지 않습니다.
-
-```bash
-vox agent node-types
-vox agent node-schema api --detail standard
-vox schema list --namespace flow-schema --category flow-node
-vox schema get flow-schema flow-data --detail minimal
-```
-
-### Graph review
+| Auth & config | `auth login`, `auth whoami`, `auth switch`, `auth logout`, `config get/set` |
+| Get started | `init`, `doctor`, `guide coding-agent`, `guide flow` |
+| Discover offline | `docs search/show`, `skills list/show`, `schema list/get` |
+| Authoring | `agent …`, `tool …`, `knowledge …` (plan, create, edit, validate, diff, push, version, promote) |
+| Sync | `sync status`, `sync import`, `sync bootstrap` |
+| Multi-org | `org list`, `org switch`, `workspace init` |
+| Runtime & telephony | `chat`, `call …`, `number …`, `version`, `upgrade` |
 
-`agent flow graph`는 committed agent source의 `flow_data.nodes` / `edges`를 Mermaid, outline, summary로 렌더합니다. `outline`은 각 node의 transition 조건, 연결 target, local `toolRef` / `knowledgeRefs`, unreachable node를 같이 보여주므로 복잡한 flow를 dashboard 없이 리뷰할 때 쓰기 좋습니다.
+## Using vox from Coding Agents
 
-`--json` 출력에는 nodes, edges, transitions, resource_refs, unreachable_nodes, mermaid, outline 문자열이 함께 들어가므로 코딩 에이전트가 현재 flow topology를 파싱한 뒤 다음 편집을 결정할 수 있습니다. 이 명령은 로컬 파일만 읽고 `.vox`나 원격을 수정하지 않습니다.
-
-## 검증, diff, push
-
-### Validate
-
-`agent validate`는 기본적으로 로컬 JSON shape 검증 후 flow agent에 대해 api-server의 canonical flow validator를 호출합니다. 따라서 기본 검증은 OAuth 인증이 필요하고, 서버가 반환하는 warning/error 및 `fixed_flow_data`를 반영합니다.
-
-인증 없이 편집 중인 JSON 구조만 빠르게 확인하려면 다음처럼 실행합니다.
-
-```bash
-vox agent validate --offline
-```
-
-`--offline`은 서버 flow validation을 명시적으로 건너뜁니다. 이 모드는 publish/push 직전 검증을 대체하지 않으며, `--fix`와 함께 사용할 수 없습니다.
-
-### Doctor
-
-편집 중인 JSON이 "빌드 가능한 프로젝트"에 가까운지 로컬에서 먼저 점검하려면 `doctor`를 사용합니다.
-
-`vox doctor`는 모든 로컬 agent source와, agent가 직접 참조하지 않아도 `tools/**/tool.json` / `knowledges/**/knowledge.json` 아래에 있는 resource source를 함께 검사합니다. 특정 agent만 볼 때는 `agent doctor --agent <name>`을 사용합니다.
-
-기본 모드는 네트워크를 쓰지 않고, placeholder API URL, literal secret, `agent flow add-node`가 만든 `TODO_*` 골격, 누락된 fallback/skip transition, dangling edge, 비어 있는 `toolId`/`knowledgeIds` 같은 authoring 위험을 잡습니다. 로컬 `toolRef` / `knowledgeRefs`가 있으면 `.vox/project.json`의 remote binding과 `tools/**/tool.json` / `knowledges/**/knowledge.json` source 파일도 함께 확인합니다.
-
-`agent push`도 마지막 안전망을 둡니다. literal secret이 agent JSON에 직접 들어 있으면 dry-run 포함 즉시 거부하고, placeholder API URL, helper가 만든 TODO 노드 텍스트/조건/SMS/transfer 대상, 비어 있는 tool/knowledge 참조가 남아 있으면 실제 원격 저장 전에 거부합니다. 로컬 flow가 `fire_and_forget` custom tool의 늦게 오는 결과를 transition 조건으로 분기하려는 경우도 `agent doctor`, `vox doctor`, 실제 `agent push`, 실제 `tool push`에서 같은 코드로 막습니다.
-
-placeholder 상태의 payload를 검토해야 할 때는 `agent push --dry-run --json`으로 먼저 확인하고, 실제 저장 전에는 `agent doctor` 경고를 해소하세요.
-
-현재 로그인/profile이 이 프로젝트의 `.vox/project.json`과 맞는지도 같이 확인하려면 `--live`를 붙입니다. 이 모드는 OAuth context를 resolve해서 `.vox`에 기록된 profile/organization과 비교하고, `.vox`에 저장된 agent/tool/knowledge remote binding이 현재 organization에서 조회 가능한지도 확인합니다. 따라서 잘못된 워크스페이스나 stale binding으로 `validate`/`push`하기 전 조기 경고로 사용할 수 있습니다.
-
-```bash
-vox doctor
-vox agent doctor
-vox agent doctor --agent support_api
-vox agent doctor --live --json
-```
-
-`doctor`는 error가 있으면 exit `1`, warning만 있으면 exit `0`입니다. 서버 canonical validation을 대체하지 않으므로 실제 저장 전에는 `agent validate`와 `agent push --dry-run`을 이어서 실행하세요.
-
-### Sync status
-
-`sync status`는 `vox agent pull`의 대체 명령이 아니라 workspace reconciliation oracle입니다. 로컬 `vox.json`, `agents/**/agent.json`, `tools/**/tool.json`, `knowledges/**/knowledge.json`, `.vox/project.json` binding/snapshot hash, 현재 remote organization inventory를 읽어서 지금 pull/edit/push가 안전한지 판단합니다. agent, tool, knowledge resource를 같은 `vox.ai.sync-status.v1` 계약의 `resources[].type`으로 반환하며 파일과 remote state를 쓰지 않는 read-only 명령입니다.
-
-```bash
-vox sync status
-vox sync status --json
-vox sync status --profile dev --org <organization-id> --json
-```
-
-`--json`의 `data.schema`는 `vox.ai.sync-status.v1`입니다. 각 resource는 `state`, `risk`, `evidence`, `recommended_actions`, `blocked_actions`를 포함하므로 Codex/Claude 같은 coding agent는 이 출력을 durable 작업의 첫 판단 기준으로 삼을 수 있습니다. 개별 agent 업데이트는 계속 `vox agent pull --agent <local-agent> --update`가 담당합니다. `vox sync pull --agent`, `vox sync push`, `vox sync apply` 같은 mutation surface는 제공하지 않습니다.
-
-`agent push`는 같은 classifier를 push guard로 재사용합니다. `remote_changed`, `diverged`, `missing_snapshot`, `binding_stale`, `remote_missing`, `invalid_local`, `remote_error` 상태에서는 기본 push가 막히며, 로컬과 원격이 둘 다 바뀐 상태를 눈으로 diff/review하지 않고 덮어쓰는 경로를 닫습니다.
-
-### Sync import
-
-`sync import --all`은 새 repo 초기셋업용 bulk bootstrap입니다. 순차적으로 `vox agent pull <id> --agent <name>`을 반복하지 않고 현재 organization의 remote agent inventory를 안전한 local name으로 materialize합니다. 실제 쓰기 전에는 항상 dry-run으로 계획을 확인하세요.
-
-```bash
-vox sync import --all --dry-run --json
-vox sync import --all --json
-vox sync import --all --profile dev --org <organization-id> --json
-```
-
-현재 import는 agents를 `agents/<local-name>/agent.json`, `.vox/snapshots/<local-name>.remote.json`, `vox.json`, `.vox/project.json`으로 씁니다. 이미 같은 local source path가 있으면 덮어쓰지 않고 `LOCAL_SOURCE_CONFLICT`로 멈춥니다. tool/knowledge는 아직 materialize하지 않고 `unsupported_inventory`에 남기며, 이후 `vox tool pull <tool-id> --tool <local-name>` 또는 `vox knowledge pull <knowledge-id> --knowledge <local-name>`로 가져옵니다.
-
-### Diff와 status
-
-`agent diff`는 기본적으로 현재 원격 에이전트를 다시 조회한 뒤 로컬 JSON과 비교합니다. 인증 없이 마지막 `pull`/`push` snapshot 대비 변경만 보고 싶으면 다음처럼 실행합니다.
-
-```bash
-vox agent diff --offline
-```
-
-`--offline`은 `.vox/snapshots/<agent>.remote.json`을 기준으로 사용합니다. snapshot이 없거나 손상되어 있으면 `agent pull --agent <local-agent> --update` 또는 온라인 `agent diff`가 필요합니다. 새 원격 에이전트를 처음 가져올 때는 `agent pull <agent-id> --agent <local-agent>`를 쓰고, 이미 바인딩된 local agent를 다시 동기화할 때는 agent id 없이 `agent pull --agent <local-agent>`를 사용할 수 있습니다.
-
-CI나 스크립트에서 변경 여부를 exit code로 판단하려면 다음처럼 실행합니다.
-
-```bash
-vox agent diff --check
-vox agent diff --offline --check
-vox agent diff --all --offline --check
-```
-
-기본 `agent diff`는 diff 계산이 성공하면 변경이 있어도 exit `0`입니다. `--check`는 변경이 있으면 결과 JSON을 출력한 뒤 exit `1`을 반환합니다. `--all`을 붙이면 `vox.json`에 선언된 모든 local agent를 순회하며, 바인딩이 없거나 snapshot이 없는 agent는 전체 명령을 중단하지 않고 per-agent error로 남깁니다. `--all --check`는 변경 또는 per-agent error가 하나라도 있으면 exit `1`입니다.
-
-현재 작업 디렉터리 상태를 인증 없이 확인하려면 다음처럼 실행합니다.
-
-```bash
-vox agent status --offline
-vox agent status --all --offline
-```
-
-`agent status --offline`은 마지막 snapshot 기준으로 로컬 변경 여부를 계산하고, 원격 최신 변경 여부는 조회하지 않습니다. `--all`을 붙이면 `vox.json`에 선언된 모든 local agent의 상태와 summary를 한 번에 출력합니다. 원격 drift까지 확인하려면 기본 `agent status`를 사용합니다.
-
-### Push
-
-인증 없이 push payload 모양만 확인하려면 다음처럼 실행합니다.
-
-```bash
-vox agent push --dry-run --offline
-```
-
-`agent push --dry-run --offline`은 로컬 agent JSON과 저장된 snapshot만 사용합니다. bound agent는 snapshot 기준 update payload를, unbound agent는 create payload를 미리 보여줍니다. 이 모드는 서버 flow validation과 원격 drift 확인을 수행하지 않으므로 실제 저장 전에는 온라인 `agent push --dry-run` 또는 `agent push`를 사용해야 합니다. 실제 push는 `--offline`과 함께 실행할 수 없습니다.
-
-온라인 `agent push --dry-run`과 `agent push`는 flow agent에 대해 서버 validator의 `fixed_flow_data`가 반환되면 그 값을 create/update payload에 사용합니다. `--dry-run`은 파일을 수정하지 않습니다.
-
-실제 `agent push`가 성공하면 저장된 서버 응답으로 `agents/<name>/agent.json`과 `.vox` snapshot을 함께 갱신합니다. 서버 기본값이나 validator fix가 적용되어도 push 직후 `agent diff`가 clean이 되도록 하기 위한 동작입니다. push 전에 validator fix만 파일에 반영하고 싶으면 `vox agent validate --fix`를 사용하세요.
-
-### Version과 promote
-
-버전 저장과 프로덕션 승격은 push와 분리합니다. `agent version save`는 현재 원격 draft를 immutable version으로 저장하고, `agent promote`는 이미 저장된 `vN`만 프로덕션 포인터로 올립니다. 프로덕션 라우팅을 바꾸는 명령이므로 `--yes` 없이는 요청을 보내지 않습니다.
-
-```bash
-vox agent versions --agent main
-vox agent version save --agent main --description "2026-06-24 support flow update"
-vox agent promote v3 --agent main --yes
-```
-
-권장 릴리스 루프는 `agent status -> agent diff -> agent push -> agent version save -> agent promote`입니다. 버전 메타데이터와 프로덕션 포인터는 원격 운영 상태라 committed `agent.json`에는 쓰지 않습니다. 로컬 source는 current draft의 desired state만 담고, 원격 agent ID와 snapshot hash는 `.vox/project.json`과 `.vox/snapshots/`에만 남깁니다.
-
-### Delete
-
-원격 에이전트를 정리할 때는 soft-delete만 지원합니다. 실수 방지를 위해 `--yes`가 없으면 요청을 보내지 않습니다.
-
-```bash
-vox agent delete <agent-id> --yes
-```
-
-## 개발
-
-### 기본 검증 루프
-
-```bash
-npm install
-npm run package:info:check
-npm run guide:pack:check
-npm run skills:pack:check
-npm run docs:pack:check
-npm run codegen:check
-npm run tool:constraints:check
-npm run homebrew:formula:smoke
-npm run mcp:surface:check
-npm run typecheck
-npm test
-npm run build
-npm run smoke:help
-npm run smoke:version
-npm run smoke:whoami-json
-npm run smoke:agent-diff-check
-npm run smoke:authoring-local
-npm run smoke:npm-pack
-npm run bun:compile
-npm run smoke:help-binary
-npm run smoke:agent-diff-check-binary
-npm run smoke:authoring-local-binary
-npm run smoke:mcp-binary
-```
-
-### 내부 chat dev smoke
-
-공개 CLI surface는 production 기본값을 유지합니다. dev 연결은 내부 profile/env override로만 검증합니다.
-
-확인된 dev 연결 값:
-
-- auth issuer: `https://xnpknkzxxuyfokbrzbil.supabase.co/auth/v1`
-- livekit-token URL: `https://xnpknkzxxuyfokbrzbil.supabase.co/functions/v1/livekit-token`
-- API base: `https://dev-client-api.tryvox.co`
-- MCP base: `https://vox-mcp-develop.fly.dev`
-- MCP endpoint for CLI `mcp_url`: `https://vox-mcp-develop.fly.dev/mcp`
-- dev smoke workspace: `aacc5a24-4fdf-40cc-8d75-6abd253146ea`
-
-dev profile 생성:
+`vox` is built to be a first-class tool for coding agents. Point your agent at these bootstrap commands:
 
 ```bash
-VOX_AUTH_ISSUER=https://xnpknkzxxuyfokbrzbil.supabase.co/auth/v1 \
-VOX_API_BASE_URL=https://dev-client-api.tryvox.co \
-VOX_MCP_URL=https://vox-mcp-develop.fly.dev/mcp \
-vox auth login --profile dev
+vox guide coding-agent --json     # the operating contract to follow
+vox docs search "<query>" --json  # offline official docs
+vox skills list --json            # design playbooks and workflow routing
+vox schema get <namespace> <schema-type> --json
 ```
 
-dev profile 검증:
+Every command accepts `--json` and emits a stable envelope (`{ ok, data }` on success, `{ ok: false, error: { code, message, … } }` on failure), so agents and automation can branch on results, read `error.details.hint`, and follow `related_commands`.
 
-```bash
-vox auth whoami --profile dev --json
-```
+## Authentication
 
-chat dev smoke는 env token을 거부하고 `--profile dev`를 요구합니다. 내부 LiveKit env는 script가 `VOX_INTERNAL_LIVEKIT_ENV=development`로 고정합니다.
+- vox uses **OAuth only**. `vox auth login` opens your browser and completes a loopback flow.
+- Refresh tokens are stored in your OS keychain / secret store — never in project files.
+- Project and workspace JSON never contain tokens or secrets.
 
-```bash
-npm run smoke:chat-dev -- --profile dev --agent <dev-agent-id> --input "hello from vox-cli dev smoke"
-```
+## Telemetry and Privacy
 
-Deterministic dev agents can assert response content so truncated or ungrounded answers fail the smoke:
+Official builds send anonymous usage telemetry to help improve the CLI. It records coarse signals such as the command name, exit status, CLI version, and OS — never your arguments, file contents, tokens, agent data, or organization identifiers.
 
-```bash
-npm run smoke:chat-dev -- --profile dev --agent <dev-agent-id> \
-  --input "Return the dev API base. Do not use markdown code fences." \
-  --expect-output "https://dev-client-api.tryvox.co"
-```
-
-For multi-turn dev checks, repeat `--turn`; the smoke sends the next turn after an assistant response:
+Opt out at any time:
 
 ```bash
-npm run smoke:chat-dev -- --profile dev --agent <dev-agent-id> \
-  --turn "What is the dev API base?" \
-  --turn "What command saves an agent version?" \
-  --expect-output "https://dev-client-api.tryvox.co" \
-  --expect-output "vox agent version save"
+vox config set settings.telemetry disabled
+# or, per-process:
+DO_NOT_TRACK=1 vox …
+VOX_TELEMETRY_DISABLED=1 vox …
 ```
 
-`VOX_LIVEKIT_TOKEN_URL`은 dev issuer 파생이 불확실한 경우의 escape hatch로 유지하지만, 일반 사용자 문서 경로로 사용하지 않습니다.
-
-### 생성물 체크
-
-v3 OpenAPI 타입 생성:
-
-```bash
-npm run codegen
-npm run codegen:check
-```
-
-package version metadata 생성:
-
-```bash
-npm run package:info
-npm run package:info:check
-```
-
-Bun 단일 바이너리 smoke 대상 컴파일:
-
-```bash
-npm run bun:compile
-./dist/vox --help
-./dist/vox --version
-./dist/vox auth whoami --json
-./dist/vox mcp --list-tools --json
-```
-
-### Auth login smoke
-
-로컬 keychain이 있는 개발 머신에서 OAuth login 저장 경로까지 확인하려면 다음 smoke를 실행합니다. 이 smoke는 로컬 fake OAuth/API 서버를 띄우고 실제 `auth login --no-open` loopback flow를 완료한 뒤, OS keychain에 저장된 임시 profile로 `auth whoami`를 실행하고 cleanup합니다.
-
-```bash
-npm run smoke:auth-login-local
-npm run bun:compile
-npm run smoke:auth-login-local-binary
-```
-
-### CI와 release
-
-GitHub Actions의 단독 `vox-cli` repo CI는 `guide:pack:check`, `skills:pack:check`, `docs:pack:check`, `typecheck`, `test`, `audit`, `build`, Node smoke, agent diff check smoke, local authoring workflow smoke, npm package smoke, Bun binary help smoke, Bun binary agent diff check smoke, Bun binary local authoring workflow smoke, MCP binary smoke를 실행합니다.
-
-local authoring workflow smoke는 임시 프로젝트에서 dashboard export `agent import`, `tool init/validate/explain`, `knowledge init/validate/explain`, single-prompt dashboard-style 설정 편집과 `callScreening` 보존, `agent explain`, `agent test init/list/show/validate`, extraction/condition router, API/tool/sendSms/transferCall/transferAgent flow node 작성과 연결, `agent attach tool/knowledge`, `agent doctor`, `agent status --all --offline`, `agent validate --offline`, `agent push --dry-run --offline`를 실제 CLI 명령으로 실행합니다.
-
-npm package smoke는 `npm pack` tarball을 임시 프로젝트에 설치한 뒤 설치된 `vox` binary로 help, version, unauthenticated whoami, agent diff check fixture를 실행합니다. `codegen:check`, `tool:constraints:check`, `mcp:surface:check`는 monorepo의 api-server/mcp/skills 파일을 필요로 하므로 monorepo context에서 실행해야 합니다.
-
-`tool:constraints:check`는 api-server의 v3 tool request schema와 `tool_service.py`에서 tool name 예약어, name 길이/패턴, HTTP/auth/response enum, timeout 범위를 다시 생성해 CLI-local `tool validate` 상수와 비교합니다. 이 체크도 monorepo context가 필요합니다.
-
-릴리스 후보를 만들기 전에는 standalone repo에서 다음 명령을 실행합니다.
-
-```bash
-npm run release:check
-```
-
-`release:check`는 package metadata drift check, guide/skills/docs pack check, public release surface check, Homebrew formula smoke, typecheck, unit test, npm audit, build, Node smoke, agent diff check smoke, local authoring workflow smoke, npm package smoke, Bun binary help smoke, Bun binary agent diff check smoke, Bun binary local authoring workflow smoke, MCP binary smoke를 모두 실행합니다.
-
-npm publish 직전에는 `prepublishOnly`가 최소 package gate를 다시 실행합니다. `@vox-ai/cli`는 새 scoped package이므로 `publishConfig.access`는 `public`으로 고정되어 있습니다.
-
-실제 배포 전에 GitHub Actions의 수동 `CLI Release Preflight` workflow를 같은 version/dist-tag로 먼저 실행합니다. 이 workflow는 configured skills source(`VOX_CLI_PUBLIC_SKILLS_BASE_URL`)와 `docs.tryvox.co` source drift check, `release:check`, macOS arm64/x64 Bun binary build/smoke, tarball/checksum/formula 검증, GitHub App 기반 public tap 접근/중복 검사, npm publish auth 기반 `npm publish --dry-run`을 실행하지만 git tag, GitHub Release, npm package, Homebrew Formula PR은 만들지 않습니다.
-
-배포는 GitHub Actions의 수동 `CLI Release` workflow로 진행합니다. workflow 입력으로 package version, npm dist-tag(`beta` 또는 `latest`), GitHub prerelease 여부를 받으며, `0.0.0` placeholder version, prerelease `latest` 배포, 다른 commit의 기존 git tag, stale tap release/tag는 거부합니다.
-
-`CLI Release` workflow는 세 가지를 같은 commit에서 처리합니다.
-
-1. `release:check`를 통과시킵니다.
-2. configured skills raw file hash와 `docs.tryvox.co/llms.txt` / 주요 `.md` page가 generated guide/docs pack과 맞는지 확인합니다. 현재 beta release 기준 skills source는 `garden-tryvox/vox-skills@codex/cli-first-authoring`입니다.
-3. macOS `darwin-arm64`, `darwin-x64` Bun 단일 바이너리를 만들고 matching runner에서 binary smoke를 실행한 뒤 Actions artifact로 보관합니다.
-4. GitHub App token으로 public tap 접근과 stale release/tag 부재를 확인하고, npm registry auth를 확인합니다.
-5. `checksums.txt`에서 Homebrew formula `vox.rb`를 렌더링하고, 실제 tarball sha256 / `checksums.txt` / `vox.rb` URL과 sha가 일치하는지 확인합니다.
-6. `vox-cli` repo에 `v{version}` source tag를 생성합니다.
-7. `vox-public/homebrew-tap` GitHub Release draft에 tarball, `checksums.txt`, `vox.rb`를 올립니다.
-8. `npm publish --tag <dist-tag>`가 성공하면 GitHub Release draft를 공개합니다.
-9. macOS arm64/x64 runner에서 public release의 `vox.rb`로 `brew audit --strict`, `brew install`, `vox --version`, `vox mcp --list-tools --json`, `brew test`를 실행합니다.
-10. Homebrew smoke가 통과하면 `vox-public/homebrew-tap`에 Formula PR을 엽니다.
-
-실행 전 repo secret `VOX_APP_ID`, `VOX_APP_KEY`, `NPM_TOKEN`과 environment `npm-publish`를 설정해야 합니다. public release 전에는 가능하면 npm Trusted Publishing/OIDC로 전환해서 장기 publish token 의존을 제거합니다. npm provenance는 source repository visibility와 trusted publishing 조건을 만족한 뒤 다시 켭니다.
-
-Homebrew 배포는 `vox-public/homebrew-tap`의 `Formula/vox.rb`가 같은 public tap repo의 GitHub Release tarball을 참조하는 구조로 둡니다. Release workflow는 GitHub App token으로 비어 있는 tap repo의 `main`을 1회 초기화하고, public release asset의 `vox.rb`가 macOS Homebrew smoke를 통과한 뒤 tap repo의 `Formula/vox.rb`로 복사하는 PR을 자동 생성합니다. Formula PR은 필요하면 tap 쪽 CI/audit 결과를 추가 확인한 뒤 merge합니다.
-
-`npm publish`가 성공하기 전 workflow가 실패하면 release cleanup step이 `vox-cli` source tag와 public tap draft release를 best-effort로 삭제해 같은 version으로 재시도할 수 있게 합니다. `npm publish`가 이미 성공한 뒤의 Homebrew 실패는 package version이 공개된 상태이므로 자동 삭제하지 않고 수동 복구합니다.
-
-## 인증
-
-이 CLI는 OAuth-only입니다. 저장된 refresh token은 내부 `SecretStore` 추상화를 통해 OS keychain에 저장해야 합니다. JSON config와 project file에는 secret이 아닌 metadata만 저장합니다.
-
-OS keychain 접근이 멈추는 환경에서는 auth resolver가 무한 대기하지 않고 `KEYCHAIN_UNAVAILABLE` JSON error로 종료합니다. 기본 keychain operation timeout은 10초이며, 진단이나 CI 환경에서는 `VOX_KEYCHAIN_TIMEOUT_MS=<milliseconds>`로 1초에서 60초 사이 값을 지정할 수 있습니다.
-
-Headless 실행은 저장 token 대신 `VOX_OAUTH_ACCESS_TOKEN`과 `VOX_ORGANIZATION_ID`를 명시적으로 주입하는 경로를 사용합니다.
-
-## MCP
-
-### Tool surface
-
-`vox mcp --list-tools --json`는 인증 없이 생성된 cached public MCP surface를 출력합니다. `vox mcp --list-tools --live --json`는 CLI OAuth token으로 hosted MCP에 직접 연결해 현재 live `tools/list` 결과를 출력합니다.
-
-### Client config snippets
-
-`vox mcp --config`는 설치된 CLI를 MCP stdio bridge로 등록하기 위한 설정 snippet을 출력합니다. 기존 Claude/Codex 설정 파일을 직접 수정하지 않으므로 고객 repo의 설정을 덮어쓰지 않습니다.
-
-```bash
-vox auth login
-vox mcp --config --target codex --json
-vox mcp --config --target claude --json
-vox mcp --config --target generic
-```
-
-Codex target은 `codex mcp add vox -- vox mcp --stdio` 명령과 `~/.codex/config.toml` / `.codex/config.toml` TOML snippet을 제공합니다. Claude target은 `claude mcp add --transport stdio --scope project vox -- vox mcp --stdio` 명령과 project-scoped `.mcp.json` snippet을 제공합니다.
-
-### Live smoke
-
-복잡한 flow agent-as-code 루프를 실제 워크스페이스에서 확인해야 할 때는 opt-in live smoke를 사용합니다. 이 스모크는 disposable 원격 에이전트를 생성, 수정, pull/diff 확인 후 soft-delete하므로 release gate에는 자동 포함하지 않습니다.
-
-```bash
-VOX_PROFILE=<profile> \
-VOX_LIVE_SMOKE_ORG_ID=<organization-id> \
-VOX_LIVE_SMOKE_CONFIRM=<organization-id> \
-npm run smoke:agent-flow-live
-```
-
-tool/knowledge/agent resource reference 루프를 실제 워크스페이스에서 확인할 때는 별도 opt-in live smoke를 사용합니다. 이 스모크는 custom HTTP tool 생성/수정/pull/status/diff, text+file knowledge 생성/문서 교체/skip/status/prune, 원격 knowledge의 incomplete pull binding, single-prompt agent에 local `toolRef`/`knowledgeRefs` attach, flow agent에 API node + tool node + conversation knowledgeRefs 구성, agent validate/dry-run/push/update/pull/status/diff, pull 시 local resource ref 복원, 그리고 사용자-facing `agent/tool/knowledge delete` cleanup까지 확인합니다.
-
-```bash
-VOX_PROFILE=<profile> \
-VOX_LIVE_SMOKE_ORG_ID=<organization-id> \
-VOX_LIVE_SMOKE_CONFIRM=<organization-id> \
-npm run smoke:resource-live
-```
-
-실행 전 active profile의 current organization이 `<organization-id>`와 일치해야 합니다. 필요하면 먼저 `vox auth switch --org <organization-id>`를 실행하세요.
-
-### Local stdio bridge
+Development and local builds never emit telemetry.
 
-`vox mcp --stdio`는 공식 TypeScript MCP SDK를 사용해 stdio 기반 로컬 MCP 서버를 실행하고, tool list/call을 profile의 hosted MCP(`mcp_url`)로 전달합니다. tool call에는 CLI OAuth resolver와 OS keychain token을 재사용합니다. `--stdio`와 `--json`은 함께 사용할 수 없습니다. stdout은 MCP protocol message 전용입니다.
+## Upgrade
 
-hosted MCP 브릿지 전환 가능성을 확인하려면 로그인된 profile 또는 `VOX_OAUTH_ACCESS_TOKEN`이 있는 개발 머신에서 다음 spike를 실행합니다. 이 spike는 `AuthContext.mcpUrl`의 hosted MCP에 bearer token으로 연결해 `tools/list`와 `list_organizations`만 호출합니다. 토큰 값은 출력하지 않습니다.
+`vox upgrade` checks for a newer release and prints the upgrade command for how you installed it — it does not modify your installation itself. Run the printed command (or one of the below) to actually update:
 
 ```bash
-npm run spike:mcp-bridge
+vox upgrade                              # check for a newer version and print the upgrade command
+npm install -g @vox-ai/cli@latest        # update an npm install
+brew upgrade vox-public/tap/vox          # update a Homebrew install
 ```
 
-`spike:mcp-bridge`는 hosted MCP bearer 경로를 수동 재검증할 때 사용합니다. `hosted_mcp_auth_401` 또는 `hosted_mcp_resource_or_scope`가 나오면 profile token freshness 또는 MCP resource/audience 처리를 먼저 확인해야 합니다.
+## Support
 
-## Listen / Trigger
+- Homepage: https://www.tryvox.co
+- Documentation: https://docs.tryvox.co
+- npm package: https://www.npmjs.com/package/@vox-ai/cli
 
-api-server owner sync 없이 이 CLI 패키지에서 api-server relay endpoint나 webhook-processor fanout 변경을 시작하지 마세요. 확정된 설계는 모노레포 Obsidian 노트 `__docs__/share/garden/dx_vox_cli/Listen And Trigger Relay Spec.md`에 기록되어 있습니다.
+Licensed under the MIT License.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vox-ai/cli-linux-x64",
-  "version": "0.1.0-beta.2",
+  "version": "0.1.0-beta.5",
   "description": "Prebuilt linux-x64 binary for the vox.ai CLI",
   "homepage": "https://www.tryvox.co",
   "license": "MIT",