sonamu 0.8.24 → 0.8.25

package/src/skills/sonamu/SKILL.md

@@ -1,196 +1,195 @@
 ---
 name: sonamu
-description: Sonamu TypeScript 풀스택 프레임워크 개발 가이드. Entity, Model, API, 테스트, 프론트엔드 연동. Use when developing with Sonamu framework.
+description: Sonamu TypeScript full-stack framework development guide. Entity, Model, API, testing, and frontend integration. Use when developing with Sonamu framework.
 ---
 
 # Sonamu Framework Skills
 
-Sonamu 프레임워크로 프로젝트를 개발하기 위한 Claude Code skill입니다.
+Claude Code skill for developing projects with the Sonamu framework.
 
-## CRITICAL: 질문은 하나씩
+## CRITICAL: Ask one question at a time
 
 **MUST ask questions one at a time. NEVER overwhelm users with multiple questions.**
 
 ### MUST DO
-- 질문 하나 → 사용자 응답 대기 → 다음 질문
-- 간결하게 질문
-- 선택지가 있으면 명확하게 제시
+- One question → wait for user response → next question
+- Keep questions concise
+- Present choices clearly when options are available
 
 ### NEVER DO
-- 여러 질문을 한꺼번에 나열
-- 긴 설명과 함께 질문
-- 확인사항 목록을 주루룩 출력
+- List multiple questions at once
+- Ask questions alongside long explanations
+- Output a checklist of confirmation items all at once
 
 ---
 
-## 개발 흐름
+## Development Flow
 
 ```
-PHASE 0: 프로젝트 생성 및 초기 설정  (프로젝트 생성 → 도메인 식별 → auth generate → Users 시퀀스 설정)
-PHASE 1: 도메인 Logic 문서화        (도메인별 contract/{domain}/*.contract.md 작성 → 사용자 확인 완료)
-PHASE 2: 엔티티 설계                (사용자와 함께 설계 확인)
-PHASE 3: 엔티티 생성 및 마이그레이션  (entity.json + migration + cone + scaffolding)
-PHASE 4: 테스트 및 API 구현          (contract→Claim→AC→implement 반복)
-PHASE 5: Fixture 생성               (사용자 승인 후 LLM으로 생성)
-PHASE 6: Frontend 개발              (batch별 진행, 사용자 확인)
+PHASE 0: Project creation and initial setup  (create project → identify domains → auth generate → Users sequence setup)
+PHASE 1: Domain logic documentation          (write contract/{domain}/*.contract.md per domain → user confirmation)
+PHASE 2: Entity design                       (design with user confirmation)
+PHASE 3: Entity creation and migration       (entity.json + migration + cone + scaffolding)
+PHASE 4: Testing and API implementation      (contract → Claim → AC → implement, repeat)
+PHASE 5: Fixture generation                  (generate with LLM after user approval)
+PHASE 6: Frontend development                (proceed in batches with user confirmation)
 ```
 
-**상세 내용:** `workflow.md` 참조
+**Full details:** see `.claude/workflow/project_init.md`
 
-### 시작 지점 판단
+### Starting Point Determination
 
-**사용자의 지시에 따라 적절한 PHASE부터 시작한다.** 무조건 PHASE 0부터 시작하지 않는다.
+**Begin from the PHASE that matches the user's instruction.** Do not always start from PHASE 0.
 
-| 사용자 지시 | 시작 PHASE | 전제 조건 확인 |
-|------------|------------|----------------|
-| "새 프로젝트 만들어줘" | PHASE 0 | — |
-| "contract 작성해줘" / "도메인 분석해줘" | PHASE 1 | 도메인 목록 식별 완료 |
-| "엔티티 추가해줘" / "엔티티 생성해줘" | PHASE 2 | 프로젝트 존재, dev 서버 실행 중, contract/**/*.contract.md 읽기, PHASE 1 완료 |
-| "테스트 작성해줘" / "API 구현해줘" | PHASE 4 | entity.json 존재, migration 완료, scaffolding 완료 |
-| "fixture 생성해줘" | PHASE 5 | 테스트 통과, cone.note 존재 확인 |
-| "프론트엔드 개발해줘" | PHASE 6 | API 구현 완료, contract/**/*.contract.md 확인 |
+| User instruction | Starting PHASE | Prerequisites to verify |
+|-----------------|----------------|------------------------|
+| "Create a new project" | PHASE 0 | — |
+| "Write contract" / "Analyze domain" | PHASE 1 | Domain list identified |
+| "Add entity" / "Create entity" | PHASE 2 | Project exists, dev server running, read contract/**/*.contract.md, PHASE 1 complete |
+| "Write tests" / "Implement API" | PHASE 4 | entity.json exists, migration complete, scaffolding complete |
+| "Generate fixtures" | PHASE 5 | Tests passing, cone.note exists |
+| "Develop frontend" | PHASE 6 | API implementation complete, contract/**/*.contract.md reviewed |
 
