chore: README localized to Korean and updated with current product boundary and environment variables

README.md

@@ -1,53 +1,51 @@
 # NomadCode
 
-NomadCode is a monorepo for AI-assisted development workflows. It brings together a Go orchestration service, a React/Vite operator console, a Flutter client, shared contract space, and root-level agent-operation rules.
+NomadCode는 AI 기반 개발 작업을 제품 흐름으로 운영하기 위한 원레포입니다. Go 기반 core 서비스, React/Vite 웹 콘솔, Flutter 클라이언트, 공유 계약 공간, 그리고 AI 에이전트 작업 규칙과 로드맵을 한 작업 흐름으로 묶습니다.
 
-The repository is currently an early product scaffold. The core service owns task orchestration and persistence, the web and mobile apps provide initial operator surfaces, and `agent-ops/` keeps the rules and roadmap that AI agents need before changing the workspace.
+NomadCode는 IOP를 사용하는 개발 워크플로우 셸입니다. 사용자와 외부 provider 요청을 개발 작업으로 구조화하고, project/session/workspace 상태와 실행 결과를 사용자에게 보여줍니다. 모델 런타임, 모델 라우팅, RAG, MCP 정책, output validation 엔진은 NomadCode가 직접 소유하지 않고 IOP 책임으로 둡니다.
 
-NomadCode is the development-workflow shell that consumes IOP. It structures user and provider requests into development tasks, tracks project/session/workspace state, and shows execution results to users. It does not own the model runtime, model routing, RAG, MCP policy, or output-validation engine; those responsibilities belong to IOP.
+## 현재 상태
 
-## Current Status
+- `services/core`는 health/readiness endpoint, task API, PostgreSQL persistence, goose migration, sqlc query 생성 구조, River job, IOP OpenAI-compatible Responses client 경로, 향후 A2A agent delegation scaffolding, Plane/Mattermost adapter stub을 포함합니다.
+- `apps/web`은 Agent, Projects, Settings, browser-based project workspace 화면을 위한 React/Vite 운영 콘솔 scaffold입니다. 일부 상태와 integration status 영역은 아직 mock 또는 stub입니다.
+- `apps/mobile`은 Flutter 기반 모바일/데스크톱 클라이언트 scaffold이며 Firebase Messaging, local notifications, HTTP client 의존성을 포함합니다.
+- `packages/contracts`는 향후 OpenAPI, protobuf, generated client, fixture, compatibility asset을 담을 공유 계약 공간입니다.
+- 활성 계획과 Milestone 상태는 `agent-ops/roadmap/`에서 관리합니다. README에는 현재 작업 상태를 복사하지 않고 진입 문서만 연결합니다.
 
-- `services/core` has HTTP health/readiness endpoints, task APIs, PostgreSQL persistence, goose migrations, sqlc-generated query code, River jobs, an IOP OpenAI-compatible Responses client path, future A2A agent-delegation scaffolding, and Plane/Mattermost adapter stubs.
-- `apps/web` is a React/Vite scaffold for Agent, Projects, Settings, and browser-based project workspace views. Some state and integration status areas are still mocked or stubbed.
-- `apps/mobile` is a Flutter app scaffold for mobile and desktop client surfaces, Firebase Messaging, local notifications, and HTTP client dependencies.
-- `packages/contracts` is a placeholder for future shared OpenAPI, protobuf, generated client, fixture, and compatibility assets.
-- Active planning lives under `agent-ops/roadmap/`; this README links to that context instead of duplicating milestone state.
+## 제품 경계
 
-## Product Boundary
+NomadCode는 제품과 워크플로우 계층을 소유합니다.
 
-NomadCode owns the product and workflow layer:
+- agent chat, project workspace 관리, task queue 상태, 실행 상태 표시
+- Plane/Jira 스타일 work item intake, provider projection, comment, status update
+- 사용자에게 노출되는 file change, diff, branch, commit, PR 흐름
+- 데스크톱/모바일 project management surface
+- IOP 호출에 넘길 task metadata 구성
 
-- agent chat, project workspace management, task queue state, and execution status.
-- Plane/Jira-style work item intake, provider projection, comments, and status updates.
-- user-facing file change, diff, branch, commit, and PR flows.
-- desktop and mobile project management surfaces, including project-level desktop windows and mobile top-tab workflows.
-- task metadata prepared for IOP calls.
+IOP는 실행과 최적화 계층을 소유합니다.
 
-IOP owns the execution and optimization layer:
+- OpenAI-compatible model call, 현재 NomadCode 통합 목표인 Responses API 지원
+- local/cloud model routing, model profile, runtime selection, usage log, quality signal
+- OpenCode, Aider, Claude Code, Gemini CLI, Codex CLI 같은 CLI agent/runtime adapter
+- RAG, context compression, MCP/tool policy, output validation, retry/fallback, token/speed/quality optimization
 
