diff --git a/packages/web/src/content/docs/ko/acp.mdx b/packages/web/src/content/docs/ko/acp.mdx
index 2fbd58013f8..a9842f27090 100644
--- a/packages/web/src/content/docs/ko/acp.mdx
+++ b/packages/web/src/content/docs/ko/acp.mdx
@@ -1,12 +1,12 @@
 ---
-title: ACP 지원
-description: ACP 호환 편집기에서 opencode를 사용하세요.
+title: ACP Support
+description: Use OpenCode in any ACP-compatible editor.
 ---
 
-opencode는 [Agent Client Protocol](https://agentclientprotocol.com) 또는 (ACP)을 지원하며, 호환 편집기 및 IDE에서 직접 사용할 수 있습니다.
+OpenCode는 [Agent Client Protocol](https://agentclientprotocol.com)(ACP)을 지원하므로, ACP 호환 편집기와 IDE에서 OpenCode를 직접 사용할 수 있습니다.
 
 :::tip
-ACP를 지원하는 편집기 및 도구 목록의 경우 [ACP 진행 보고서](https://zed.dev/blog/acp-progress-report#available-now)를 확인하십시오.
+ACP를 지원하는 편집기와 tool 목록은 [ACP progress report](https://zed.dev/blog/acp-progress-report#available-now)에서 확인하세요.
 :::
 
 ACP는 코드 편집기와 AI 코딩 에이전트 간의 통신을 표준화하는 개방형 프로토콜입니다.
@@ -15,17 +15,17 @@ ACP는 코드 편집기와 AI 코딩 에이전트 간의 통신을 표준화하
 
 ## 구성
 
-ACP를 통해 opencode를 사용하려면 `opencode acp` 명령을 실행하려면 편집기를 구성하십시오.
+ACP로 OpenCode를 사용하려면, 편집기에서 `opencode acp` 명령을 실행하도록 config를 설정하세요.
 
-명령은 opencode를 실행하여 JSON-RPC를 통해 편집기와 통신하는 ACP 호환 하위 프로세스로 시작합니다.
+이 명령은 OpenCode를 ACP 호환 subprocess로 시작하며, stdio 기반 JSON-RPC를 통해 편집기와 통신합니다.
 
-아래는 ACP를 지원하는 인기있는 편집기의 예입니다.
+아래는 ACP를 지원하는 주요 편집기 예시입니다.
 
 ---
 
-##### Zed
+### Zed
 
-[Zed](https://zed.dev) 구성 (`~/.config/zed/settings.json`)에 추가 :
+[Zed](https://zed.dev) config(`~/.config/zed/settings.json`)에 다음을 추가하세요.
 
 ```json title="~/.config/zed/settings.json"
 {
@@ -38,9 +38,9 @@ ACP를 통해 opencode를 사용하려면 `opencode acp` 명령을 실행하려
 }
 ```
 
-그것을 열려면 **Command Palette **에서 `agent: new thread` 동작을 사용하십시오.
+열려면 **Command Palette**에서 `agent: new thread` action을 사용하세요.
 
-`keymap.json`를 편집하여 키보드 단축키도 결합할 수 있습니다.
+`keymap.json`을 수정해 키보드 단축키를 바인딩할 수도 있습니다.
 
 ```json title="keymap.json"
 [
@@ -67,9 +67,9 @@ ACP를 통해 opencode를 사용하려면 `opencode acp` 명령을 실행하려
 
 ---
 
-#### JetBrains IDEs
+### JetBrains IDEs
 
-[JetBrains IDE]에 추가하십시오 (https://www.jetbrains.com/) [documentation]에 따라 acp.json (https://www.jetbrains.com/help/ai-assistant/acp.html):
+[JetBrains IDE](https://www.jetbrains.com/)에서는 [documentation](https://www.jetbrains.com/help/ai-assistant/acp.html)에 따라 `acp.json`에 다음을 추가하세요.
 
 ```json title="acp.json"
 {
@@ -82,13 +82,13 @@ ACP를 통해 opencode를 사용하려면 `opencode acp` 명령을 실행하려
 }
 ```
 
-그것을 열려면 AI Chat Agent selector의 새로운 'opencode' 에이전트를 사용하십시오.
+열려면 AI Chat agent selector에서 새 `OpenCode` agent를 선택하세요.
 
 ---
 
-#### Avante.nvim
+### Avante.nvim
 
-[Avante.nvim](https://github.com/yetone/avante.nvim) 구성에 추가하십시오:
+[Avante.nvim](https://github.com/yetone/avante.nvim) config에 다음을 추가하세요.
 
 ```lua
 {
@@ -101,7 +101,7 @@ ACP를 통해 opencode를 사용하려면 `opencode acp` 명령을 실행하려
 }
 ```
 
-환경 변수를 전달해야 하는 경우:
+환경 변수를 전달해야 한다면 다음과 같이 설정하세요.
 
 ```lua {6-8}
 {
@@ -119,9 +119,9 @@ ACP를 통해 opencode를 사용하려면 `opencode acp` 명령을 실행하려
 
 ---
 
-#### CodeCompanion.nvim
+### CodeCompanion.nvim
 
-opencode를 [CodeCompanion.nvim](https://github.com/olimorris/codecompanion.nvim)에서 ACP 에이전트로 사용하려면 Neovim config에 다음을 추가하십시오.
+[CodeCompanion.nvim](https://github.com/olimorris/codecompanion.nvim)에서 OpenCode를 ACP agent로 사용하려면 Neovim config에 다음을 추가하세요.
 
 ```lua
 require("codecompanion").setup({
@@ -136,21 +136,21 @@ require("codecompanion").setup({
 })
 ```
 
-이 구성은 CodeCompanion을 설정하여 채팅을 위한 ACP 에이전트로 opencode를 사용합니다.
+이 config는 chat에서 OpenCode를 ACP agent로 사용하도록 CodeCompanion을 설정합니다.
 
-환경 변수 (`OPENCODE_API_KEY`와 같은)를 전달해야하는 경우, CodeCompanion.nvim 문서에서 [Configuring Adapters: Environment variables](https://codecompanion.olimorris.dev/getting-started#setting-an-api-key)를 참조하십시오.
+환경 변수(`OPENCODE_API_KEY` 등)를 전달해야 한다면 CodeCompanion.nvim documentation의 [Configuring Adapters: Environment Variables](https://codecompanion.olimorris.dev/getting-started#setting-an-api-key)를 참고하세요.
 
-## 지원 기능
+## 지원
 
-opencode는 터미널과 동일하게 ACP를 통해 작동합니다. 모든 기능은 지원됩니다:
+OpenCode는 ACP를 통해서도 터미널과 동일하게 동작합니다. 다음 기능을 모두 지원합니다.
 
 :::note
 `/undo` 및 `/redo`와 같은 일부 내장 슬래시 명령은 현재 지원되지 않습니다.
 :::
 
-- 내장 도구 (파일 작업, terminal 명령 등)
-- 사용자 정의 도구 및 슬래시 명령
-- opencode config에서 설정된 MCP 서버
-- `AGENTS.md`의 프로젝트 별 규칙
-- 사용자 정의 포맷 및 라이터
-- 에이전트 및 권한 시스템
+- 내장 tool(파일 작업, terminal 명령 등)
+- 사용자 정의 tool과 slash command
+- OpenCode config에 설정한 MCP 서버
+- `AGENTS.md`의 프로젝트별 규칙
+- 사용자 정의 formatter와 linter
+- agent 및 권한 시스템
diff --git a/packages/web/src/content/docs/ko/agents.mdx b/packages/web/src/content/docs/ko/agents.mdx
index 5b37122435f..34de6250d1d 100644
--- a/packages/web/src/content/docs/ko/agents.mdx
+++ b/packages/web/src/content/docs/ko/agents.mdx
@@ -1,141 +1,141 @@
 ---
-title: 에이전트
-description: 전문 에이전트를 구성하고 사용하세요.
+title: Agents
+description: Configure and use specialized agents.
 ---
 
-에이전트는 특정 작업과 워크플로우를 전문으로 하는 구성 가능한 AI 보조자입니다. 사용자 정의 프롬프트, 모델, 도구 액세스로 집중된 도구를 만들 수 있습니다.
+agent는 특정 작업과 워크플로에 맞게 설정할 수 있는 전문 AI assistant입니다. custom prompt, model, tool 접근 권한을 조합해 목적에 맞는 agent를 만들 수 있습니다.
 
 :::tip
-코드 변경 없이 제안을 검토할 때는 Plan 에이전트를 사용하세요.
+코드를 수정하지 않고 분석과 제안 검토만 하고 싶다면 plan agent를 사용하세요.
 :::
 
-세션 중에 에이전트를 전환하거나 `@` 멘션으로 호출할 수 있습니다.
+세션 중에 agent를 전환하거나 `@` mention으로 호출할 수 있습니다.
 
 ---
 
 ## 유형
 
-OpenCode에는 두 가지 유형의 에이전트가 있습니다: 기본 에이전트(Primary Agent)와 서브 에이전트(Subagent).
+OpenCode의 agent는 primary agent와 subagent, 두 가지 유형으로 나뉩니다.
 
 ---
 
-### 기본 에이전트
+### Primary agents
 
-기본 에이전트는 사용자가 직접 상호 작용하는 주요 보조자입니다. **Tab** 키 또는 설정된 `switch_agent` 키바인드를 사용하여 순환할 수 있습니다. 이 에이전트는 주요 대화를 처리합니다. 도구 액세스는 권한을 통해 구성됩니다 — 예를 들어, Build는 모든 도구를 사용할 수 있지만 Plan은 제한됩니다.
+primary agent는 사용자가 직접 상호작용하는 메인 assistant입니다. **Tab** 키 또는 설정한 `switch_agent` keybind로 순환 전환할 수 있습니다. primary agent는 메인 대화를 처리하며, tool 접근은 permission으로 제어합니다. 예를 들어 Build는 모든 tool이 활성화되어 있고 Plan은 제한되어 있습니다.
 
 :::tip
-세션 중에 **Tab** 키를 사용하여 기본 에이전트를 전환할 수 있습니다.
+세션 중 **Tab** 키로 primary agent를 빠르게 전환할 수 있습니다.
 :::
 
-OpenCode는 두 가지 내장 기본 에이전트, **Build** 및 **Plan**을 제공합니다. 아래에서 자세히 살펴봅니다.
+OpenCode에는 기본 제공 primary agent인 **Build**와 **Plan**이 포함되어 있습니다. 아래에서 각각 살펴보겠습니다.
 
 ---
 
-### 서브 에이전트
+### Subagents
 
-서브 에이전트는 기본 에이전트가 특정 작업을 위해 호출할 수 있는 전문 보조자입니다. 또한 메시지에서 **@멘션**을 통해 수동으로 호출할 수도 있습니다.
+subagent는 primary agent가 특정 작업을 위해 호출하는 전문 assistant입니다. 메시지에서 **@ mention**으로 직접 호출할 수도 있습니다.
 
-OpenCode는 두 가지 내장 서브 에이전트, **General** 및 **Explore**를 제공합니다. 아래에서 자세히 살펴봅니다.
+OpenCode에는 기본 제공 subagent인 **General**과 **Explore**가 포함되어 있습니다. 아래에서 살펴보겠습니다.
 
 ---
 
 ## 기본 제공
 
-OpenCode는 기본 에이전트와 두 개의 내장 서브 에이전트를 제공합니다.
+OpenCode는 기본적으로 primary agent 2개와 subagent 2개를 제공합니다.
 
 ---
 
-### Build
+### Use build
 
-_모드_: `primary`
+_Mode_: `primary`
 
-Build는 모든 도구가 활성화된 **기본** 에이전트입니다. 파일 조작 및 시스템 명령에 대한 전체 액세스가 필요한 개발 작업을 위한 표준 에이전트입니다.
+Build는 모든 tool이 활성화된 **default** primary agent입니다. 파일 작업과 시스템 명령에 대한 전체 접근이 필요한 일반적인 개발 작업에 사용하는 표준 agent입니다.
 
 ---
 
-### Plan
+### Use plan
 
-_모드_: `primary`
+_Mode_: `primary`
 
-계획 및 분석을 위해 설계된 제한된 에이전트입니다. 더 많은 제어권을 부여하고 의도하지 않은 변경을 방지하기 위해 권한 시스템을 사용합니다.
-기본적으로 다음은 모두 `ask`로 설정됩니다:
+Plan은 계획과 분석에 특화된 제한형 agent입니다. 더 높은 제어력과 의도치 않은 변경 방지를 위해 permission 시스템을 사용합니다.
+기본값으로 아래 항목은 모두 `ask`로 설정됩니다.
 
-- `file edits`: 모든 쓰기, 패치 및 편집
+- `file edits`: 모든 write, patch, edit
 - `bash`: 모든 bash 명령
 
-이 에이전트는 코드를 분석하거나 변경을 제안받고 싶지만, 코드베이스에 실제 수정 없이 계획만 만들고 싶을 때 유용합니다.
+코드베이스를 실제로 수정하지 않고 LLM 분석, 변경 제안, 계획 수립만 진행하고 싶을 때 유용합니다.
 
 ---
 
-### General
+### Use general
 
-_모드_: `subagent`
+_Mode_: `subagent`
 
-복잡한 질문을 연구하고 다단계 작업을 실행하기 위한 범용 에이전트입니다. 전체 도구 액세스(todo 제외)를 가지므로 필요할 때 파일 변경을 수행할 수 있습니다. 여러 단위의 작업을 병렬로 실행할 때 사용하세요.
+복잡한 질문을 조사하고 다단계 작업을 수행하기 위한 범용 agent입니다. todo를 제외한 모든 tool 접근이 가능하므로 필요하면 파일 수정도 할 수 있습니다. 여러 작업 단위를 병렬로 처리할 때 사용하세요.
 
 ---
 
-### Explore
+### Use explore
 
-_모드_: `subagent`
+_Mode_: `subagent`
 
-코드베이스를 탐색하는 빠르고 읽기 전용인 에이전트입니다. 파일을 수정할 수 없습니다. 패턴, 키워드로 코드를 검색하거나 코드베이스에 대한 질문에 답하기 위해 파일을 빠르게 찾아야 할 때 사용하세요.
+코드베이스 탐색에 최적화된 빠른 읽기 전용 agent입니다. 파일을 수정할 수 없습니다. 패턴 기반 파일 탐색, 키워드 검색, 코드베이스 관련 질의 응답을 빠르게 처리할 때 사용하세요.
 
 ---
 
-### Compaction
+### Use compaction
 
-_모드_: `primary`
+_Mode_: `primary`
 
-긴 컨텍스트를 작은 요약으로 압축하는 숨겨진 시스템 에이전트입니다. 필요한 경우 자동으로 실행되며 UI에서 선택할 수 없습니다.
+긴 context를 더 짧은 요약으로 압축하는 숨겨진 시스템 agent입니다. 필요할 때 자동으로 실행되며 UI에서 직접 선택할 수 없습니다.
 
 ---
 
-### Title
+### Use title
 
-_모드_: `primary`
+_Mode_: `primary`
 
-짧은 세션 제목을 생성하는 숨겨진 시스템 에이전트입니다. 자동으로 실행되며 UI에서 선택할 수 없습니다.
+짧은 세션 제목을 생성하는 숨겨진 시스템 agent입니다. 자동으로 실행되며 UI에서 직접 선택할 수 없습니다.
 
 ---
 
-### Summary
+### Use summary
 
-_모드_: `primary`
+_Mode_: `primary`
 
-세션 요약을 만드는 숨겨진 시스템 에이전트입니다. 자동으로 실행되며 UI에서 선택할 수 없습니다.
+세션 요약을 생성하는 숨겨진 시스템 agent입니다. 자동으로 실행되며 UI에서 직접 선택할 수 없습니다.
 
 ---
 
 ## 사용법
 
-1. 기본 에이전트의 경우, 세션 중에 **Tab** 키를 사용하여 순환합니다. 구성된 `switch_agent` 키바인드도 사용할 수 있습니다.
+1. primary agent는 세션 중 **Tab** 키로 순환 전환할 수 있습니다. 설정한 `switch_agent` keybind를 사용할 수도 있습니다.
 
-2. 서브 에이전트는 다음과 같이 호출할 수 있습니다:
-   - 설명에 근거하여 전문적인 작업을 위해 기본 에이전트에 의해 **자동으로** 호출됨.
-   - 메시지에서 서브 에이전트를 **@멘션**. 예를 들어:
+2. subagent 호출 방법:
+   - **Automatically**: primary agent가 설명(description)을 바탕으로 특화 작업에 자동 호출합니다.
+   - 수동 호출: 메시지에서 subagent를 **@ mention**하여 호출합니다. 예:
 
      ```txt frame="none"
      @general help me search for this function
      ```
 
-3. **세션 간 이동**: 서브 에이전트가 자체 자식 세션을 만들 때, 부모 세션과 자식 세션 간을 탐색할 수 있습니다.
-   - **\<Leader>+Right** (또는 부모 → 자식1 → 자식2 순으로 이동하기 위해 설정된 `session_child_cycle` 키바인드)
-   - **\<Leader>+Left** (또는 `session_child_cycle_reverse` 키바인드) 부모 방향으로 되돌아가기: 자식2 → 자식1 → 부모
+3. **세션 간 이동**: subagent가 child session을 만들면 아래 키로 parent session과 child session 사이를 이동할 수 있습니다.
+   - **\<Leader>+Right** (또는 설정한 `session_child_cycle` keybind): parent → child1 → child2 → ... → parent 순방향 순환
+   - **\<Leader>+Left** (또는 설정한 `session_child_cycle_reverse` keybind): parent ← child1 ← child2 ← ... ← parent 역방향 순환
 
-   이를 통해 주요 대화와 전문적인 서브 에이전트 작업 간을 원활하게 전환할 수 있습니다.
+   이를 통해 메인 대화와 특화 subagent 작업 사이를 자연스럽게 오갈 수 있습니다.
 
 ---
 
 ## 구성
 
-내장 에이전트를 사용자 정의하거나 구성을 통해 자신만의 에이전트를 만들 수 있습니다. 에이전트는 두 가지 방법으로 구성될 수 있습니다:
+기본 제공 agent를 커스터마이즈하거나 config를 통해 직접 agent를 만들 수 있습니다. agent는 두 가지 방식으로 설정합니다.
 
 ---
 
 ### JSON
 
-`opencode.json` config 파일에 에이전트 구성:
+`opencode.json` config 파일에서 agent를 설정합니다.
 
 ```json title="opencode.json"
 {
@@ -178,10 +178,10 @@ _모드_: `primary`
 
 ### Markdown
 
-Markdown 파일을 사용하여 에이전트를 정의 할 수 있습니다. 그들에 게:
+Markdown 파일로도 agent를 정의할 수 있습니다. 다음 위치에 두세요.
 
-- 글로벌: `~/.config/opencode/agents/`
-- 프로젝트: `.opencode/agents/`
+- Global: `~/.config/opencode/agents/`
+- Per-project: `.opencode/agents/`
 
 ```markdown title="~/.config/opencode/agents/review.md"
 ---
@@ -205,19 +205,19 @@ You are in code review mode. Focus on:
 Provide constructive feedback without making direct changes.
 ```
 
-markdown 파일 이름은 에이전트 이름입니다. 예를 들어, `review.md`는 `review` 에이전트을 만듭니다.
+Markdown 파일명은 agent 이름이 됩니다. 예를 들어 `review.md`는 `review` agent를 만듭니다.
 
 ---
 
 ## 옵션
 
-이 구성 옵션들을 자세히 살펴봅시다.
+각 config 옵션을 자세히 살펴보겠습니다.
 
 ---
 
-### 설명
+### Description
 
-`description` 옵션을 사용하여 에이전트가 무엇을 하고 언제 사용해야 하는지에 대한 간단한 설명을 제공합니다.
+`description` 옵션으로 agent의 역할과 사용 시점을 간단히 설명하세요.
 
 ```json title="opencode.json"
 {
@@ -229,15 +229,15 @@ markdown 파일 이름은 에이전트 이름입니다. 예를 들어, `review.m
 }
 ```
 
-\*\* 필수 구성 옵션입니다.
+이 옵션은 **필수** config 항목입니다.
 
 ---
 
-### 온도
+### Temperature
 
-`temperature` 구성으로 LLM 응답의 무작위성과 창의성을 제어합니다.
+`temperature` config로 LLM 응답의 무작위성과 창의성을 제어합니다.
 
-값이 낮을수록 더 집중되고 결정적인 응답을 생성하며, 값이 높을수록 창의성과 가변성이 증가합니다.
+값이 낮을수록 응답이 더 집중되고 결정적이며, 값이 높을수록 창의성과 다양성이 커집니다.
 
 ```json title="opencode.json"
 {
@@ -252,11 +252,11 @@ markdown 파일 이름은 에이전트 이름입니다. 예를 들어, `review.m
 }
 ```
 
-온도 값은 일반적으로 0.0에서 1.0 사이입니다:
+Temperature 값은 일반적으로 0.0~1.0 범위를 사용합니다.
 
-- **0.0-0.2**: 매우 집중되고 신중한 응답, 코드 분석 및 계획에 이상적
-- **0.3-0.5**: 창의성과 정확성의 균형, 일반 개발 작업에 좋음
-- **0.6-1.0**: 더 창의적이고 다양한 응답, 브레인스토밍 및 탐색에 유용함
+- **0.0-0.2**: 매우 집중되고 결정적인 응답, 코드 분석/계획에 적합
+- **0.3-0.5**: 적당한 창의성이 섞인 균형형 응답, 일반 개발 작업에 적합
+- **0.6-1.0**: 더 창의적이고 다양한 응답, 브레인스토밍/탐색에 유용
 
 ```json title="opencode.json"
 {
@@ -276,15 +276,15 @@ markdown 파일 이름은 에이전트 이름입니다. 예를 들어, `review.m
 }
 ```
 
-온도가 지정되지 않은 경우, OpenCode는 모델별 기본값을 사용합니다. 일반적으로 대부분의 모델은 0, Qwen 모델의 경우 0.55입니다.
+temperature를 지정하지 않으면 OpenCode는 model별 기본값을 사용합니다. 일반적으로 대부분의 model은 0, Qwen model은 0.55를 사용합니다.
 
 ---
 
-## 최대 단계
+### Max steps
 
-에이전트가 중지하고 사용자와 다시 상호 작용하기 전에 실행할 수 있는 최대 단계 수를 제어합니다. 이를 통해 에이전트의 행동과 비용을 제어할 수 있습니다.
+agent가 텍스트 응답만 하도록 강제되기 전까지 수행할 수 있는 agentic iteration의 최대 횟수를 제어합니다. 비용을 관리하려는 사용자에게 agentic action 제한을 제공하기 위한 옵션입니다.
 
-설정되지 않은 경우, 에이전트는 모델이 중지하거나 사용자가 세션을 중단할 때까지 계속됩니다.
+이 값을 설정하지 않으면 model이 중단을 선택하거나 사용자가 세션을 중단할 때까지 agent는 계속 반복합니다.
 
 ```json title="opencode.json"
 {
@@ -298,17 +298,17 @@ markdown 파일 이름은 에이전트 이름입니다. 예를 들어, `review.m
 }
 ```
 
-제한에 도달하면, 에이전트는 작업 요약과 권장되는 남은 작업을 신속하게 응답하도록 지시받습니다.
+제한에 도달하면 agent는 작업 요약과 남은 권장 작업을 응답하도록 지시하는 특수 시스템 prompt를 받습니다.
 
 :::caution
-레거시 `maxSteps` 필드는 더 이상 사용되지 않습니다. 대신 `steps`를 사용하십시오.
+레거시 `maxSteps` 필드는 deprecated입니다. 대신 `steps`를 사용하세요.
 :::
 
 ---
 
-#### 비활성화
+### Disable
 
-`true`로 설정하여 에이전트를 비활성화합니다.
+`true`로 설정하면 agent를 비활성화합니다.
 
 ```json title="opencode.json"
 {
@@ -322,9 +322,9 @@ markdown 파일 이름은 에이전트 이름입니다. 예를 들어, `review.m
 
 ---
 
-#### 프롬프트
+### Prompt
 
-`prompt` 구성으로 이 에이전트를 위한 사용자 정의 시스템 프롬프트 파일을 지정하십시오. 프롬프트 파일은 에이전트의 목적에 따른 지시를 포함해야 합니다.
+`prompt` config로 해당 agent의 custom 시스템 prompt 파일을 지정합니다. prompt 파일에는 agent 목적에 맞는 지시사항을 작성하세요.
 
 ```json title="opencode.json"
 {
@@ -336,16 +336,16 @@ markdown 파일 이름은 에이전트 이름입니다. 예를 들어, `review.m
 }
 ```
 
-이 경로는 구성 파일이 있는 위치를 기준으로 합니다. 따라서 글로벌 OpenCode 구성과 프로젝트별 구성 모두에서 작동합니다.
+이 경로는 config 파일 위치 기준의 상대 경로입니다. 따라서 전역 OpenCode config와 프로젝트별 config 모두에서 동일하게 동작합니다.
 
 ---
 
-### 모델
+### Model
 
-`model` 구성을 사용하여 이 에이전트에 대한 모델을 재정의합니다. 다른 작업에 최적화된 다른 모델을 사용하는 데 유용합니다. 예를 들어, 계획을 위한 빠른 모델, 구현을 위한 더 강력한 모델 등입니다.
+`model` config로 해당 agent의 model을 override할 수 있습니다. 작업 특성에 맞춰 model을 달리 쓸 때 유용합니다. 예를 들어 계획에는 더 빠른 model, 구현에는 더 강력한 model을 사용할 수 있습니다.
 
 :::tip
-모델을 지정하지 않는 경우, 기본 에이전트는 [전역 구성 모델](/docs/config#models)을 사용하며, 서브 에이전트는 자신을 호출한 기본 에이전트의 모델을 사용합니다.
+model을 지정하지 않으면 primary agent는 [전역으로 설정한 model](/docs/config#models)을 사용하고, subagent는 해당 subagent를 호출한 primary agent의 model을 사용합니다.
 :::
 
 ```json title="opencode.json"
@@ -358,13 +358,13 @@ markdown 파일 이름은 에이전트 이름입니다. 예를 들어, `review.m
 }
 ```
 
-OpenCode 구성의 모델 ID는 `provider/model-id` 형식을 사용합니다. 예를 들어, [OpenCode Zen](/docs/zen)을 사용한다면, GPT 5.1 Codex에 `opencode/gpt-5.1-codex`를 사용할 수 있습니다.
+OpenCode config의 model ID는 `provider/model-id` 형식을 사용합니다. 예를 들어 [OpenCode Zen](/docs/zen)을 사용한다면 GPT 5.1 Codex에 `opencode/gpt-5.1-codex`를 사용합니다.
 
 ---
 
-## 도구
+### Tools
 
-`tools` 구성으로 이 에이전트가 사용할 수 있는 도구를 제어합니다. `true` 또는 `false`로 설정하여 특정 도구를 활성화하거나 비활성화할 수 있습니다.
+`tools` config로 agent에서 사용할 tool을 제어합니다. 각 tool을 `true` 또는 `false`로 설정해 활성화/비활성화할 수 있습니다.
 
 ```json title="opencode.json" {3-6,9-12}
 {
@@ -385,10 +385,10 @@ OpenCode 구성의 모델 ID는 `provider/model-id` 형식을 사용합니다. 
 ```
 
 :::note
-에이전트별 구성은 글로벌 구성을 덮어씁니다.
+agent별 config는 전역 config를 override합니다.
 :::
 
-한 번에 여러 도구를 제어하기 위해 와일드카드를 사용할 수 있습니다. 예를 들어, MCP 서버에서 모든 도구를 비활성화하려면:
+와일드카드를 사용하면 여러 tool을 한 번에 제어할 수 있습니다. 예를 들어 MCP 서버의 모든 tool을 비활성화하려면 다음과 같이 설정합니다.
 
 ```json title="opencode.json"
 {
@@ -405,17 +405,17 @@ OpenCode 구성의 모델 ID는 `provider/model-id` 형식을 사용합니다. 
 }
 ```
 
-[도구에 대해 더 알아보기](/docs/tools).
+[tool에 대해 더 알아보기](/docs/tools).
 
 ---
 
-## 권한
+### Permissions
 
-에이전트가 수행할 수 있는 작업을 관리할 수 있는 권한을 구성할 수 있습니다. 현재 `edit`, `bash` 및 `webfetch` 도구에 대한 권한은 다음과 같습니다.
+permission을 설정해 agent가 수행할 수 있는 action을 제어할 수 있습니다. 현재 `edit`, `bash`, `webfetch` tool의 permission은 다음 값으로 설정할 수 있습니다.
 
-- `"ask"` - 도구를 실행하기 전에 승인 요청
-- `"allow"` - 승인 없이 모든 작업 허용
-- `"deny"` - 도구 비활성화
+- `"ask"` — tool 실행 전에 승인 요청
+- `"allow"` — 승인 없이 모든 작업 허용
+- `"deny"` — tool 비활성화
 
 ```json title="opencode.json"
 {
@@ -426,7 +426,7 @@ OpenCode 구성의 모델 ID는 `provider/model-id` 형식을 사용합니다. 
 }
 ```
 
-에이전트별로 이 권한을 재정의(override)할 수 있습니다.
+이 permission은 agent별로 override할 수 있습니다.
 
 ```json title="opencode.json" {3-5,8-10}
 {
@@ -444,7 +444,7 @@ OpenCode 구성의 모델 ID는 `provider/model-id` 형식을 사용합니다. 
 }
 ```
 
-Markdown 에이전트에서도 권한을 설정할 수 있습니다.
+Markdown agent에서도 permission을 설정할 수 있습니다.
 
 ```markdown title="~/.config/opencode/agents/review.md"
 ---
@@ -463,7 +463,7 @@ permission:
 Only analyze code and suggest changes.
 ```
 
-특정 bash 명령에 대한 권한을 설정할 수 있습니다.
+특정 bash 명령에 대해서도 permission을 설정할 수 있습니다.
 
 ```json title="opencode.json" {7}
 {
@@ -481,7 +481,7 @@ Only analyze code and suggest changes.
 }
 ```
 
-이것은 glob 패턴을 사용할 수 있습니다.
+여기에는 glob 패턴을 사용할 수 있습니다.
 
 ```json title="opencode.json" {7}
 {
@@ -498,8 +498,8 @@ Only analyze code and suggest changes.
 }
 ```
 
-또한 `*` 와일드카드를 사용하여 모든 명령에 대한 권한을 관리할 수 있습니다.
-마지막 일치 규칙이 우선하므로, `*` 와일드카드를 먼저 두고 특정 규칙을 나중에 두십시오.
+또한 `*` 와일드카드로 모든 명령의 permission을 제어할 수 있습니다.
+마지막으로 일치한 규칙이 우선하므로 `*` 와일드카드를 먼저 두고, 구체적인 규칙을 뒤에 두세요.
 
 ```json title="opencode.json" {8}
 {
@@ -517,13 +517,13 @@ Only analyze code and suggest changes.
 }
 ```
 
-[권한에 대해 더 알아보기](/docs/permissions).
+[permission에 대해 더 알아보기](/docs/permissions).
 
 ---
 
-### 모드
+### Mode
 
-`mode` 구성으로 에이전트 모드를 제어합니다. `mode` 옵션은 에이전트가 어떻게 사용될 수 있는지 결정하는 데 사용됩니다.
+`mode` config로 agent 모드를 제어합니다. `mode` 옵션은 agent를 어떤 방식으로 사용할지 결정합니다.
 
 ```json title="opencode.json"
 {
@@ -535,13 +535,13 @@ Only analyze code and suggest changes.
 }
 ```
 
-`mode` 옵션은 `primary`, `subagent`, 또는 `all`로 설정할 수 있습니다. `mode`가 지정되지 않은 경우 `all`이 기본값입니다.
+`mode`는 `primary`, `subagent`, `all` 중 하나로 설정할 수 있습니다. 설정하지 않으면 기본값은 `all`입니다.
 
 ---
 
-## 숨김
+### Hidden
 
-`hidden: true`를 사용하여 `@` 자동 완성 메뉴에서 에이전트를 숨깁니다. 작업 도구를 통해 다른 에이전트에 의해 프로그래밍 방식으로 호출되어야 하는 내부 에이전트에 유용합니다.
+`hidden: true`를 설정하면 `@` 자동완성 메뉴에서 subagent를 숨길 수 있습니다. 다른 agent가 Task tool을 통해 programmatic으로만 호출해야 하는 내부 subagent에 유용합니다.
 
 ```json title="opencode.json"
 {
@@ -554,17 +554,17 @@ Only analyze code and suggest changes.
 }
 ```
 
-자동 완성 메뉴의 사용자 가시성에만 영향을 미칩니다. 숨겨진 에이전트는 권한이 허용된다면 여전히 작업 도구를 통해 모델에 의해 호출될 수 있습니다.
+이 설정은 자동완성 메뉴에서의 사용자 가시성에만 영향을 줍니다. permission이 허용되면 hidden agent도 모델이 Task tool을 통해 호출할 수 있습니다.
 
 :::note
-`mode: subagent` 에이전트에만 적용됩니다.
+`mode: subagent` agent에만 적용됩니다.
 :::
 
 ---
 
-## 작업 권한
+### Task permissions
 
-`permission.task`와 작업 도구를 통해 에이전트가 호출할 수 있는 서브 에이전트를 제어합니다. 유연한 일치를 위한 glob 패턴을 사용합니다.
+`permission.task`로 Task tool을 통해 해당 agent가 호출할 수 있는 subagent 범위를 제어합니다. 유연한 매칭을 위해 glob 패턴을 사용합니다.
 
 ```json title="opencode.json"
 {
@@ -583,23 +583,23 @@ Only analyze code and suggest changes.
 }
 ```
 
-`deny`로 설정할 때, 서브 에이전트는 작업 도구 설명에서 완전히 제거됩니다. 따라서 모델은 그것을 호출하려고 시도하지 않습니다.
+`deny`로 설정되면 해당 subagent는 Task tool 설명에서 완전히 제거되므로 모델이 호출을 시도하지 않습니다.
 
 :::tip
-규칙은 순서대로 평가되며, **마지막 일치 규칙**이 우선합니다. 위의 예에서 `orchestrator-planner`는 `*` (deny)와 `orchestrator-*` (allow) 모두 일치하지만 `orchestrator-*`가 `*` 뒤에 오므로 결과는 `allow`입니다.
+규칙은 선언 순서대로 평가되며, **마지막으로 일치한 규칙이 승리합니다**. 위 예시에서 `orchestrator-planner`는 `*`(deny)와 `orchestrator-*`(allow) 모두에 일치하지만, `orchestrator-*`가 뒤에 있으므로 결과는 `allow`입니다.
 :::
 
 :::tip
-사용자는 에이전트의 작업 권한이 거부되더라도 `@` 자동 완성 메뉴를 통해 직접 어떤 서브 에이전트든 호출할 수 있습니다.
+사용자는 agent의 task permission이 deny여도 `@` 자동완성 메뉴를 통해 어떤 subagent든 직접 호출할 수 있습니다.
 :::
 
 ---
 
-### 색상
+### Color
 
-`color` 옵션으로 UI에서 에이전트의 시각적 모양을 사용자 정의합니다.
+`color` 옵션으로 UI에서 agent의 시각 스타일을 지정할 수 있습니다. 인터페이스에서 agent가 표시되는 방식에 영향을 줍니다.
 
-유효한 hex 색상(예: `#FF5733`) 또는 테마 색상을 사용하십시오: `primary`, `secondary`, `accent`, `success`, `warning`, `error`, `info`.
+유효한 hex 색상(예: `#FF5733`) 또는 theme 색상(`primary`, `secondary`, `accent`, `success`, `warning`, `error`, `info`)을 사용하세요.
 
 ```json title="opencode.json"
 {
@@ -618,7 +618,7 @@ Only analyze code and suggest changes.
 
 ### Top P
 
-`top_p` 옵션으로 응답의 다양성을 제어합니다. 무작위성 제어를 위한 온도의 대안입니다.
+`top_p` 옵션으로 응답 다양성을 제어합니다. 무작위성을 제어하는 Temperature의 대안입니다.
 
 ```json title="opencode.json"
 {
@@ -630,15 +630,15 @@ Only analyze code and suggest changes.
 }
 ```
 
-값은 0.0에서 1.0 사이입니다. 낮은 값은 더 집중되고, 높은 값은 더 다양합니다.
+값 범위는 0.0~1.0입니다. 값이 낮을수록 집중되고, 높을수록 다양해집니다.
 
 ---
 
-### 추가 옵션
+### Additional
 
-에이전트 구성에 지정하는 다른 옵션은 모델 옵션으로 공급자에게 **직접 전달**됩니다. 이를 통해 공급자별 기능 및 매개변수를 사용할 수 있습니다.
+agent config에 지정한 나머지 옵션은 모델 옵션으로 provider에 **그대로 전달(pass through)** 됩니다. 이를 통해 provider별 기능과 파라미터를 활용할 수 있습니다.
 
-예를 들어, OpenAI의 추론 모델과 함께, 추론 노력을 제어할 수 있습니다:
+예를 들어 OpenAI reasoning model에서는 reasoning effort를 제어할 수 있습니다.
 
 ```json title="opencode.json" {6,7}
 {
@@ -653,55 +653,55 @@ Only analyze code and suggest changes.
 }
 ```
 
-이 추가 옵션은 모델과 공급자별로 다릅니다. 사용 가능한 매개변수는 공급자의 문서를 확인하십시오.
+이 추가 옵션은 model 및 provider마다 다릅니다. 사용 가능한 파라미터는 provider 문서를 확인하세요.
 
 :::tip
-`opencode models`를 실행하여 사용 가능한 모델 목록을 볼 수 있습니다.
+사용 가능한 model 목록은 `opencode models` 명령으로 확인할 수 있습니다.
 :::
 
 ---
 
-## 에이전트 만들기
+## 에이전트 생성
 
-다음 명령을 사용하여 새로운 에이전트를 만들 수 있습니다:
+아래 명령으로 새 agent를 만들 수 있습니다.
 
 ```bash
 opencode agent create
 ```
 
-이 대화형 명령은:
+이 인터랙티브 명령은 다음을 수행합니다.
 
-1. 에이전트를 저장할 위치를 묻습니다 (전역 또는 프로젝트별).
-2. 에이전트가 해야 할 일에 대한 설명을 묻습니다.
-3. 적절한 시스템 프롬프트 및 식별자를 생성합니다.
-4. 에이전트가 접근할 수 있는 도구를 선택하게 합니다.
-5. 마지막으로, 에이전트 구성을 가진 markdown 파일을 생성합니다.
+1. agent 저장 위치를 묻습니다(전역/프로젝트).
+2. agent가 수행할 작업의 설명을 받습니다.
+3. 적절한 시스템 prompt와 식별자를 생성합니다.
+4. agent가 접근할 tool을 선택하게 합니다.
+5. 마지막으로 agent config가 담긴 Markdown 파일을 생성합니다.
 
 ---
 
 ## 사용 사례
 
-다른 에이전트를 위한 몇 가지 일반적인 사용 사례는 다음과 같습니다.
+서로 다른 agent의 대표적인 사용 사례는 다음과 같습니다.
 
-- **Build Agent**: 모든 도구와 함께 전체 개발 작업
-- **Plan Agent**: 변경 없이 분석 및 계획
-- **Review Agent**: 읽기 전용 액세스 및 문서 도구와 함께 코드 리뷰
-- **Debug Agent**: bash 및 읽기 도구와 함께 조사에 집중
-- **Docs Agent**: 파일 작업과 문서 작성을 하지만 시스템 명령 없음
+- **Build agent**: 모든 tool을 활성화한 전체 개발 작업
+- **Plan agent**: 코드 변경 없이 분석과 계획 수행
+- **Review agent**: 읽기 전용 접근 + 문서화 tool 기반 코드 리뷰
+- **Debug agent**: bash/read tool 중심의 조사 작업
+- **Docs agent**: 파일 작업은 가능하지만 시스템 명령은 없는 문서 작성 작업
 
 ---
 
-## 예제
+## 예시
 
-여기에 유용 할 수있는 몇 가지 예 에이전트가 있습니다.
+실제로 유용하게 쓸 수 있는 예시 agent를 소개합니다.
 
 :::tip
-공유하고 싶은 에이전트가 있습니까? [PR](https://github.com/anomalyco/opencode).
+공유하고 싶은 agent가 있나요? [PR 제출하기](https://github.com/anomalyco/opencode).
 :::
 
 ---
 
-### 문서 에이전트
+### Documentation agent
 
 ```markdown title="~/.config/opencode/agents/docs-writer.md"
 ---
@@ -723,7 +723,7 @@ Focus on:
 
 ---
 
-## 보안 감사
+### Security auditor
 
 ```markdown title="~/.config/opencode/agents/security-auditor.md"
 ---
diff --git a/packages/web/src/content/docs/ko/config.mdx b/packages/web/src/content/docs/ko/config.mdx
index 0357ded7857..e906eaf47b2 100644
--- a/packages/web/src/content/docs/ko/config.mdx
+++ b/packages/web/src/content/docs/ko/config.mdx
@@ -1,15 +1,15 @@
 ---
-title: 구성
-description: OpenCode JSON 구성을 사용합니다.
+title: Config
+description: Using the OpenCode JSON config.
 ---
 
-JSON 구성 파일을 사용하여 OpenCode를 구성할 수 있습니다.
+JSON config 파일로 OpenCode를 설정할 수 있습니다.
 
 ---
 
 ## 형식
 
-OpenCode는 **JSON** 및 **JSONC** (주석이 있는 JSON) 형식을 지원합니다.
+OpenCode는 **JSON**과 **JSONC**(주석이 포함된 JSON) 형식을 모두 지원합니다.
 
 ```jsonc title="opencode.jsonc"
 {
@@ -25,44 +25,44 @@ OpenCode는 **JSON** 및 **JSONC** (주석이 있는 JSON) 형식을 지원합
 
 ## 위치
 
-구성을 여러 위치에 배치할 수 있으며, 이들은 서로 다른 우선 순위(precedence)를 가집니다.
+config 파일은 여러 위치에 둘 수 있으며, 각 위치에는 우선순위가 있습니다.
 
 :::note
-구성 파일은 **병합**되며, 대체되지 않습니다.
+config 파일은 **교체되지 않고 병합**됩니다.
 :::
 
-구성 파일은 함께 병합되며 대체되지 않습니다. 다음 구성 위치의 설정이 결합됩니다. 나중의 구성은 충돌하는 키에 대해 이전 구성을 덮어씁니다. 모든 구성의 설정이 보존됩니다.
+config 파일은 서로 대체되는 방식이 아니라 병합됩니다. 아래 config 위치의 설정이 결합되며, 충돌하는 key에 대해서만 나중에 로드된 config가 앞선 값을 override합니다. 충돌하지 않는 설정은 모두 유지됩니다.
 
-예를 들어, 전역 구성이 `theme: "opencode"` 및 `autoupdate: true`를 설정하고 프로젝트 구성이 `model: "anthropic/claude-sonnet-4-5"`를 설정하면 최종 구성에는 세 가지 설정이 모두 포함됩니다.
+예를 들어, 전역 config에 `theme: "opencode"`와 `autoupdate: true`가 있고 프로젝트 config에 `model: "anthropic/claude-sonnet-4-5"`가 있으면 최종 config에는 이 세 설정이 모두 포함됩니다.
 
 ---
 
-### 우선 순위
+### 우선순위
 
-구성 소스는 다음 순서로 로드됩니다 (나중 소스가 이전 소스를 덮어씀):
+config source는 다음 순서로 로드됩니다(나중 source가 앞선 source를 override).
 
-1. **원격 구성** (`.well-known/opencode`에서) - 조직 기본값
-2. **전역 구성** (`~/.config/opencode/opencode.json`) - 사용자 환경설정
-3. **사용자 정의 구성** (`OPENCODE_CONFIG` 환경 변수) - 사용자 정의 재정의
-4. **프로젝트별 구성** (`opencode.json`) - 프로젝트별 설정
-5. **`.opencode` 디렉토리** - 에이전트, 명령, 플러그인
-6. **인라인 구성** (`OPENCODE_CONFIG_CONTENT` 환경 변수) - 런타임 재정의
+1. **Remote config**(`.well-known/opencode`) - 조직 기본값
+2. **Global config**(`~/.config/opencode/opencode.json`) - 사용자 기본 설정
+3. **Custom config**(`OPENCODE_CONFIG` env var) - custom override
+4. **Project config**(프로젝트의 `opencode.json`) - 프로젝트별 설정
+5. **`.opencode` directories** - agents, commands, plugins
+6. **Inline config**(`OPENCODE_CONFIG_CONTENT` env var) - 런타임 override
 
-이것은 프로젝트 구성이 전역 기본값을 덮어쓸 수 있고, 전역 구성이 원격 조직 기본값을 덮어쓸 수 있음을 의미합니다.
+즉, 프로젝트 config는 전역 기본값을 override할 수 있고, 전역 config는 조직의 Remote 기본값을 override할 수 있습니다.
 
 :::note
-`.opencode`와 `~/.config/opencode` 디렉토리는 하위 디렉토리에 대해 **복수형 이름**을 사용합니다: `agents/`, `commands/`, `modes/`, `plugins/`, `skills/`, `tools/`, 그리고 `themes/`. 단수형 이름(예: `agent/`)도 하위 호환성을 위해 지원됩니다.
+`.opencode` 및 `~/.config/opencode` 디렉토리는 하위 디렉토리에 **복수형 이름**을 사용합니다: `agents/`, `commands/`, `modes/`, `plugins/`, `skills/`, `tools/`, `themes/`. 단수형 이름(예: `agent/`)도 하위 호환성을 위해 지원합니다.
 :::
 
 ---
 
-### 원격
+### Remote
 
-조직은 `.well-known/opencode` 엔드포인트를 통해 기본 구성을 제공할 수 있습니다. 이를 지원하는 공급자로 인증할 때 자동으로 가져옵니다.
+조직은 `.well-known/opencode` endpoint로 기본 config를 제공할 수 있습니다. 이를 지원하는 provider로 인증하면 자동으로 가져옵니다.
 
-원격 구성은 기본 레이어로 가장 먼저 로드됩니다. 다른 구성 소스(전역, 프로젝트)는 이러한 기본값을 무시(override)할 수 있습니다.
+Remote config는 가장 먼저 로드되어 기본 레이어 역할을 합니다. 이후의 모든 config source(전역, 프로젝트)는 이 기본값을 override할 수 있습니다.
 
-예를 들어, 조직이 기본적으로 비활성화된 MCP 서버를 제공하는 경우:
+예를 들어, 조직에서 기본 비활성화된 MCP 서버를 제공하는 경우:
 
 ```json title="Remote config from .well-known/opencode"
 {
@@ -76,7 +76,7 @@ OpenCode는 **JSON** 및 **JSONC** (주석이 있는 JSON) 형식을 지원합
 }
 ```
 
-로컬 설정에서 특정 서버를 활성화할 수 있습니다:
+로컬 config에서 특정 서버를 활성화할 수 있습니다.
 
 ```json title="opencode.json"
 {
@@ -92,65 +92,65 @@ OpenCode는 **JSON** 및 **JSONC** (주석이 있는 JSON) 형식을 지원합
 
 ---
 
-## 전역
+### Global
 
-`~/.config/opencode/opencode.json`에 전역 OpenCode 구성을 배치합니다. 테마, 공급자, 키바인드와 같은 사용자 전체 기본 설정에 전역 구성을 사용하십시오.
+전역 OpenCode config는 `~/.config/opencode/opencode.json`에 두세요. theme, provider, keybind 같은 사용자 전체 기본 설정은 전역 config로 관리하세요.
 
-전역 구성은 원격 조직 기본값을 덮어씁니다.
+전역 config는 조직의 Remote 기본값을 override합니다.
 
 ---
 
-## 프로젝트별
+### Per project
 
-프로젝트 루트에 `opencode.json`을 추가합니다. 프로젝트 구성은 표준 구성 파일 중 가장 높은 우선순위를 가집니다. 이는 전역 및 원격 구성을 모두 덮어씁니다.
+프로젝트 루트에 `opencode.json`을 추가하세요. 프로젝트 config는 표준 config 파일 중 우선순위가 가장 높아 전역 및 Remote config를 모두 override합니다.
 
 :::tip
-프로젝트의 루트에 특정 설정을 둡니다.
+프로젝트별 config는 프로젝트 루트에 두세요.
 :::
 
-OpenCode가 시작될 때, 현재 디렉토리의 설정 파일이나 가장 가까운 Git 디렉토리를 찾습니다.
+OpenCode 시작 시 현재 디렉토리에서 config 파일을 찾고, 없으면 가장 가까운 Git 디렉토리까지 상위로 탐색합니다.
 
-이것은 Git으로 관리되며 전역 구성과 동일한 스키마를 사용합니다.
+이 파일은 Git에 커밋해도 안전하며 전역 config와 동일한 schema를 사용합니다.
 
 ---
 
-### 사용자 정의 경로
+### Custom path
 
-`OPENCODE_CONFIG` 환경 변수를 사용하여 사용자 정의 구성 파일 경로를 지정합니다.
+`OPENCODE_CONFIG` 환경 변수로 custom config 파일 경로를 지정하세요.
 
 ```bash
 export OPENCODE_CONFIG=/path/to/my/custom-config.json
 opencode run "Hello world"
 ```
 
-사용자 정의 구성은 우선 순위에서 전역 구성과 프로젝트 구성 사이에 로드됩니다.
+Custom config는 우선순위상 전역 config와 프로젝트 config 사이에서 로드됩니다.
 
 ---
 
-## 사용자 정의 디렉토리
+### Custom directory
 
-`OPENCODE_CONFIG_DIR` 환경 변수를 사용하여 사용자 정의 구성 디렉토리를 지정할 수 있습니다. 이 디렉토리는 표준 `.opencode` 디렉토리와 마찬가지로 에이전트, 명령, 모드 및 플러그인을 검색하며 동일한 구조를 따라야 합니다.
+`OPENCODE_CONFIG_DIR` 환경 변수로 custom config 디렉토리를 지정할 수 있습니다. 이 디렉토리는 표준 `.opencode` 디렉토리와 동일하게 agents, commands, modes, plugins를 검색하며, 동일한 구조를 따라야 합니다.
 
 ```bash
 export OPENCODE_CONFIG_DIR=/path/to/my/config-directory
 opencode run "Hello world"
 ```
 
-사용자 정의 디렉토리는 전역 구성 이후 및 `.opencode` 디렉토리 이전에 로드됩니다.
+custom 디렉토리는 전역 config와 `.opencode` 디렉토리 뒤에 로드되므로 해당 설정을 **override할 수 있습니다**.
 
 ---
 
-## 스키마
+## Schema
 
-구성 파일에는 [**`opencode.ai/config.json`**](https://opencode.ai/config.json)에 정의된 스키마가 있습니다.
+config 파일의 schema는 [**`opencode.ai/config.json`**](https://opencode.ai/config.json)에 정의되어 있습니다.
 
-편집기는 스키마에 따라 유효성 검사 및 자동 완성을 제공해야 합니다.
+편집기에서 이 schema를 기반으로 validation과 autocomplete를 사용할 수 있습니다.
 
 ---
 
-#### TUI
+### TUI
 
-`tui` 옵션을 통해 TUI 관련 설정을 구성할 수 있습니다.
+`tui` 옵션으로 TUI 관련 설정을 구성할 수 있습니다.
 
 ```json title="opencode.json"
 {
@@ -165,19 +165,19 @@ opencode run "Hello world"
 }
 ```
 
-유효한 옵션:
+사용 가능한 옵션:
 
 - `scroll_acceleration.enabled` - macOS 스타일 스크롤 가속을 활성화합니다. **`scroll_speed`보다 우선합니다.**
-- `scroll_speed` - 사용자 정의 스크롤 속도 배수 (기본값: `3`, 최소값: `1`). `scroll_acceleration.enabled`가 `true`이면 무시됩니다.
-- `diff_style` - diff 렌더링을 제어합니다. `"auto"`는 터미널 너비에 맞추고, `"stacked"`는 항상 단일 열을 보여줍니다.
+- `scroll_speed` - 사용자 정의 스크롤 속도 배수(기본: `3`, 최소: `1`). `scroll_acceleration.enabled`가 `true`이면 무시됩니다.
+- `diff_style` - diff 렌더링 방식을 제어합니다. `"auto"`는 터미널 너비에 맞춰 조정되고, `"stacked"`는 항상 단일 컬럼으로 표시합니다.
 
-[TUI 사용법에 대해 더 알아보기](/docs/tui).
+[TUI에 대해 더 알아보기](/docs/tui).
 
 ---
 
-## 서버
+### Server
 
-`opencode serve` 및 `opencode web` 명령에 대한 서버 설정을 구성할 수 있습니다.
+`server` 옵션으로 `opencode serve`와 `opencode web` 명령의 server 설정을 구성할 수 있습니다.
 
 ```json title="opencode.json"
 {
@@ -192,21 +192,21 @@ opencode run "Hello world"
 }
 ```
 
-유효한 옵션:
+사용 가능한 옵션:
 
-- `port` - 리스닝 포트.
-- `hostname` - 리스닝 호스트 이름. `mdns`가 활성화되고 hostname이 설정되지 않으면 `0.0.0.0`이 기본값이 됩니다.
-- `mdns` - mDNS 서비스 발견 활성화. 로컬 네트워크의 다른 장치가 OpenCode 서버를 찾을 수 있습니다.
-- `mdnsDomain` - mDNS 서비스를 위한 사용자 정의 도메인 이름. 기본값은 `opencode.local`입니다. 동일한 네트워크에서 여러 인스턴스를 실행할 때 유용합니다.
-- `cors` - 브라우저 기반 클라이언트에서 HTTP 서버를 사용할 때 CORS를 허용할 추가 출처(Origin). 값은 전체 출처(스킴 + 호스트 + 선택적 포트)여야 합니다. 예: `https://app.example.com`.
+- `port` - 수신할 포트입니다.
+- `hostname` - 수신할 호스트명입니다. `mdns`가 활성화되어 있고 hostname이 없으면 기본값은 `0.0.0.0`입니다.
+- `mdns` - mDNS service discovery를 활성화합니다. 네트워크 내 다른 기기에서 OpenCode server를 찾을 수 있습니다.
+- `mdnsDomain` - mDNS service의 custom 도메인 이름입니다. 기본값은 `opencode.local`입니다. 같은 네트워크에서 여러 인스턴스를 실행할 때 유용합니다.
+- `cors` - 브라우저 기반 client에서 HTTP server를 사용할 때 허용할 추가 CORS origin입니다. 값은 전체 origin(scheme + host + optional port) 형식이어야 하며, 예: `https://app.example.com`.
 
-[서버에 대해 더 알아보기](/docs/server).
+[server에 대해 더 알아보기](/docs/server).
 
 ---
 
-## 도구
+### Tools
 
-`tools` 옵션을 통해 LLM이 사용할 수 있는 도구를 구성할 수 있습니다.
+`tools` 옵션으로 LLM이 사용할 수 있는 tool을 관리할 수 있습니다.
 
 ```json title="opencode.json"
 {
@@ -218,13 +218,13 @@ opencode run "Hello world"
 }
 ```
 
-[도구에 대해 더 알아보기](/docs/tools).
+[tool에 대해 더 알아보기](/docs/tools).
 
 ---
 
-## 모델
+### Models
 
-`provider`, `model`, `small_model` 옵션을 통해 OpenCode 구성에서 사용할 공급자와 모델을 구성할 수 있습니다.
+OpenCode config의 `provider`, `model`, `small_model` 옵션으로 사용할 provider와 model을 설정할 수 있습니다.
 
 ```json title="opencode.json"
 {
@@ -235,9 +235,9 @@ opencode run "Hello world"
 }
 ```
 
-`small_model` 옵션은 제목 생성과 같은 가벼운 작업을 위한 별도의 모델을 구성합니다. 기본적으로, OpenCode는 공급자에게서 사용 가능한 더 저렴한 모델이 있다면 그것을 사용하고, 그렇지 않으면 주 모델로 돌아갑니다.
+`small_model`은 제목 생성 같은 경량 작업에 사용할 별도 model을 설정합니다. 기본적으로 OpenCode는 provider에서 더 저렴한 model을 사용할 수 있으면 우선 사용하고, 없으면 메인 model로 fallback합니다.
 
-공급자 옵션은 `timeout`과 `setCacheKey`를 포함할 수 있습니다:
+provider 옵션에는 `timeout`, `setCacheKey`를 포함할 수 있습니다.
 
 ```json title="opencode.json"
 {
@@ -253,20 +253,20 @@ opencode run "Hello world"
 }
 ```
 
-- `timeout` - 요청 타임아웃(밀리초) (기본값: 300000). `false`로 설정하여 비활성화할 수 있습니다.
-- `setCacheKey` - 지정된 공급자에 대해 캐시 키가 항상 설정되도록 강제합니다.
+- `timeout` - 요청 timeout(밀리초, 기본값: 300000). `false`로 비활성화할 수 있습니다.
+- `setCacheKey` - 지정된 provider에 대해 cache key가 항상 설정되도록 보장합니다.
 
-[로컬 모델](/docs/models#local)을 구성할 수도 있습니다. [더 알아보기](/docs/models).
+[local model](/docs/models#local)도 설정할 수 있습니다. [더 알아보기](/docs/models).
 
 ---
 
-### 공급자별 옵션
+#### Provider-Specific Options
 
-일반적인 `timeout` 및 `apiKey` 외에도 일부 공급자는 추가 구성 옵션을 지원합니다.
+일부 provider는 공통 옵션인 `timeout`, `apiKey` 외에 추가 config 옵션을 지원합니다.
 
 ##### Amazon Bedrock
 
-Amazon Bedrock는 AWS 관련 구성을 지원합니다:
+Amazon Bedrock은 AWS 전용 config를 지원합니다.
 
 ```json title="opencode.json"
 {
@@ -283,21 +283,21 @@ Amazon Bedrock는 AWS 관련 구성을 지원합니다:
 }
 ```
 
-- `region` - Bedrock를 위한 AWS 리전 (`AWS_REGION` 환경 변수 또는 `us-east-1`이 기본값)
-- `profile` - `~/.aws/credentials`의 AWS 프로필 이름 (`AWS_PROFILE` 환경 변수가 기본값)
-- `endpoint` - VPC 엔드포인트 등을 위한 사용자 정의 엔드포인트 URL. 이는 AWS 관련 용어를 사용한 일반적인 `baseURL` 옵션의 별칭입니다. 둘 다 지정된 경우 `endpoint`가 우선합니다.
+- `region` - Bedrock용 AWS 리전(`AWS_REGION` env var 또는 기본값 `us-east-1`)
+- `profile` - `~/.aws/credentials`의 AWS named profile(기본값: `AWS_PROFILE` env var)
+- `endpoint` - VPC endpoint용 custom endpoint URL입니다. AWS 용어를 사용한 일반 `baseURL` 옵션의 별칭(alias)입니다. 둘 다 지정하면 `endpoint`가 우선합니다.
 
 :::note
-Bearer 토큰(`AWS_BEARER_TOKEN_BEDROCK` 또는 `/connect`)은 프로필 기반 인증보다 우선합니다. 자세한 내용은 [인증 우선 순위](/docs/providers#authentication-precedence)를 참조하십시오.
+Bearer token(`AWS_BEARER_TOKEN_BEDROCK` 또는 `/connect`)은 profile 기반 인증보다 우선합니다. 자세한 내용은 [authentication precedence](/docs/providers#authentication-precedence)를 참고하세요.
 :::
 
-[Amazon Bedrock에 대해 더 알아보기](/docs/providers#amazon-bedrock).
+[Amazon Bedrock config 더 알아보기](/docs/providers#amazon-bedrock).
 
 ---
 
-## 테마
+### Themes
 
-`theme` 옵션을 통해 OpenCode 구성에서 사용할 테마를 설정할 수 있습니다.
+`theme` 옵션으로 OpenCode config에서 사용할 theme를 설정할 수 있습니다.
 
 ```json title="opencode.json"
 {
@@ -310,9 +310,9 @@ Bearer 토큰(`AWS_BEARER_TOKEN_BEDROCK` 또는 `/connect`)은 프로필 기반
 
 ---
 
-## 에이전트
+### Agents
 
-`agent` 옵션을 통해 특정 작업을 전문으로 하는 에이전트를 구성할 수 있습니다.
+`agent` 옵션으로 특정 작업용 전문 agent를 구성할 수 있습니다.
 
 ```jsonc title="opencode.jsonc"
 {
@@ -332,13 +332,13 @@ Bearer 토큰(`AWS_BEARER_TOKEN_BEDROCK` 또는 `/connect`)은 프로필 기반
 }
 ```
 
-`~/.config/opencode/agents/` 또는 `.opencode/agents/`에서 Markdown 파일을 사용하여 에이전트를 정의할 수도 있습니다. [더 알아보기](/docs/agents).
+`~/.config/opencode/agents/` 또는 `.opencode/agents/`의 Markdown 파일로 agent를 정의할 수도 있습니다. [더 알아보기](/docs/agents).
 
 ---
 
-### 기본 에이전트
+### Default agent
 
-`default_agent` 옵션을 사용하여 기본 에이전트를 설정할 수 있습니다. 명시적으로 지정되지 않았을 때 어떤 에이전트가 사용될지 결정합니다.
+`default_agent` 옵션으로 기본 agent를 설정할 수 있습니다. 별도 지정이 없을 때 어떤 agent를 사용할지 결정합니다.
 
 ```json title="opencode.json"
 {
@@ -347,15 +347,15 @@ Bearer 토큰(`AWS_BEARER_TOKEN_BEDROCK` 또는 `/connect`)은 프로필 기반
 }
 ```
 
-기본 에이전트는 기본(primary) 에이전트여야 합니다(서브 에이전트 불가). `"build"` 또는 `"plan"`과 같은 내장 에이전트이거나 정의된 [사용자 정의 에이전트](./agents)일 수 있습니다. 지정된 에이전트가 존재하지 않는 경우, OpenCode는 경고와 함께 `"build"`로 돌아갑니다.
+기본 agent는 primary agent여야 합니다(subagent 불가). `"build"`, `"plan"` 같은 내장 agent나 직접 정의한 [custom agent](/docs/agents)를 지정할 수 있습니다. 지정한 agent가 없거나 subagent이면 OpenCode는 경고와 함께 `"build"`로 fallback합니다.
 
-이 설정은 모든 인터페이스에 적용됩니다: TUI, CLI (`opencode run`), 데스크톱 앱 및 GitHub Action.
+이 설정은 TUI, CLI(`opencode run`), 데스크톱 앱, GitHub Action 등 모든 인터페이스에 적용됩니다.
 
 ---
 
-## 공유
+### Sharing
 
-`share` 옵션을 통해 [공유](/docs/share) 기능을 구성할 수 있습니다.
+`share` 옵션으로 [share](/docs/share) 기능을 설정할 수 있습니다.
 
 ```json title="opencode.json"
 {
@@ -364,19 +364,19 @@ Bearer 토큰(`AWS_BEARER_TOKEN_BEDROCK` 또는 `/connect`)은 프로필 기반
 }
 ```
 
-값은 다음과 같습니다:
+허용 값:
 
-- `"manual"` - 명령을 통한 수동 공유 허용 (기본값)
-- `"auto"` - 새로운 대화를 자동으로 공유
-- `"disabled"` - 공유 기능 완전히 비활성화
+- `"manual"` - 명령으로 수동 공유 허용(기본값)
+- `"auto"` - 새 대화를 자동 공유
+- `"disabled"` - 공유 기능 완전 비활성화
 
-기본적으로 `/share` 명령을 사용하여 대화를 명시적으로 공유해야 하는 수동 모드로 설정됩니다.
+기본값은 manual 모드이며, `/share` 명령으로 명시적으로 공유해야 합니다.
 
 ---
 
-## 명령
+### Commands
 
-`command` 옵션을 통해 반복 작업을 위한 사용자 정의 명령을 구성할 수 있습니다.
+`command` 옵션으로 반복 작업용 custom command를 구성할 수 있습니다.
 
 ```jsonc title="opencode.jsonc"
 {
@@ -387,8 +387,6 @@ Bearer 토큰(`AWS_BEARER_TOKEN_BEDROCK` 또는 `/connect`)은 프로필 기반
       "description": "Run tests with coverage",
       "agent": "build",
       "model": "anthropic/claude-haiku-4-5",
-      "agent": "build",
-      "model": "anthropic/claude-haiku-4-5",
     },
     "component": {
       "template": "Create a new React component named $ARGUMENTS with TypeScript support.\nInclude proper typing and basic structure.",
@@ -398,13 +396,13 @@ Bearer 토큰(`AWS_BEARER_TOKEN_BEDROCK` 또는 `/connect`)은 프로필 기반
 }
 ```
 
-`~/.config/opencode/commands/` 또는 `.opencode/commands/`에서 Markdown 파일을 사용하여 명령을 정의할 수도 있습니다. [더 알아보기](/docs/commands).
+`~/.config/opencode/commands/` 또는 `.opencode/commands/`의 Markdown 파일로 command를 정의할 수도 있습니다. [더 알아보기](/docs/commands).
 
 ---
 
-## 키바인드
+### Keybinds
 
-`keybinds` 옵션을 통해 키바인드를 사용자 정의할 수 있습니다.
+`keybinds` 옵션으로 keybind를 커스터마이즈할 수 있습니다.
 
 ```json title="opencode.json"
 {
@@ -417,9 +415,9 @@ Bearer 토큰(`AWS_BEARER_TOKEN_BEDROCK` 또는 `/connect`)은 프로필 기반
 
 ---
 
-## 자동 업데이트
+### Autoupdate
 
-OpenCode는 시작될 때 자동으로 새로운 업데이트를 다운로드합니다. `autoupdate` 옵션으로 이를 비활성화할 수 있습니다.
+OpenCode는 시작 시 새 업데이트를 자동으로 다운로드합니다. `autoupdate` 옵션으로 비활성화할 수 있습니다.
 
 ```json title="opencode.json"
 {
@@ -428,14 +426,14 @@ OpenCode는 시작될 때 자동으로 새로운 업데이트를 다운로드합
 }
 ```
 
-업데이트를 원하지 않지만 새 버전을 알림받고 싶다면 `autoupdate`를 `"notify"`로 설정하십시오.
-Homebrew와 같은 패키지 관리자를 사용하여 설치되지 않은 경우에만 작동합니다.
+업데이트를 자동 적용하지 않고 새 버전 알림만 받고 싶다면 `autoupdate`를 `"notify"`로 설정하세요.
+이 옵션은 Homebrew 같은 패키지 매니저로 설치하지 않은 경우에만 동작합니다.
 
 ---
 
-## 포매터
+### Formatters
 
-`formatter` 옵션을 통해 코드 포매터를 구성할 수 있습니다.
+`formatter` 옵션으로 코드 formatter를 설정할 수 있습니다.
 
 ```json title="opencode.json"
 {
@@ -455,15 +453,15 @@ Homebrew와 같은 패키지 관리자를 사용하여 설치되지 않은 경
 }
 ```
 
-[포매터에 대해 더 알아보기](/docs/formatters).
+[formatter에 대해 더 알아보기](/docs/formatters).
 
 ---
 
-## 권한
+### Permissions
 
-기본적으로, OpenCode는 **명시적 승인 없이 모든 작업을 허용**합니다. `permission` 옵션을 사용하여 이를 변경할 수 있습니다.
+기본적으로 OpenCode는 **명시적 승인 없이 모든 작업을 허용**합니다. `permission` 옵션으로 이 동작을 바꿀 수 있습니다.
 
-예를 들어, `edit` 및 `bash` 도구가 사용자 승인을 요구하도록 설정하려면:
+예를 들어 `edit`, `bash` tool이 사용자 승인을 요구하게 하려면:
 
 ```json title="opencode.json"
 {
@@ -475,32 +473,34 @@ Homebrew와 같은 패키지 관리자를 사용하여 설치되지 않은 경
 }
 ```
 
-[권한에 대해 더 알아보기](/docs/permissions).
+[permission에 대해 더 알아보기](/docs/permissions).
 
 ---
 
-### 압축
+### Compaction
 
-`compaction` 옵션을 통해 컨텍스트 압축 동작을 제어할 수 있습니다.
+`compaction` 옵션으로 context compaction 동작을 제어할 수 있습니다.
 
 ```json title="opencode.json"
 {
   "$schema": "https://opencode.ai/config.json",
   "compaction": {
     "auto": true,
-    "prune": true
+    "prune": true,
+    "reserved": 10000
   }
 }
 ```
 
-- `auto` - 컨텍스트가 꽉 차면 자동으로 세션을 압축합니다 (기본값: `true`).
-- `prune` - 토큰을 절약하기 위해 오래된 도구 출력을 제거합니다 (기본값: `true`).
+- `auto` - context가 가득 찼을 때 세션을 자동 compact합니다(기본값: `true`).
+- `prune` - token 절약을 위해 오래된 tool 출력을 제거합니다(기본값: `true`).
+- `reserved` - compaction용 token buffer입니다. compaction 중 overflow가 나지 않도록 충분한 window를 남깁니다.
 
 ---
 
-### 파일 감시자
+### Watcher
 
-`watcher` 옵션을 통해 파일 감시자가 무시할 패턴을 설정할 수 있습니다.
+`watcher` 옵션으로 파일 watcher ignore 패턴을 설정할 수 있습니다.
 
 ```json title="opencode.json"
 {
@@ -511,13 +511,13 @@ Homebrew와 같은 패키지 관리자를 사용하여 설치되지 않은 경
 }
 ```
 
-패턴은 glob 구문을 따릅니다. 잡음이 많은 디렉토리를 제외하는 데 사용하십시오.
+패턴은 glob 문법을 따릅니다. 파일 감시에서 노이즈가 많은 디렉토리를 제외할 때 유용합니다.
 
 ---
 
-### MCP 서버
+### MCP servers
 
-`mcp` 옵션을 통해 사용하려는 MCP 서버를 구성할 수 있습니다.
+`mcp` 옵션으로 사용할 MCP server를 설정할 수 있습니다.
 
 ```json title="opencode.json"
 {
@@ -530,11 +530,11 @@ Homebrew와 같은 패키지 관리자를 사용하여 설치되지 않은 경
 
 ---
 
-### 플러그인
+### Plugins
 
-[플러그인](/docs/plugins)은 사용자 정의 도구, 훅(hook), 통합으로 OpenCode를 확장합니다.
+[Plugins](/docs/plugins)는 custom tool, hook, integration으로 OpenCode를 확장합니다.
 
-`.opencode/plugins/` 또는 `~/.config/opencode/plugins/`에 플러그인 파일을 배치하십시오. `plugin` 옵션을 통해 npm에서 플러그인을 로드할 수 있습니다.
+plugin 파일은 `.opencode/plugins/` 또는 `~/.config/opencode/plugins/`에 두세요. `plugin` 옵션으로 npm plugin을 로드할 수도 있습니다.
 
 ```json title="opencode.json"
 {
@@ -547,9 +547,9 @@ Homebrew와 같은 패키지 관리자를 사용하여 설치되지 않은 경
 
 ---
 
-### 지침
+### Instructions
 
-`instructions` 옵션을 통해 모델에 대한 지침(Rules)을 구성할 수 있습니다.
+`instructions` 옵션으로 사용 중인 model에 제공할 지침 파일을 설정할 수 있습니다.
 
 ```json title="opencode.json"
 {
@@ -558,13 +558,13 @@ Homebrew와 같은 패키지 관리자를 사용하여 설치되지 않은 경
 }
 ```
 
-지침 파일에 대한 경로와 glob 패턴의 배열을 사용합니다. [규칙에 대해 더 알아보기](/docs/rules).
+이 옵션은 지침 파일 경로 및 glob 패턴 배열을 받습니다. [rules에 대해 더 알아보기](/docs/rules).
 
 ---
 
-## 비활성화된 공급자
+### Disabled providers
 
-`disabled_providers` 옵션을 통해 자동으로 로드되는 공급자를 비활성화할 수 있습니다. 자격 증명이 유효하더라도 특정 공급자가 로드되는 것을 방지할 때 유용합니다.
+`disabled_providers` 옵션으로 자동 로드되는 provider를 비활성화할 수 있습니다. credential이 있어도 특정 provider를 로드하지 않게 하고 싶을 때 유용합니다.
 
 ```json title="opencode.json"
 {
@@ -577,17 +577,17 @@ Homebrew와 같은 패키지 관리자를 사용하여 설치되지 않은 경
 `disabled_providers`는 `enabled_providers`보다 우선합니다.
 :::
 
-`disabled_providers` 옵션은 공급자 ID의 배열을 허용합니다. 공급자가 비활성화되면:
+`disabled_providers`는 provider ID 배열을 받습니다. provider가 비활성화되면:
 
-- 환경 변수가 설정된 경우에도 로드되지 않습니다.
-- API 키가 `/connect` 명령을 통해 구성되는 경우에도 로드되지 않습니다.
-- 공급자의 모델은 모델 선택 목록에 표시되지 않습니다.
+- 환경 변수가 설정되어 있어도 로드되지 않습니다.
+- `/connect` 명령으로 API key를 설정해도 로드되지 않습니다.
+- 해당 provider의 model은 model 선택 목록에 표시되지 않습니다.
 
 ---
 
-### 활성화된 공급자
+### Enabled providers
 
-`enabled_providers` 옵션을 통해 허용할 공급자를 지정할 수 있습니다. 설정하면 지정된 공급자만 활성화되고 다른 모든 공급자는 무시됩니다.
+`enabled_providers` 옵션으로 provider allowlist를 지정할 수 있습니다. 이 값을 설정하면 지정한 provider만 활성화되고 나머지는 무시됩니다.
 
 ```json title="opencode.json"
 {
@@ -596,19 +596,19 @@ Homebrew와 같은 패키지 관리자를 사용하여 설치되지 않은 경
 }
 ```
 
-OpenCode를 제한하여 특정 공급자만 사용하도록 할 때 유용합니다.
+provider를 하나씩 비활성화하는 대신, OpenCode가 특정 provider만 사용하도록 제한하고 싶을 때 유용합니다.
 
 :::note
 `disabled_providers`는 `enabled_providers`보다 우선합니다.
 :::
 
-공급자가 `enabled_providers`와 `disabled_providers` 둘 다에 나타나면, 하위 호환성을 위해 `disabled_providers`가 우선합니다.
+동일 provider가 `enabled_providers`와 `disabled_providers`에 모두 있으면 하위 호환성을 위해 `disabled_providers`가 우선합니다.
 
 ---
 
-### 실험적 기능
+### Experimental
 
-`experimental` 키는 활발히 개발 중인 옵션을 포함합니다.
+`experimental` key에는 현재 활발히 개발 중인 옵션이 포함됩니다.
 
 ```json title="opencode.json"
 {
@@ -618,20 +618,20 @@ OpenCode를 제한하여 특정 공급자만 사용하도록 할 때 유용합
 ```
 
 :::caution
-실험적 옵션은 안정적이지 않습니다. 예고 없이 변경되거나 제거될 수 있습니다.
+experimental 옵션은 안정적이지 않습니다. 예고 없이 변경되거나 제거될 수 있습니다.
 :::
 
 ---
 
-## 변수
+## Variables
 
-구성 파일에서 환경 변수를 참조하고 파일 내용에 대한 변수 대체를 사용할 수 있습니다.
+config 파일에서 환경 변수와 파일 내용을 참조할 수 있도록 변수 치환을 사용할 수 있습니다.
 
 ---
 
-##### 환경 변수
+### Env vars
 
-`{env:VARIABLE_NAME}`을 사용하여 환경 변수를 대체합니다.
+`{env:VARIABLE_NAME}` 형식으로 환경 변수를 치환할 수 있습니다.
 
 ```json title="opencode.json"
 {
@@ -648,13 +648,13 @@ OpenCode를 제한하여 특정 공급자만 사용하도록 할 때 유용합
 }
 ```
 
-환경 변수가 설정되지 않으면 빈 문자열로 대체됩니다.
+환경 변수가 설정되지 않았으면 빈 문자열로 치환됩니다.
 
 ---
 
-## 파일
+### Files
 
-`{file:path/to/file}`를 사용하여 파일의 내용을 대체합니다.
+`{file:path/to/file}` 형식으로 파일 내용을 치환할 수 있습니다.
 
 ```json title="opencode.json"
 {
@@ -670,13 +670,13 @@ OpenCode를 제한하여 특정 공급자만 사용하도록 할 때 유용합
 }
 ```
 
-파일 경로는:
+파일 경로는 다음을 지원합니다.
 
-- 구성 파일 디렉토리에 상대적이거나
-- `/` 또는 `~`로 시작하는 절대 경로여야 합니다.
+- config 파일 디렉토리 기준 상대 경로
+- `/` 또는 `~`로 시작하는 절대 경로
 
-이것은 다음에 유용합니다:
+이 기능은 다음 상황에 유용합니다.
 
-- API 키와 같은 민감한 데이터를 별도의 파일에 유지할 때.
-- 구성을 어지럽히지 않고 큰 지침 파일을 포함할 때.
-- 여러 구성 파일에서 공통 구성 스니펫을 공유할 때.
+- API key 같은 민감 정보를 별도 파일로 분리
+- 큰 지침 파일을 config를 복잡하게 만들지 않고 포함
+- 여러 config 파일에서 공통 설정 스니펫 재사용
diff --git a/packages/web/src/content/docs/ko/custom-tools.mdx b/packages/web/src/content/docs/ko/custom-tools.mdx
index 5da050f49bd..77310557faa 100644
--- a/packages/web/src/content/docs/ko/custom-tools.mdx
+++ b/packages/web/src/content/docs/ko/custom-tools.mdx
@@ -1,30 +1,30 @@
 ---
-title: 사용자 정의 도구
-description: OpenCode에서 LLM이 호출할 수 있는 도구를 만듭니다.
+title: Custom Tools
+description: Create tools the LLM can call in OpenCode.
 ---
 
-사용자 정의 도구는 LLM이 대화 중에 호출 할 수있는 기능을 만듭니다. 그들은 `read`, `write` 및 `bash`와 같은 opencode의 [붙박이 도구](./tools)와 함께 작동합니다.
+custom tool은 대화 중 LLM이 호출할 수 있도록 사용자가 직접 만든 함수입니다. `read`, `write`, `bash` 같은 OpenCode의 [built-in tools](/docs/tools)와 함께 동작합니다.
 
 ---
 
 ## 도구 만들기
 
-도구는 **TypeScript** 또는 **JavaScript** 파일로 정의됩니다. 그러나 도구 정의는 ** 어떤 언어로 작성된 스크립트를 호출 할 수 있습니다 ** - TypeScript 또는 JavaScript는 도구 정의 자체에서만 사용됩니다.
+tool은 **TypeScript** 또는 **JavaScript** 파일로 정의합니다. 다만 tool 정의에서 호출하는 스크립트는 **어떤 언어든** 사용할 수 있습니다. 즉, TypeScript/JavaScript는 tool 정의 자체에만 필요합니다.
 
 ---
 
-## 위치
+### 위치
 
-그들은 정의 할 수 있습니다:
+tool은 다음 위치에 둘 수 있습니다.
 
-- 프로젝트의 `.opencode/tools/` 디렉토리에 배치하여 로컬.
-- 또는 전 세계적으로 `~/.config/opencode/tools/`에 배치하여.
+- 프로젝트의 `.opencode/tools/` 디렉토리(로컬)
+- `~/.config/opencode/tools/` 디렉토리(전역)
 
 ---
 
-## 구조
+### 구조
 
-도구를 만드는 가장 쉬운 방법은 `tool()` helper를 사용하여 유형 안전 및 검증을 제공합니다.
+tool을 가장 쉽게 만드는 방법은 타입 안정성과 validation을 제공하는 `tool()` helper를 사용하는 것입니다.
 
 ```ts title=".opencode/tools/database.ts" {1}
 import { tool } from "@opencode-ai/plugin"
@@ -41,13 +41,13 @@ export default tool({
 })
 ```
 
-**파일 이름**는 **tool name**가 됩니다. 위는 `database` 공구를 만듭니다.
+**파일 이름**이 **tool 이름**이 됩니다. 위 예시는 `database` tool을 생성합니다.
 
 ---
 
-### 파일당 여러 도구
+#### 파일 하나에 여러 tool 정의
 
-단일 파일에서 여러 도구를 수출할 수 있습니다. 각 수출은 ** 별도의 도구 ** 이름 ** `<filename>_<exportname>`**:
+하나의 파일에서 여러 tool을 export할 수도 있습니다. 각 export는 **별도의 tool**이 되며 이름은 **`<filename>_<exportname>`** 형식을 사용합니다.
 
 ```ts title=".opencode/tools/math.ts"
 import { tool } from "@opencode-ai/plugin"
@@ -75,13 +75,13 @@ export const multiply = tool({
 })
 ```
 
-이것은 2개의 공구를 만듭니다: `math_add`와 `math_multiply`.
+이 경우 `math_add`, `math_multiply` 두 tool이 생성됩니다.
 
 ---
 
-#### 스키마
+### 인자
 
-`tool.schema`를 사용할 수 있습니다, 그냥 [Zod](https://zod.dev), 인수 유형을 정의합니다.
+인자 타입은 `tool.schema`로 정의할 수 있습니다. `tool.schema`는 [Zod](https://zod.dev) 기반입니다.
 
 ```ts "tool.schema"
 args: {
@@ -89,7 +89,7 @@ args: {
 }
 ```
 
-[Zod](https://zod.dev)를 직접 가져오고 일반 객체를 반환할 수 있습니다.
+[Zod](https://zod.dev)를 직접 import해서 일반 객체를 반환하는 방식도 사용할 수 있습니다.
 
 ```ts {6}
 import { z } from "zod"
@@ -108,9 +108,9 @@ export default {
 
 ---
 
-### 컨텍스트
+### Context
 
-도구는 현재 세션에 대한 컨텍스트를받습니다.
+tool은 현재 세션의 context 정보를 전달받습니다.
 
 ```ts title=".opencode/tools/project.ts" {8}
 import { tool } from "@opencode-ai/plugin"
@@ -126,18 +126,18 @@ export default tool({
 })
 ```
 
-세션 작업 디렉토리에 `context.directory`를 사용합니다.
-git worktree 루트에 `context.worktree`를 사용합니다.
+세션 작업 디렉토리는 `context.directory`를 사용하세요.
+git worktree 루트는 `context.worktree`를 사용하세요.
 
 ---
 
-## 예제
+## 예시
 
-### Python 도구 작성
+### Python으로 tool 작성
 
-원하는 모든 언어로 도구를 쓸 수 있습니다. 여기에 Python을 사용하여 두 개의 숫자를 추가하는 예입니다.
+tool은 원하는 언어로 작성할 수 있습니다. 아래는 Python으로 두 숫자를 더하는 예시입니다.
 
-먼저 Python 스크립트로 도구를 만듭니다.
+먼저 Python 스크립트로 tool을 만듭니다.
 
 ```python title=".opencode/tools/add.py"
 import sys
@@ -147,7 +147,7 @@ b = int(sys.argv[2])
 print(a + b)
 ```
 
-그런 다음 도구 정의를 만듭니다.
+그다음 이 스크립트를 호출하는 tool 정의를 만듭니다.
 
 ```ts title=".opencode/tools/python-add.ts" {10}
 import { tool } from "@opencode-ai/plugin"
@@ -167,4 +167,4 @@ export default tool({
 })
 ```
 
-여기에 우리는 [`Bun.$`](https://bun.com/docs/runtime/shell) 유틸리티를 사용하여 Python 스크립트를 실행합니다.
+여기서는 Python 스크립트를 실행하기 위해 [`Bun.$`](https://bun.com/docs/runtime/shell) 유틸리티를 사용합니다.