-**중간 진입 시 규칙:**
-1. `contract/**/*.contract.md` 및 `skills/project/architecture.md`가 있으면 반드시 먼저 읽는다
-2. 해당 PHASE의 전제 조건이 충족되었는지 확인한다
-3. 충족되지 않으면 사용자에게 알리고 필요한 단계부터 진행한다
-4. 해당 PHASE 내에서는 `workflow.md`의 넘버링된 Step을 순서대로 진행한다. 어떤 Step도 건너뛰지 않고, 자체 판단으로 병합하지 않는다
+**Mid-entry rules:**
+1. If `contract/**/*.contract.md` and `skills/project/architecture.md` exist, read them first.
+2. Verify prerequisites for the target PHASE.
+3. If prerequisites are not met, inform the user and begin from the required step.
+4. Within a PHASE, follow the numbered steps in `.claude/workflow/project_init.md` in order. Do not skip any step or merge steps on your own judgment.
 
 ---
 
-## 프로젝트 문서 체계
+## Project Document System
 
-### CRITICAL: 작업 시작 전 필수 확인
+### CRITICAL: Read these before starting any task
 
-**프로젝트 작업을 시작하기 전에 반드시 다음 문서를 읽으세요.**
+**Before starting any project task, always read the following documents.**
 
 ```
 contract/
 └── {domain}/
-    └── {domain}.contract.md  # PHASE 1: 도메인 규칙 + 결정 근거 (영구 문서, 코드 변경 시 함께 갱신)
+    └── {domain}.contract.md  # PHASE 1: domain rules + decision rationale (permanent; update alongside code changes)
 
 .claude/skills/project/
-└── architecture.md      # 엔티티 설계 + 시스템 아키텍처
+└── architecture.md      # entity design + system architecture
 
-tmp/claims/              # 진행 중 Claim YAML (완료 후 폐기)
+tmp/claims/              # in-progress Claim YAML (discard after completion)
 ```
 
-**Ground truth는 코드다.** `*.contract.md`는 코드 결정의 근거 기록이지 선행 정의서가 아니다. 코드와 `*.contract.md`가 충돌하면 코드를 우선한다.
+**Code is the ground truth.** `*.contract.md` records the rationale behind code decisions — it is not a spec that precedes the code. When code and `*.contract.md` conflict, the code takes precedence.
 
-### 도메인 `*.contract.md`
+### Domain `*.contract.md`
 
-도메인 규칙을 응집된 형태로 기술하고, 코드만으로는 파악하기 어려운 결정 근거를 함께 기록한다.
+Documents domain rules in a cohesive form and captures decision rationale that cannot be inferred from code alone.
 
 ```markdown
-# {도메인} 비즈니스 로직
+# {Domain} Business Logic
 
-## 규칙
-- 환불은 결제 후 7일 이내만 가능 [근거: PG사 정책]
-- 주문 상태 전환: 대기 → 확인 → 배송 → 완료
+## Rules
+- Refunds allowed only within 7 days of payment [Rationale: PG provider policy]
+- Order status transitions: pending → confirmed → shipped → completed
 
-## 워크플로우
+## Workflow
 1. ...
 ```
 
-**두 가지 개발 경로:**
-- **신규**: `*.contract.md` 작성 → Claim → AC(테스트명) → implement (TDD 방식)
-- **변경**: 코드 수정 → Claim 등록 → `*.contract.md` 확인/갱신 (변경 근거 기록)
+**Two development paths:**
+- **New**: write `*.contract.md` → Claim → AC (test name) → implement (TDD)
+- **Change**: modify code → register Claim → verify/update `*.contract.md` (record change rationale)
 
