docs: synchronize runtime inventory and localized API docs

Generated runtime inventory, synchronized all maintained README variants, and added CI checks for documentation drift. Fixes #24.

Author: EvanProgramming

.github/workflows/ci.yml

@@ -48,6 +48,9 @@ jobs:
       run: |
         python -c "from providers import *; print('All providers imported OK')"
 
+    - name: Documentation and runtime inventory check
+      run: make docs-check
+
   docker-persistence:
     runs-on: ubuntu-latest
     timeout-minutes: 10

Makefile

@@ -1,4 +1,4 @@
-.PHONY: install run clean lint test check benchmark docker-smoke git-status git-diff git-log web
+.PHONY: install run clean lint test check docs-check benchmark docker-smoke git-status git-diff git-log web
 
 # Prefer the known-stable Python 3.12, but use the active supported Python
 # 3.13 on clean runners that do not provide 3.12. Python 3.14 remains
@@ -49,7 +49,7 @@ clean:
 
 # Syntax check
 lint:
-	$(VENV_PYTHON) -m compileall -q main.py main_debug.py server.py tools.py memory.py event_store.py task_engine.py learning_engine.py learning_benchmark.py migration.py scheduler.py skill_registry.py browser_manager.py instruction_loader.py agent_config.py subagents.py capability_tokens.py tool_registry.py dynamic_tools.py plugin_runtime.py
+	$(VENV_PYTHON) -m compileall -q main.py main_debug.py server.py tools.py memory.py event_store.py task_engine.py learning_engine.py learning_benchmark.py migration.py scheduler.py skill_registry.py browser_manager.py instruction_loader.py agent_config.py subagents.py capability_tokens.py tool_registry.py dynamic_tools.py plugin_runtime.py scripts/generate_tool_inventory.py scripts/check_docs.py
 	@echo "Python syntax OK."
 	@echo "All files pass syntax check."
 
@@ -68,6 +68,10 @@ benchmark:
 		--evolved-runner "$(VENV_PYTHON) benchmarks/evolved_runner.py" \
 		--timeout "$${BENCHMARK_TIMEOUT:-60}"
 
+docs-check:
+	$(VENV_PYTHON) scripts/generate_tool_inventory.py --check
+	$(VENV_PYTHON) scripts/check_docs.py
+
 docker-smoke:
 	@command -v docker >/dev/null 2>&1 || { echo "Error: Docker is required for the container smoke test."; exit 1; }
 	docker build -t openkyrozen-smoke .
@@ -76,7 +80,7 @@ docker-smoke:
 # Quick verification
 check:
 	@echo "Checking Python syntax..."
-	@$(VENV_PYTHON) -m py_compile main.py main_debug.py server.py tools.py memory.py event_store.py task_engine.py learning_engine.py learning_benchmark.py migration.py scheduler.py skill_registry.py browser_manager.py instruction_loader.py agent_config.py subagents.py capability_tokens.py tool_registry.py dynamic_tools.py plugin_runtime.py
+	@$(VENV_PYTHON) -m py_compile main.py main_debug.py server.py tools.py memory.py event_store.py task_engine.py learning_engine.py learning_benchmark.py migration.py scheduler.py skill_registry.py browser_manager.py instruction_loader.py agent_config.py subagents.py capability_tokens.py tool_registry.py dynamic_tools.py plugin_runtime.py scripts/generate_tool_inventory.py scripts/check_docs.py
 	@echo "  Python modules: OK"
 	@echo "Checking git tools..."
 	@$(VENV_PYTHON) -c "from tools import AVAILABLE_TOOLS; git = [k for k in AVAILABLE_TOOLS if k.startswith('git_')]; print(f'  {len(git)} git tools, {len(AVAILABLE_TOOLS)} total tools')"

README.ja.md