-- OpenAI-compatible model calls, with Responses API support as the current NomadCode integration target.
-- local/cloud model routing, model profiles, runtime selection, usage logs, and quality signals.
-- CLI agent/runtime adapters such as OpenCode, Aider, Claude Code, Gemini CLI, and Codex CLI.
-- RAG, context compression, MCP/tool policy, output validation, retry/fallback, and token/speed/quality optimization.
+NomadCode는 IOP가 제공하는 외부 표면을 통해 IOP를 호출합니다. 현재 기본 경로는 IOP의 OpenAI-compatible Responses API입니다. A2A는 향후 외부 agent delegation 작업을 위한 표면이며, IOP native protocol은 NomadCode의 기본 외부 호출 경로가 아닙니다.
 
-NomadCode should call IOP through its supported external surfaces. The current NomadCode path is IOP's OpenAI-compatible Responses API. A2A is reserved for later external agent delegation work, and IOP native protocol is not a NomadCode default external call path.
+## 빠른 시작
 
-## Quick Start
-
-Install only the runtimes needed for the part of the workspace you are using.
+사용하는 workspace 영역에 필요한 runtime만 설치하면 됩니다.
 
 ```bash
-# Show service/app dev entrypoints.
+# 사용 가능한 service/app 개발 entrypoint 확인
 bin/dev
 
-# Run workspace checks for installed toolchains.
+# 설치된 toolchain 기준으로 workspace 검증
 bin/test
 bin/lint
 bin/build
 ```
 
-Run the core service locally. The scripts provide local defaults, but they still expect reachable PostgreSQL and Redis services; see `services/core/README.md` for the current `code-server` database setup notes.
+Core service를 로컬에서 실행합니다. 스크립트는 local 기본값을 제공하지만, PostgreSQL과 Redis가 접근 가능해야 합니다. 현재 `code-server` database setup 관련 메모는 `services/core/README.md`를 확인합니다.
 
 ```bash
 cd services/core
@@ -55,7 +53,7 @@ cd services/core
 ./bin/run
 ```
 
-Run the web console:
+Web console을 실행합니다.
 
 ```bash
 cd apps/web
@@ -63,82 +61,84 @@ npm install
 npm run dev
 ```
 
-Run the Flutter app:
+Flutter 앱을 실행합니다.
 