-**갱신 규칙:**
-- 코드 변경 시 영향받는 도메인 규칙을 확인하고 `*.contract.md`도 함께 업데이트
-- 변경 이유와 결정 근거를 함께 기록 — 이것이 `*.contract.md`를 살아있게 유지
+**Update rules:**
+- When code changes, check affected domain rules and update `*.contract.md` together
+- Record the reason and decision rationale — this keeps `*.contract.md` alive
 
 ### architecture.md
 
-**언제:** 엔티티를 설계하거나 시스템 아키텍처를 논의할 때
-**내용:** Entity 구조 및 관계 설계, 데이터베이스 스키마, 시스템 컴포넌트 구조
+**When:** designing entities or discussing system architecture
+**Content:** entity structure and relationships, database schema, system component structure
 
-### Compacting 후에도 안전
+### Safe after compacting
 
-문서가 파일로 영속화되어 있어서 대화가 압축(compacting)되어도 프로젝트 맥락이 유지된다.
+Documents are persisted as files, so project context is preserved even when the conversation is compacted.
 
 ---
 
-## Skills 목록
-
-| Skill | 파일 | 용도 |
-|-------|------|------|
-| **전체 워크플로우** | `workflow.md` | **엔티티 설계 → Frontend 개발 7단계 가이드** |
-| **CDD (AC+Claim 기반 개발)** | `cdd.md` | **`*.contract.md`(도메인 규칙), AC(테스트 이름), Claim(작업 지시서) 3종 체계** |
-| 프로젝트 생성 | `create-sonamu.md` | create-sonamu CLI 옵션 |
-| 프로젝트 초기화 | `project-init.md` | 프로젝트 생성 여부 확인, 대화 흐름 |
-| 프로젝트 설정 | `config.md` | .env, sonamu.config.ts 설정 |
-| 데이터베이스 | `database.md` | DB 설정, 포트 충돌 해결, 3-Tier 구조 |
-| Entity 검증 | `entity-validation-checklist.md` | Entity 생성 단계별 체크리스트 |
-| Entity 기본 | `entity-basic.md` | Entity JSON 구조, 필드 타입 |
-| Entity 관계 | `entity-relations.md` | BelongsToOne, HasMany, ManyToMany, FK 코드 패턴 |
-| Subset | `subset.md` | 조회 필드 범위 정의 |
-| Model | `model.md` | BaseModelClass, CRUD 패턴 |
-| API | `api.md` | @api 데코레이터 |
-| Puri | `puri.md` | SQL 쿼리 빌더 |
-| i18n | `i18n.md` | 다국어 지원, SD 함수 |
-| Upsert | `upsert.md` | 관계 데이터 저장 |
-| Testing | `testing.md` | Vitest 테스트 (test/testAs), Fixture 생성 팁 |
-| **DevRunner** | `testing-devrunner.md` | **sonamu test 실행, HMR 연동, 병렬 테스트, sonamu.config.ts 테스트 설정** |
-| **Naite** | `naite.md` | **Naite.t()/get() 추적 시스템, 체이닝 필터, trace CLI 출력** |
-| **Cone** | `cone.md` | **Cone 메타데이터 생성 및 관리 (LLM/템플릿)** |
-| **Fixture CLI** | `fixture-cli.md` | **fixture gen/fetch/explore 명령어, 3-Tier DB 활용** |
-| Migration | `migration.md` | DB 스키마 마이그레이션, PK 타입 변경 |
-| Auth | `auth.md` | better-auth 인증 시스템 (엔티티 자동 생성, Guards, Context) |
-| Auth Migration | `auth-migration.md` | better-auth 등 외부 인증 통합 시 User.id 타입 변경 |
-| **Auth Plugins** | `auth-plugins.md` | **better-auth 플러그인 래퍼 (admin, organization, 2fa, passkey 등 10종), snake_case 매핑** |
-| **벡터 검색** | `vector.md` | **pgvector 임베딩 (Voyage AI/OpenAI), 청킹, 하이브리드 검색** |
-| Puri 쿼리 빌더 | `puri.md` | SELECT, WHERE, JOIN, FTS, pg_trgm fuzzy search, pgvector |
-| **AI Agents** | `ai-agents.md` | **BaseAgentClass, @tools 데코레이터, ToolLoopAgent, AsyncLocalStorage 상태** |
-| **Tasks** | `tasks.md` | **백그라운드 워크플로우, cron 스케줄링, durable step, 재시도 정책** |
-| **스킬 기여** | `skill-contribution.md` | **트러블슈팅 해결 → 스킬 반영 워크플로우 (매칭, 판정, 포맷, 승인)** |
-| **Framework 변경 판단** | `framework-change.md` | **프레임워크 수정 vs. 프로젝트 우회 판단 기준. @upload 파라미터 패턴** |
+## Skills List
+
+| Skill | File | Purpose |
+|-------|------|---------|
+| **CDD (AC+Claim-based development)** | `cdd.md` | **`*.contract.md` (domain rules), AC (test names), Claim (work instructions) — 3-artifact system** |
+| Project creation | `create-sonamu.md` | create-sonamu CLI options |
+| Project initialization | `project-init.md` | Project creation flow and conversation guide |
+| Project configuration | `config.md` | .env, sonamu.config.ts settings |
+| Database | `database.md` | DB setup, port conflict resolution, 3-Tier structure |
+| Entity validation | `entity-validation-checklist.md` | Step-by-step entity creation checklist |
+| Entity basics | `entity-basic.md` | Entity JSON structure, field types |
+| Entity relations | `entity-relations.md` | BelongsToOne, HasMany, ManyToMany, FK code patterns |
+| Subset | `subset.md` | Response field scope definition |
+| Model | `model.md` | BaseModelClass, CRUD patterns |
+| API | `api.md` | @api decorator |
+| Puri | `puri.md` | SQL query builder |
+| i18n | `i18n.md` | Internationalization, SD functions |
+| Upsert | `upsert.md` | Batch saving of relation data |
+| Testing | `testing.md` | Vitest tests (test/testAs), fixture generation tips |
+| **DevRunner** | `testing-devrunner.md` | **sonamu test execution, HMR integration, parallel tests, sonamu.config.ts test settings** |
+| **Naite** | `naite.md` | **Naite.t()/get() tracing system, chaining filters, trace CLI output** |
+| **Cone** | `cone.md` | **Cone metadata generation and management (LLM/template)** |
+| **Fixture CLI** | `fixture-cli.md` | **fixture gen/fetch/explore commands, 3-Tier DB usage** |
+| Migration | `migration.md` | DB schema migration, PK type changes |
+| Auth | `auth.md` | better-auth system (auto entity generation, Guards, Context) |
+| Auth Migration | `auth-migration.md` | User.id type changes for external auth (e.g., better-auth) |
+| **Auth Plugins** | `auth-plugins.md` | **better-auth plugin wrappers (admin, organization, 2fa, passkey, etc. — 10 types), snake_case mapping** |
+| **Vector search** | `vector.md` | **pgvector embeddings (Voyage AI/OpenAI), chunking, hybrid search** |
+| Puri query builder | `puri.md` | SELECT, WHERE, JOIN, FTS, pg_trgm fuzzy search, pgvector |
+| **AI Agents** | `ai-agents.md` | **BaseAgentClass, @tools decorator, ToolLoopAgent, AsyncLocalStorage state** |
+| **Tasks** | `tasks.md` | **Background workflows, cron scheduling, durable steps, retry policies** |
+| **Skill contribution** | `skill-contribution.md` | **Troubleshooting → skill contribution workflow (matching, decision, format, approval)** |
+| **Framework change** | `framework-change.md` | **Criteria for framework fix vs. project workaround. @upload parameter pattern** |
 | Frontend | `frontend.md` | Service, TanStack Query |