@@ -37,7 +37,8 @@
 - [🛠 도구 레퍼런스](#-도구-레퍼런스)
   - [파일 및 시스템](#파일-및-시스템)
   - [웹](#웹)
-  - [Git (15개 도구)](#git-15개-도구)
+  - [브라우저](#브라우저-5개-도구)
+  - [Git (14개 도구)](#git-14개-도구)
   - [메모리](#메모리)
 - [🧠 전용 워크플로우](#-전용-워크플로우)
   - [버그 수정](#버그-수정6단계-프로토콜)
@@ -59,7 +60,7 @@
 
 OpenKyrozen은 터미널에서 실행되는 **자기 학습형 AI 에이전트**입니다. 일반적인 챗봇과 달리 다음과 같은 기능을 제공합니다:
 
-- **내장 26개 도구** — 파일 읽기/쓰기, 셸 명령 실행, 웹 검색, Git 저장소 관리
+- **31개 런타임 도구** — 파일, 셸, 웹, Git, 브라우저 기본 작업 29개와 SQLite 메모리 작업 2개
 - **지속적 학습** — 20개 기능을 제한된 dispatcher로 실행하고 사실 추출, 스킬 발명, 전략 최적화를 기록
 - **다양한 LLM 지원** — DeepSeek, OpenAI, Claude, Gemini, 또는 로컬 Ollama 모델
 - **크로스 플랫폼** — macOS, Linux, Windows (터미널 기능 자동 감지 포함)
@@ -192,7 +193,7 @@ docker run -p 8000:8000 \
          │  응답 + 도구 호출
          ▼
 ┌─────────────────┐
-│   도구 실행기   │──► 26개 내장 도구 (파일 I/O, 셸, Git, 웹, 메모리)
+│   도구 실행기   │──► 31개 런타임 도구 (파일 I/O, 셸, Git, 웹, 메모리, 브라우저)
 └────────┬────────┘
          │  도구 결과를 LLM에 피드백
          │  (턴당 최대 50회 도구 호출)
@@ -244,13 +245,13 @@ export ANTHROPIC_API_KEY=sk-ant-...
 python main.py
 ```
 
-주 제공자가 실패하면 Kyrozen은 자동으로 폴백 체인(예: DeepSeek → OpenAI → Claude)을 통해 전환합니다. 속도 제한 오류(HTTP 429)는 지터가 포함된 지수 백오프를 트리거합니다.
+주 제공자가 실패하면 Kyrozen은 자동으로 폴백 체인(예: DeepSeek → OpenAI → Claude)을 통해 전환합니다. 속도 제한 오류(HTTP 429)는 지터가 포함된 지수 백오프를 트리거합니다. Ollama는 키가 필요 없는 로컬 제공자입니다. `KYROZEN_PROVIDER=ollama`를 설정하고 필요하면 `KYROZEN_BASE_URL`로 OpenAI-compatible endpoint를 지정하세요. Web headless 시작은 stdin을 읽지 않습니다. 원격 제공자 키가 없으면 명확한 degraded 상태가 되며 대화형 CLI만 키를 요청합니다.
 
 ---
 
 ## 🛠 도구 레퍼런스
 
-모든 26개 도구는 JSON 액션 블록에서 일반 문자열 `args` 필드를 허용합니다:
+모든 31개 런타임 도구는 JSON 액션 블록에서 일반 문자열 `args` 필드를 허용합니다. 도구 이름, capability 라벨, MCP 입력 schema 및 실제 HTTP 경로는[생성된 런타임 인벤토리](docs/tool-inventory.md)를 기준으로 합니다:
 
 ```json
 {"action": "read_file", "args": "README.md"}
@@ -268,15 +269,30 @@ python main.py
 | `list_tree` | 재귀적 디렉토리 트리 | `"src/"` |
 | `find_files` | Glob 기반 파일 검색 | `"*.py|."` |
 | `run_cmd` | 셸 명령 실행 | `"python --version"` |
+| `execute_terminal_command` | `run_cmd`의 별칭 | `"python --version"` |
 
 ### 웹
 
 | 도구 | 설명 | 예시 |
 |------|------|------|
 | `search_web` | 인터넷 검색 (Google → DDG → Wikipedia) | `"최신 Python 릴리스"` |
 | `read_webpage` | URL 텍스트 콘텐츠 가져오기 | `"https://example.com"` |
+| `analyze_remote_repo` | 원격 저장소를 클론하고 요약 | `"https://github.com/org/repo"` |
 
-### Git (15개 도구)
+### 브라우저 (5개 도구)
+
+브라우저 도구는 격리된 profile을 사용합니다. 사용 전에 선택적 browser
+extra를 설치하세요.
+
+| 도구 | 설명 | 예시 |
+|------|------|------|
+| `browser_open` | URL 열기 | `"https://example.com"` |
+| `browser_snapshot` | 현재 페이지 텍스트 읽기 | `"session-id"` |
+| `browser_click` | CSS selector 클릭 | `"session-id|button.submit"` |
+| `browser_type` | CSS selector 입력 | `"session-id|input[name=q]|query"` |
+| `browser_close` | 격리된 브라우저 세션 닫기 | `"session-id"` |
+
+### Git (14개 도구)
 
 | 도구 | 기능 |
 |------|------|
@@ -293,7 +309,6 @@ python main.py
 | `git_show` | `--stat`으로 커밋 상세 정보 확인 |
 | `git_remote` | 원격 저장소 나열 / 추가 / 삭제 |
 | `git_clone` | 저장소 클론 |
-| `analyze_remote_repo` | 클론 + 모든 파일 읽기 → 구조화된 요약 |
 
 ### 메모리
 
@@ -373,7 +388,9 @@ CLI는 유휴 상태에서 30초마다 최대 4개 기능을 라운드 로빈으
 
 ### 메모리 저장소
 
-장기 메모리는 **ChromaDB**(벡터 데이터베이스, `chroma_memory/`에 저장)를 사용합니다. ChromaDB를 사용할 수 없는 경우 인메모리 저장소로 폴백합니다. 메모리는 의미 기반 검색이 가능하며 — 에이전트는 몇 주 전의 관련 사실을 기억할 수 있습니다.
+OpenKyrozen v2의 장기 메모리는 **SQLite를 사실의 원본**(`~/.kyrozen/v2/openkyrozen.sqlite3`)으로 사용하고, ChromaDB는 다시 만들 수 있는 파생 의미 인덱스로 사용합니다. workspace와 session은 분리되며 ChromaDB를 사용할 수 없어도 SQLite 키워드 검색으로 영속성이 유지됩니다. Web/MCP 단일 사용자 배포에서는 `KYROZEN_SERVER_TOKEN` 하나가 안정적인 actor 하나를 나타내고, 요청의 `speaker`만으로 private 데이터의 소유자를 바꿀 수 없습니다.
+
+작업은 재시작 후에도 저장되며 상태는 `pending`, `running`, `succeeded`, `failed`, `blocked`, `cancelled`입니다(이전 `done`은 읽기 호환). `TaskDone`만으로는 성공하지 않고 도구 결과, 테스트, 파일 확인 또는 명시적 확인 증거가 필요합니다. 안전한 API 작업은 worker가 재개하며 failed/blocked 작업은 `/api/v2/tasks/{task_id}/resume`으로 명시적으로 재개합니다.
 
 ---
 
@@ -390,19 +407,49 @@ python server.py --port 8000
 | 메서드 | 엔드포인트 | 설명 |
 |--------|----------|------|
 | `GET` | `/` | 다크 테마 채팅 Web UI |
-| `POST` | `/api/chat` | 메시지 전송, JSON 응답 받기 |
-| `POST` | `/api/chat/stream` | SSE 스트리밍 채팅 |
+| `POST` | `/api/chat` | 메시지를 보내고 메모리 receipt가 포함된 JSON 응답 받기 |
+| `POST` | `/api/chat/stream` | SSE 스트리밍; `[DONE]` 이후에만 완료 webhook 전송 |
 | `GET` | `/api/memory?q=키워드` | 저장된 메모리 검색 |
-| `GET` | `/api/v2/learning/features` | 20개 기능 레지스트리와 최신 실행 상태 |
-| `GET` | `/api/cost` | 토큰 사용량 및 비용 요약 |
-| `GET` | `/api/health` | 제공자 상태 + 메모리 수 |
-| `GET` | `/api/voice/speak?text=...` | 시스템 TTS로 텍스트 음성 변환 |
+| `GET` | `/api/v2/memory?q=키워드&speaker=...&audience=...&channel=...` | provenance 및 참여자 scope가 포함된 구조화 메모리 |
+| `GET/POST` | `/api/v2/tasks` | 영속 작업 조회 및 생성 |
+| `POST` | `/api/v2/tasks/{task_id}/resume` | failed/blocked 작업을 명시적으로 재개 |
+| `GET` | `/api/v2/learning` | 학습 제안 상태 조회 |
+| `GET` | `/api/v2/learning/metrics?profile=...` | 완료, 수정, 오류, 도구, token, 지연 지표 조회 |
+| `GET` | `/api/v2/learning/features` | 권위 있는 20개 기능 레지스트리와 최신 실행 상태 |
+| `GET` | `/api/v2/learning/{proposal_id}/evidence` | proof card, 적용성, replay 및 결과 receipt 조회 |
+| `POST` | `/api/v2/learning/{proposal_id}/replay` | 후보/선행 artifact의 paired replay 결과 기록 |
+| `POST` | `/api/v2/learning/{proposal_id}/omission` | artifact 유/무 paired 결과 기록 |
+| `POST` | `/api/v2/learning/{proposal_id}/retire` | 비회귀 omission 증거로 artifact retire |
+| `POST` | `/api/v2/learning/{proposal_id}/restore` | retired artifact를 canary로 복구 |
+| `GET` | `/api/v2/learning/{proposal_id}/capsule` | redacted·harness 독립 경험 capsule 내보내기 |
+| `POST` | `/api/v2/learning/capsules` | capsule을 비활성 후보로 가져오기 |
+| `GET` | `/api/v2/learning/constitution` | 변경 불가능한 사용자 소유 learning policy 조회 |
+| `POST` | `/api/v2/learning/{proposal_id}/rollback` | 활성화된 학습 제안 rollback |
+| `GET/POST` | `/api/v2/memory/claims` | 유형·귀속·scope가 있는 memory claim 조회/생성 |
+| `GET/DELETE` | `/api/v2/memory/claims/{claim_id}` | claim 설명 또는 단독 의존 항목과 함께 삭제 |
+| `GET` | `/api/v2/events` | runtime, session, task, learning 감사 이벤트 조회 |
+| `GET/POST` | `/api/v2/schedules` | 영속 interval/one-shot Gateway job |
+| `POST` | `/api/v2/schedules/{job_id}/disable` | 예약 job 비활성화 |
+| `GET` | `/api/v2/skills` | candidate/active skill 조회 |
+| `POST` | `/api/v2/skills/install` | 로컬 `SKILL.md` package 검증 및 설치 |
+| `POST` | `/api/v2/skills/{skill_id}/activate` | 검증된 skill 활성화 |
+| `POST` | `/api/v2/skills/{skill_id}/rollback` | skill rollback |
+| `GET` | `/api/v2/sessions` | 영속 session 조회 |
+| `GET` | `/api/v2/sessions/{session_id}` | session context 복구/읽기 |
+| `GET` | `/api/v2/agents` | 전문 sub-agent profile 조회 |
+| `POST` | `/api/v2/agents/run` | 격리된 memory와 capability로 sub-agent 실행 |
+| `GET` | `/api/cost` | token 사용량 및 비용 요약 |
+| `GET` | `/api/health` | provider 상태 + memory 수 |
+| `GET` | `/api/voice/speak?text=...` | 시스템 TTS 텍스트 음성 변환 |
 | `POST` | `/api/voice/transcribe` | 음성-텍스트 변환 (패스스루) |
 | `POST` | `/api/webhooks/register` | Webhook URL 등록 |
-| `GET` | `/api/webhooks` | 등록된 Webhook 나열 |
+| `GET` | `/api/webhooks` | 등록된 Webhook 조회 |
 | `POST` | `/api/webhooks/test` | 테스트 Webhook 실행 |
 | `POST` | `/mcp` | 모델 컨텍스트 프로토콜 (JSON-RPC 2.0) |
 
+모든 JSON Action은 일반 문자열 `args`를 사용합니다. MCP의 `tools/list`와
+`server/discover`는 허용된 각 도구의 `inputSchema`를 반환하고 object 인자를 같은 문자열 계약으로 명시적으로 변환합니다. 알 수 없거나 권한이 없는 도구는 JSON-RPC protocol error이며, 실행된 도구의 실패는 `result.isError: true`입니다. 전체 정식 목록은 [docs/tool-inventory.md](docs/tool-inventory.md)를 참조하세요.
+
 ### Docker 배포
 
 ```bash
@@ -450,10 +497,12 @@ def register():
 | 기능 | 보호 내용 |
 |------|---------|
 | **위험 명령어 필터** | `rm -rf`, `mkfs`, 포크 폭탄, Windows 파괴적 명령어 차단 |
-| **API 키 암호화** | `~/.kyrozen_config.json` 정적 암호화 (XOR + 머신 파생 SHA-256 키) |
+| **API 키 암호화** | 무작위 설치 비밀을 사용하는 Fernet 암호화; 설정/비밀 파일 권한 `0600` |
 | **프롬프트 인젝션 보호** | 9가지 일반적인 인젝션 패턴 감지 및 필터링 |
 | **샌드박스 실행** | 파일 작업을 워크스페이스 경계 내로 제한 |
-| **Git 안전성** | 강제 푸시 없음, 하드 리셋 전 경고 |
+| **API 인증** | loopback 외 API/MCP 접근에는 `KYROZEN_SERVER_TOKEN` 필요 |
+| **Capability 프로필** | Web/MCP 기본값은 `workspace`; 되돌릴 수 없는 `git_reset`과 동적 도구는 `full`에서 명시적으로 허용 |
+| **Git 안전** | 강제 푸시 없음; CLI가 고영향 작업을 확인하고 기록 |
 | **감사 로그** | 모든 채팅/API 이벤트를 타임스탬프와 함께 `kyrozen_audit.log`에 기록 |
 | **Python 버전 가드** | Python 3.14+에서 시작 거부 |
 | **도구 실패 메모리** | 과거 실패를 기억하고 반복 방지 |
@@ -475,6 +524,18 @@ def register():
 | `KYROZEN_MODEL_SIMPLE` | 간단/중간 작업용 모델 | 제공자 기본값 |
 | `KYROZEN_MODEL_COMPLEX` | 복잡한 작업용 모델 | 제공자 기본값 |
 | `KYROZEN_BASE_URL` | 사용자 정의 API 기본 URL | 제공자 기본값 |
+| `KYROZEN_DB_PATH` | SQLite 사실 저장소 경로 | `~/.kyrozen/v2/openkyrozen.sqlite3` |
+| `KYROZEN_SERVER_TOKEN` | loopback 외 Web/MCP 접근 토큰 | 설정되지 않음 (loopback만) |
+| `KYROZEN_SERVER_ACTOR` | 단일 사용자 배포의 안정적인 actor 라벨 | `local` |
+| `KYROZEN_EXECUTION_SURFACE` | 실행 표면 (`cli` 또는 `web`) | `cli` |
+| `KYROZEN_ALLOW_DYNAMIC_TOOLS` | LLM 생성 Python 도구 허용 (`1`/`true`) | CLI: 활성화; Web/MCP: 비활성화 |
+| `KYROZEN_APPROVAL_MODE` | CLI 고영향 Git/동적 도구 확인 (`dangerous`/`never`) | `dangerous` |
+| `KYROZEN_WEB_CAPABILITIES` | Web capability (`readonly`, `workspace`, `full`) | `workspace` |
+| `KYROZEN_MCP_CAPABILITIES` | MCP capability (`readonly`, `workspace`, `full`) | `workspace` |
+| `KYROZEN_AGENT_CONFIG` | 명시적인 `agent.yaml` 경로 | 작업공간, 그 다음 패키지 기본값 |
+| `KYROZEN_ROLE` / `KYROZEN_ROLE_PROMPT` | role 이름 또는 role prompt 재정의 | 패키지 prompt |
+| `KYROZEN_INSTRUCTIONS` / `KYROZEN_EXAMPLES` | 실행 지침 또는 JSON examples 재정의 | 패키지 prompt |
+| `KYROZEN_AGENT_CAPABILITIES` | capability 상한 (surface/승인/인증 우회 불가) | `full` |
 
 ### 설정 파일 (`~/.kyrozen_config.json`)
 
@@ -497,6 +558,7 @@ def register():
 ```bash
 # 빠른 검증
 make check
+make docs-check
 
 # 구문 검사만
 make lint
@@ -524,9 +586,9 @@ make push
 
 GitHub Actions가 모든 푸시와 PR에서 자동 실행:
 - Python 3.12 및 3.13에서 구문 검사
-- 도구 인벤토리 검증
+- 실제 런타임 레지스트리에서 생성한 도구 목록과 문서 일관성 검사
 - 제공자 임포트 확인
-- Docker 빌드 검증
+- Docker 빌드 및 컨테이너 교체 복구 스모크 테스트
 
 ### pip 패키지
 
@@ -544,17 +606,18 @@ pip install '.[all]'            # + Claude + Gemini + Web
 ```
 OpenKyrozen/
 ├── main.py              # 코어 에이전트 루프, 자기 학습, 채팅 턴 로직
-├── tools.py             # 26개 내장 도구 (파일, 셸, Git, 웹)
+├── tools.py             # 기본 도구 29개; main.py가 SQLite 메모리 작업 2개 추가
 ├── providers.py         # 멀티 LLM 추상화 (5개 제공자 + 폴백)
-├── memory.py            # ChromaDB 기반 벡터 메모리
+├── memory.py            # SQLite 사실 메모리 + 재생성 가능한 Chroma 인덱스
 ├── server.py            # FastAPI 웹 서버 + REST API + 채팅 UI
 ├── pyproject.toml       # pip 패키지 설정
 ├── Dockerfile           # Docker 이미지 정의
 ├── Makefile             # 빌드 자동화 (macOS/Linux)
 ├── setup.bat / run.bat  # Windows 배치 스크립트
 ├── plugins/             # 플러그인 디렉토리 (훅 기반)
 ├── prompts/             # 프롬프트 템플릿 (역할, 지침, 예시)
-├── chroma_memory/       # ChromaDB 영구 저장소 (자동 생성)
+├── docs/tool-inventory.md # 생성된 런타임 도구/경로 인벤토리
+├── scripts/              # 재현 가능한 문서/스모크 검사
 └── .github/workflows/   # CI/CD 파이프라인
 ```