-```sh
+```bash
 cd apps/mobile
 flutter pub get
 flutter run
 ```
 
-## Major Commands
+## 주요 명령
 
-| Purpose | Command | Notes |
+| 목적 | 명령 | 비고 |
 |------|------|------|
-| Show local dev entrypoints | `bin/dev` | Prints core, web, and mobile commands. |
-| Test workspace | `bin/test` | Runs `go test ./...`, web `npm run check` or tests if present, and `flutter test`; skips missing toolchains. |
-| Lint workspace | `bin/lint` | Runs `go vet ./...`, web `npm run lint --if-present`, and `flutter analyze --no-fatal-infos`; skips missing toolchains. |
-| Build workspace | `bin/build` | Runs core `go build ./...`, web `npm run build`, and `flutter build web`; skips missing toolchains. |
-| Run core | `cd services/core && ./bin/run` | Uses local defaults from the core script unless environment variables override them. |
-| Migrate core DB | `cd services/core && ./bin/migrate-up` | Uses goose against the configured PostgreSQL database. |
-| Test core | `cd services/core && ./bin/test` | Thin wrapper around `go test ./...`. |
-| Build core binary | `cd services/core && ./bin/build` | Outputs to `.build/nomadcode-core` unless `OUTPUT` is set. |
-| Run web dev server | `cd apps/web && npm run dev` | Vite development server. |
-| Check web types | `cd apps/web && npm run check` | TypeScript `--noEmit`. |
-| Verify web | `cd apps/web && npm run verify` | Runs type check and production build. |
-| Run mobile tests | `cd apps/mobile && flutter test` | Flutter test suite. |
+| 개발 entrypoint 확인 | `bin/dev` | core, web, mobile 실행 명령을 출력합니다. |
+| workspace 테스트 | `bin/test` | `go test ./...`, web check 또는 test, `flutter test`를 실행하고 없는 toolchain은 건너뜁니다. |
+| workspace lint | `bin/lint` | `go vet ./...`, web lint, `flutter analyze --no-fatal-infos`를 실행하고 없는 toolchain은 건너뜁니다. |
+| workspace build | `bin/build` | core `go build ./...`, web build, Flutter web build를 실행하고 없는 toolchain은 건너뜁니다. |
+| core 실행 | `cd services/core && ./bin/run` | 스크립트 기본값을 사용하며 env로 override할 수 있습니다. |
+| core DB migration | `cd services/core && ./bin/migrate-up` | goose로 PostgreSQL migration을 적용합니다. |
+| core 테스트 | `cd services/core && ./bin/test` | `go test ./...` wrapper입니다. |
+| core build | `cd services/core && ./bin/build` | 기본 출력 경로는 `.build/nomadcode-core`입니다. |
+| web dev server | `cd apps/web && npm run dev` | Vite 개발 서버입니다. |
+| web type check | `cd apps/web && npm run check` | TypeScript `--noEmit` 검증입니다. |
+| web verify | `cd apps/web && npm run verify` | type check와 production build를 함께 실행합니다. |
+| mobile 테스트 | `cd apps/mobile && flutter test` | Flutter test suite입니다. |
 
-## Structure
+## 구조
 
-| Path | Role |
+| 경로 | 역할 |
 |------|------|
-| `services/core/` | Go backend for orchestration, persistence, scheduling, HTTP APIs, and external service adapters. |
-| `apps/web/` | React/Vite operator console and browser-based agent/project workspace UI. |
-| `apps/mobile/` | Flutter mobile/desktop client, project management surface, and notification integration surface. |
-| `packages/contracts/` | Future shared API/schema contracts and generated client boundary. |
-| `docs/` | Architecture and operations notes. |
-| `bin/` | Root test, lint, build, and dev helper commands. |
-| `agent-ops/` | Agent rules, domain routing, roadmap, and repeatable task skills. |
+| `services/core/` | Go backend. orchestration, persistence, scheduling, HTTP API, 외부 service adapter를 담당합니다. |
+| `apps/web/` | React/Vite 운영 콘솔과 agent/project workspace UI입니다. |
+| `apps/mobile/` | Flutter 모바일/데스크톱 클라이언트와 notification 연동 표면입니다. |
+| `packages/contracts/` | 서비스와 클라이언트가 공유할 API/schema 계약 공간입니다. |
+| `docs/` | 아키텍처와 운영 문서입니다. |
+| `bin/` | root test, lint, build, dev helper 명령입니다. |
+| `agent-ops/` | AI 에이전트 규칙, 도메인 라우팅, 로드맵, 반복 작업 skill입니다. |
 
-## Work Context
+## 작업 맥락
 
-AI agents should start with the root instructions and project rules before changing files:
+AI 에이전트는 파일을 변경하기 전에 루트 지침과 프로젝트 규칙을 먼저 확인합니다.
 
 - `AGENTS.md`
 - `agent-ops/rules/project/rules.md`
-- `agent-ops/rules/private/rules.md` when present
+- `agent-ops/rules/private/rules.md`가 있으면 해당 파일
 
-For workspace-level files such as this README, also check:
+README 같은 workspace-level 파일을 다룰 때는 아래 문서를 함께 확인합니다.
 
 - `agent-ops/rules/project/domain/workspace-ops/rules.md`
 - `agent-ops/skills/common/create-readme/SKILL.md`
 - `agent-ops/roadmap/current.md`
 
-Keep detailed roadmap state in `agent-ops/roadmap/` and detailed domain rules in `agent-ops/rules/project/domain/`. Do not read `agent-task/archive/**` unless the user explicitly asks for it.
+로드맵 상세 상태는 `agent-ops/roadmap/`에, 도메인별 세부 규칙은 `agent-ops/rules/project/domain/`에 둡니다. 사용자가 명시적으로 요청하지 않는 한 `agent-task/archive/**`와 `agent-ops/roadmap/archive/**`는 읽지 않습니다.
 
-IOP boundary work should be checked against the sibling IOP repository when it is available in the same workspace. NomadCode roadmap documents should remain the source of truth for NomadCode product/workflow scope; IOP roadmap documents should remain the source of truth for execution/runtime scope.
+IOP 경계가 걸린 작업은 같은 workspace에 sibling IOP repository가 있을 때 함께 확인합니다. NomadCode roadmap은 제품/워크플로우 범위의 기준 문서이고, IOP roadmap은 실행/runtime 범위의 기준 문서입니다.
 
-## Development Flow
+## 개발 흐름
 
-- Prefer the root `bin/test`, `bin/lint`, `bin/build`, and `bin/dev` entrypoints for whole-workspace work.
-- Keep changes scoped to the owning domain rules. Cross-boundary changes should close the contract, service, and client behavior in the same branch when those boundaries move together.
-- For core database changes, update `services/core/migrations/` and `services/core/queries/`, then regenerate sqlc output instead of hand-editing generated files under `services/core/internal/db/`.
-- Keep `agent-ops/rules/common/**` and `agent-ops/skills/common/**` as framework-synced areas; put project-specific rules under `agent-ops/rules/project/**`.
+- 전체 workspace 작업은 가능한 한 root `bin/test`, `bin/lint`, `bin/build`, `bin/dev` entrypoint를 우선 사용합니다.
+- 변경은 소유 도메인 규칙 범위에 맞춰 좁게 유지합니다.
+- contract, service, client 경계가 함께 움직이는 변경은 같은 브랜치에서 닫습니다.
+- core DB 변경은 `services/core/migrations/`와 `services/core/queries/`를 기준으로 반영하고, `services/core/internal/db/`의 생성 파일은 직접 수정하지 않습니다.
+- `agent-ops/rules/common/**`와 `agent-ops/skills/common/**`는 framework 동기화 영역입니다. 프로젝트 특화 규칙은 `agent-ops/rules/project/**`에 둡니다.
 
-## Environment Variables
+## 환경 변수
 
-| Runtime | Name | Required | Notes |
+| Runtime | 이름 | 필수 | 설명 |
 |------|------|------|------|
-| Core | `DATABASE_URL` | No, with scripts | Core scripts provide local defaults; set it when running the binary directly or using a different PostgreSQL database. |
-| Core | `REDIS_URL`, `REDIS_KEY_PREFIX` | No, with scripts | Core scripts provide local defaults for worker/queue state; set them when running outside those scripts. |
-| Core | `AUTH_USERNAME`, `AUTH_PASSWORD` | No | `AUTH_PASSWORD` enables HTTP Basic Auth for `/readyz` and `/api/*`. |
-| Core | `MODEL_BASE_URL`, `MODEL_API_KEY`, `MODEL_NAME`, `MODEL_CONTEXT_SIZE`, `MODEL_TIMEOUT_SEC` | No | Configure the IOP Edge OpenAI-compatible Responses endpoint used by worker execution. Legacy direct model endpoint compatibility may exist in local scripts, but the target runtime path is IOP. |
-| Core | `A2A_EDGE_URL`, `A2A_AGENT_URL`, `A2A_TOKEN`, `A2A_TIMEOUT_SEC` | No | Configure the future A2A-compatible agent delegation path. This is not the current default execution path. |
-| Core | `MATTERMOST_BASE_URL`, `MATTERMOST_TOKEN` | No | Reserved for Mattermost adapter integration. |
-| Core | `PLANE_BASE_URL`, `PLANE_TOKEN` | No | Configure Plane work item lookup, comment, and state update integration. |
-| Web | `VITE_NOMADCODE_API_BASE_URL` | No | The web client falls back to `http://localhost:8080`; `apps/web/.env.example` documents the same local value. |
+| Core | `DATABASE_URL` | 스크립트 사용 시 선택 | Core script는 local 기본값을 제공합니다. 다른 PostgreSQL을 쓰거나 binary를 직접 실행할 때 설정합니다. |
+| Core | `REDIS_URL`, `REDIS_KEY_PREFIX` | 스크립트 사용 시 선택 | worker/queue 상태에 사용할 Redis 주소와 key prefix입니다. |
+| Core | `AUTH_USERNAME`, `AUTH_PASSWORD` | 선택 | `AUTH_PASSWORD`를 설정하면 `/readyz`와 `/api/*`에 HTTP Basic Auth가 적용됩니다. |
+| Core | `MODEL_BASE_URL`, `MODEL_API_KEY`, `MODEL_NAME`, `MODEL_CONTEXT_SIZE`, `MODEL_TIMEOUT_SEC` | 선택 | worker execution에서 사용할 IOP Edge OpenAI-compatible Responses endpoint 설정입니다. |
+| Core | `A2A_EDGE_URL`, `A2A_AGENT_URL`, `A2A_TOKEN`, `A2A_TIMEOUT_SEC` | 선택 | 향후 A2A-compatible agent delegation 경로 설정입니다. 현재 기본 실행 경로는 아닙니다. |
+| Core | `WORKFLOW_TASK_TIMEOUT_SEC` | 선택 | workflow task timeout 기본값을 조정합니다. |
+| Core | `MATTERMOST_BASE_URL`, `MATTERMOST_TOKEN` | 선택 | Mattermost adapter 연동용 설정입니다. |
+| Core | `PLANE_BASE_URL`, `PLANE_TOKEN` | 선택 | Plane work item 조회, comment, state update 연동용 설정입니다. token 값은 문서에 기록하지 않습니다. |
+| Web | `VITE_NOMADCODE_API_BASE_URL` | 선택 | web client API base URL입니다. 기본값은 `http://localhost:8080`입니다. |
 
-## Reference Documents
+## 참고 문서
 
 - `docs/monorepo.md`
 - `services/core/README.md`