-| Scaffolding | `scaffolding.md` | UI Scaffolding 오류 해결 |
-
-## 작업별 Skill 선택
-
-**CRITICAL: 새로운 시스템이나 기능을 처음부터 개발할 때는 `workflow.md`부터 시작하세요!**
-
-| 작업 | 참고 Skill |
-|------|-----------|
-| **처음부터 전체 시스템 개발** | **workflow.md (7단계 마스터 가이드)** |
-| **도메인 Logic 문서화 / AC+Claim 기반 개발** | **cdd.md** |
-| 프로젝트 생성 | create-sonamu, project-init |
-| 프로젝트 설정 | config |
-| Sonamu 로컬 개발 설정 | config |
-| DB 설정/포트 충돌 | database, config |
-| **3-Tier DB 구조 이해** | **database, fixture-cli** |
-| **Cone 메타데이터 생성/관리** | **cone** |
-| Entity/속성 정의 | entity-basic |
-| 관계 설정 | entity-relations |
-| **BelongsToOne FK 코드 사용** | **entity-relations** |
-| API 응답 필드 구성 | subset |
-| 데이터 조회/저장 로직 | model, puri |
-| API 엔드포인트 | api |
-| 관계 데이터 배치 저장 | upsert |
-| 테스트 작성 | testing |
-| **테스트 실행 (sonamu test)** | **testing-devrunner** |
-| **Naite 추적/디버깅** | **naite** |
-| **Fixture 데이터 생성/관리** | **fixture-cli** |
-| **테스트 데이터 생성 팁** | **testing (Fixture 데이터 생성 팁), fixture-cli (실전 팁)** |
-| DB 스키마 변경 | migration |
-| **인증 설정 (auth generate, Guards, Context)** | **auth** |
-| PK 타입 변경 (better-auth 등) | auth-migration |
-| **인증 플러그인 추가** | **auth-plugins** |
-| 프론트엔드 개발 | frontend |
-| 다국어/번역 | i18n |
-| Scaffolding 오류 | scaffolding |
-| **벡터 검색/임베딩** | **vector** |
+| Scaffolding | `scaffolding.md` | Resolving UI scaffolding errors |
+
+## Task-to-Skill Reference
+
+**CRITICAL: When building a new system from scratch, start with `.claude/workflow/project_init.md`!**
+
+| Task | Reference Skill |
+|------|----------------|
+| **Build an entire system from scratch** | **`.claude/workflow/project_init.md` (7-phase master guide)** |
+| **Domain logic documentation / AC+Claim-based development** | **cdd.md** |
+| Project creation | create-sonamu, project-init |
+| Project configuration | config |
+| Sonamu local dev setup | config |
+| DB setup / port conflict | database, config |
+| **3-Tier DB structure** | **database, fixture-cli** |
+| **Cone metadata generation/management** | **cone** |
+| Entity / field definition | entity-basic |
+| Relationship setup | entity-relations |
+| **BelongsToOne FK code usage** | **entity-relations** |
+| API response field composition | subset |
+| Data query / save logic | model, puri |
+| API endpoints | api |
+| Batch saving of relation data | upsert |
+| Writing tests | testing |
+| **Running tests (sonamu test)** | **testing-devrunner** |
+| **Naite tracing / debugging** | **naite** |
+| **Fixture data generation/management** | **fixture-cli** |
+| **Test data generation tips** | **testing (Fixture data generation tips), fixture-cli (practical tips)** |
+| DB schema changes | migration |
+| **Auth setup (auth generate, Guards, Context)** | **auth** |
+| PK type changes (better-auth, etc.) | auth-migration |
+| **Adding auth plugins** | **auth-plugins** |
+| Frontend development | frontend |
+| Internationalization / translation | i18n |
+| Scaffolding errors | scaffolding |
+| **Vector search / embeddings** | **vector** |
 | **pg_trgm Fuzzy Search** | **puri, entity-basic** |
-| **AI Agent 개발** | **ai-agents** |
-| **백그라운드 작업/스케줄링** | **tasks** |
-| **트러블슈팅 → 스킬 반영** | **skill-contribution** |
-| **프레임워크 버그/제약 발견 시 대응** | **framework-change** |
+| **AI Agent development** | **ai-agents** |
+| **Background jobs / scheduling** | **tasks** |
+| **Troubleshooting → skill contribution** | **skill-contribution** |
+| **Framework bug / constraint response** | **framework-change** |
 
-## 명령어 실행 경로
+## Command Execution Path
 
-모든 `pnpm` 명령어는 **`packages/api`** 디렉토리에서 실행합니다.
+All `pnpm` commands are run from the **`packages/api`** directory.
 
 ```bash
 cd packages/api
@@ -199,9 +198,9 @@ pnpm dev
 pnpm sonamu migrate run
 ```
 
-## 소스코드 참조
+## Source Code References
 
-- Sonamu 프레임워크: `sonamu/modules/sonamu/`
-- 예제 프로젝트: `sonamu/examples/miomock/`
-- 공식 문서: `sonamu/modules/docs/`
+- Sonamu framework: `sonamu/modules/sonamu/`
+- Example project: `sonamu/examples/miomock/`
+- Official docs: `sonamu/modules/docs/`
 - create-sonamu: `sonamu/modules/create-sonamu/`

package/src/skills/sonamu/ai-agents.md

@@ -1,28 +1,28 @@
 ---
 name: sonamu-ai-agents
-description: AI Agent 프레임워크. BaseAgentClass 상속, @tools 데코레이터로 도구 정의, ToolLoopAgent 통합, AsyncLocalStorage 기반 상태 관리. Use when building AI agents with tool-use capabilities.
+description: AI Agent framework. Extend BaseAgentClass, define tools with @tools decorator, ToolLoopAgent integration, AsyncLocalStorage-based state management. Use when building AI agents with tool-use capabilities.
 ---
 
-# AI Agent 가이드
+# AI Agent Guide
 
-Sonamu는 Vercel AI SDK의 `ToolLoopAgent`를 래핑하여 클래스 기반 AI Agent를 구성할 수 있는 프레임워크를 제공합니다.
+Sonamu provides a framework that wraps Vercel AI SDK's `ToolLoopAgent` to build class-based AI Agents.
 
-**소스코드:** `modules/sonamu/src/ai/agents/`
+**Source code:** `modules/sonamu/src/ai/agents/`
 
 ---
 
-## 구조
+## Structure
 
-| 파일 | 역할 |
+| File | Role |
 |------|------|
-| `agent.ts` | `BaseAgentClass`, `tools` 데코레이터 |
-| `types.ts` | `AgentConfig`, `ToolDecoratorOptions`, `RegisteredToolDefinition` 등 |
+| `agent.ts` | `BaseAgentClass`, `tools` decorator |
+| `types.ts` | `AgentConfig`, `ToolDecoratorOptions`, `RegisteredToolDefinition`, etc. |
 
 ---
 
 ## BaseAgentClass
 
-Agent의 베이스 클래스. 상속하여 커스텀 Agent를 만듭니다.
+The base class for Agents. Extend it to create a custom Agent.
 
 ```typescript
 import { BaseAgentClass, tools } from "sonamu/ai/agents";
@@ -30,11 +30,11 @@ import { z } from "zod/v4";
 
 class MyAgentClass extends BaseAgentClass<{ count: number }> {
   constructor() {
-    super("MyAgent");  // agentName (로거 카테고리로 사용)
+    super("MyAgent");  // agentName (used as logger category)
   }
 
   @tools({
-    description: "두 수를 더합니다",
+    description: "Adds two numbers",
     schema: {
       input: z.object({ a: z.number(), b: z.number() }),
       output: z.object({ result: z.number() }),
@@ -48,54 +48,54 @@ class MyAgentClass extends BaseAgentClass<{ count: number }> {
 export const MyAgent = new MyAgentClass();
 ```
 
-### 주요 기능
+### Key Features
 
-| 기능 | 설명 |
+| Feature | Description |
 |------|------|
-| `this.logger` | LogTape 로거 (agent 카테고리) |
-| `this.store` | AsyncLocalStorage 기반 상태 접근 |
-| `this.tools` | 등록된 도구셋 (ToolSet) |
-| `this.use()` | Agent 실행 (ALS 컨텍스트 + ToolLoopAgent) |
+| `this.logger` | LogTape logger (agent category) |
+| `this.store` | AsyncLocalStorage-based state access |
+| `this.tools` | Registered toolset (ToolSet) |
+| `this.use()` | Run the Agent (ALS context + ToolLoopAgent) |
 
 ---
 
-## @tools 데코레이터
+## @tools Decorator
 
-메서드를 AI 도구로 등록합니다. Zod v4 스키마로 입출력을 정의합니다.
+Registers a method as an AI tool. Define input/output using Zod v4 schema.
 
 ```typescript
 @tools({
-  name?: string,           // 도구 이름 (기본: "className.methodName" 형태)
-  description?: string,    // LLM에게 보여줄 설명
+  name?: string,           // Tool name (default: "className.methodName" format)
+  description?: string,    // Description shown to the LLM
   schema: {
-    input: z.ZodType,      // 입력 스키마 (필수)
-    output?: z.ZodType,    // 출력 스키마 (선택)
+    input: z.ZodType,      // Input schema (required)
+    output?: z.ZodType,    // Output schema (optional)
   },
-  needsApproval?: boolean | function,  // 사용자 승인 필요 여부
-  toModelOutput?: function,            // 모델에게 반환할 출력 변환
-  providerOptions?: ProviderOptions,   // 프로바이더별 옵션
+  needsApproval?: boolean | function,  // Whether user approval is required
+  toModelOutput?: function,            // Transform output returned to the model
+  providerOptions?: ProviderOptions,   // Provider-specific options
 })
 ```
 
-### 이름 자동 생성 규칙
+### Automatic Name Generation Rule
 
-`name`을 생략하면 `{ModelName(camelCase)}.{methodName(camelCase)}`로 자동 생성됩니다.
+If `name` is omitted, it is auto-generated as `{ModelName(camelCase)}.{methodName(camelCase)}`.
 
 ```typescript
 class SearchAgentClass extends BaseAgentClass<...> {
   @tools({ ... })
   async findDocuments(input: ...) { ... }
-  // → 도구 이름: "searchAgent.findDocuments"
+  // → Tool name: "searchAgent.findDocuments"
 }
 ```
 
-클래스명에서 `Class`, `Model`, `Frame` 접미사는 자동 제거됩니다.
+The suffixes `Class`, `Model`, and `Frame` are automatically stripped from the class name.
 
 ---
 
-## Agent 실행 (use)
+## Running an Agent (use)
 
-`use()` 메서드로 Agent를 실행합니다. AsyncLocalStorage 컨텍스트 내에서 ToolLoopAgent가 동작합니다.
+Run the Agent with the `use()` method. ToolLoopAgent operates within the AsyncLocalStorage context.
 
 ```typescript
 import { anthropic } from "@ai-sdk/anthropic";
@@ -104,64 +104,64 @@ const result = await MyAgent.use(
   // AgentConfig
   {
     model: anthropic("claude-sonnet-4-5-20250514"),
-    instructions: "당신은 수학 도우미입니다.",
+    instructions: "You are a math assistant.",
     toolChoice: "auto",     // "auto" | "none" | "required"
     maxOutputTokens: 1000,
     temperature: 0.7,
   },
-  // 초기 상태 (AsyncLocalStorage에 저장)
+  // Initial state (stored in AsyncLocalStorage)
   { count: 0 },
-  // 콜백 (Agent 인스턴스 받음)
+  // Callback (receives Agent instance)
   async (agent) => {
-    // agent는 ToolLoopAgent 인스턴스
-    // Vercel AI SDK의 agent API 사용
+    // agent is a ToolLoopAgent instance
+    // Use Vercel AI SDK's agent API
     return agent;
   },
 );
 ```
 
-### AgentConfig 옵션
+### AgentConfig Options
 
-| 옵션 | 타입 | 설명 |
+| Option | Type | Description |
 |------|------|------|
-| `model` | `LanguageModel` | AI SDK 모델 (필수) |
-| `instructions` | `string` | 시스템 프롬프트 |
-| `toolChoice` | `"auto" \| "none" \| "required"` | 도구 선택 방식 |
-| `stopWhen` | `StopCondition` | 중단 조건 |
-| `activeTools` | `string[]` | 활성화할 도구 이름 목록 |
-| `maxOutputTokens` | `number` | 최대 출력 토큰 |
-| `temperature` | `number` | 온도 |
-| `topP` / `topK` | `number` | 샘플링 파라미터 |
-| `presencePenalty` / `frequencyPenalty` | `number` | 페널티 |
-| `seed` | `number` | 재현성용 시드 |
-| `stopSequences` | `string[]` | 생성 중단 시퀀스 |
-| `providerOptions` | `ProviderOptions` | 프로바이더별 추가 옵션 |
-| `headers` | `Record<string, string>` | 커스텀 HTTP 헤더 |
+| `model` | `LanguageModel` | AI SDK model (required) |
+| `instructions` | `string` | System prompt |
+| `toolChoice` | `"auto" \| "none" \| "required"` | Tool selection strategy |
+| `stopWhen` | `StopCondition` | Stop condition |
+| `activeTools` | `string[]` | List of tool names to activate |
+| `maxOutputTokens` | `number` | Maximum output tokens |
+| `temperature` | `number` | Temperature |
+| `topP` / `topK` | `number` | Sampling parameters |
+| `presencePenalty` / `frequencyPenalty` | `number` | Penalties |
+| `seed` | `number` | Seed for reproducibility |
+| `stopSequences` | `string[]` | Generation stop sequences |
+| `providerOptions` | `ProviderOptions` | Additional provider-specific options |
+| `headers` | `Record<string, string>` | Custom HTTP headers |
 
 ---
 
-## 상태 관리 (AsyncLocalStorage)
+## State Management (AsyncLocalStorage)
 
-`BaseAgentClass`는 제네릭 `TStore`로 상태 타입을 정의합니다. `use()` 호출 시 초기 상태를 전달하면, 도구 실행 중 `this.store`로 접근할 수 있습니다.
+`BaseAgentClass` defines the state type with the generic `TStore`. When you pass the initial state to `use()`, it can be accessed via `this.store` during tool execution.
 
 ```typescript
 class StatefulAgentClass extends BaseAgentClass<{ processedItems: string[] }> {
   @tools({ ... })
   async processItem(input: { item: string }) {
-    // 상태 접근
+    // Access state
     this.store?.processedItems.push(input.item);
     return { ok: true };
   }
 }
 ```
 
-**주의:** `this.store`는 `use()` 컨텍스트 밖에서는 `undefined`입니다.
+**Note:** `this.store` is `undefined` outside of a `use()` context.
 
 ---
 
-## 도구 격리
+## Tool Isolation
 
-각 Agent 클래스의 도구는 클래스별로 격리됩니다. `toolSet` getter가 `def.from === this.constructor.name`으로 필터링합니다.
+Tools for each Agent class are isolated per class. The `toolSet` getter filters by `def.from === this.constructor.name`.
 
 ```typescript
 class AgentA extends BaseAgentClass<void> {
@@ -171,34 +171,34 @@ class AgentB extends BaseAgentClass<void> {
   @tools({ ... }) async toolY() { ... }
 }
 
-// AgentA.tools → { toolX만 포함 }
-// AgentB.tools → { toolY만 포함 }
+// AgentA.tools → { contains only toolX }
+// AgentB.tools → { contains only toolY }
 ```
 
 ---
 
-## 로깅
+## Logging
 
-`this.logger`는 LogTape를 사용합니다. 카테고리는 `convertDomainToCategory(agentName, "agent")`로 생성됩니다.
+`this.logger` uses LogTape. The category is generated with `convertDomainToCategory(agentName, "agent")`.
 
-도구 실행 시 자동으로 debug 로그가 기록됩니다:
+Debug logs are automatically recorded on tool execution:
 ```
 tools: {model}.{method} with args: {args}
 ```
 
 ---
 
-## 관련 패키지
+## Related Packages
 
 - `ai`: Vercel AI SDK (`ToolLoopAgent`, `Agent`, `ToolSet`)
 - `@ai-sdk/provider-utils`: `tool()`, `Tool`, `ToolExecutionOptions`
-- `zod/v4`: 스키마 정의
-- `@logtape/logtape`: 로깅
+- `zod/v4`: Schema definitions
+- `@logtape/logtape`: Logging
 
 ---
 
-## 참고
+## References
 
-- **소스코드**: `modules/sonamu/src/ai/agents/`
+- **Source code**: `modules/sonamu/src/ai/agents/`
 - **Vercel AI SDK**: https://sdk.vercel.ai/docs
-- **벡터 검색**: `vector.md`
+- **Vector search**: `vector.md`