diff --git a/README.en.md b/README.en.md
index a6255981..beb50c32 100644
--- a/README.en.md
+++ b/README.en.md
@@ -1,6 +1,6 @@
 # Star Office UI
 
-🌐 Language: [中文](./README.md) | **English** | [日本語](./README.ja.md)
+🌐 Language: [中文](./README.md) | [한국어](./README.ko.md) | **English** | [日本語](./README.ja.md)
 
 ![Star Office UI Cover](docs/screenshots/readme-cover-2.jpg)
 
diff --git a/README.ja.md b/README.ja.md
index 1ab8d19d..c1926891 100644
--- a/README.ja.md
+++ b/README.ja.md
@@ -1,6 +1,6 @@
 # Star Office UI
 
-🌐 Language: [中文](./README.md) | [English](./README.en.md) | **日本語**
+🌐 Language: [中文](./README.md) | [한국어](./README.ko.md) | [English](./README.en.md) | **日本語**
 
 ![Star Office UI カバー](docs/screenshots/readme-cover-2.jpg)
 
diff --git a/README.ko.md b/README.ko.md
new file mode 100644
index 00000000..9a098f83
--- /dev/null
+++ b/README.ko.md
@@ -0,0 +1,294 @@
+# Star Office UI
+
+🌐 Language: [中文](./README.md) | **한국어** | [English](./README.en.md) | [日本語](./README.ja.md)
+
+![Star Office UI 커버](docs/screenshots/readme-cover-2.jpg)
+
+**픽셀 아트 스타일의 AI 사무실 대시보드** — AI 어시스턴트의 작업 상태를 실시간으로 시각화하여, "누가 무엇을 하고 있는지, 어제 무슨 일을 했는지, 지금 온라인인지"를 한눈에 보여줍니다.
+
+멀티 에이전트 협업, 다국어 UI(중/영/일), AI 기반 룸 디자인, 데스크톱 펫 모드를 지원합니다.
+[OpenClaw](https://github.com/openclaw/openclaw)와 함께 쓸 때 가장 좋은 경험을 제공하지만, 단독 상태 대시보드로도 사용할 수 있습니다.
+
+> 이 프로젝트는 **[Ring Hyacinth](https://x.com/ring_hyacinth)** 와 **[Simon Lee](https://x.com/simonxxoo)** 가 공동 제작(co-created project)했으며, 커뮤니티 기여자들([@Zhaohan-Wang](https://github.com/Zhaohan-Wang), [@Jah-yee](https://github.com/Jah-yee), [@liaoandi](https://github.com/liaoandi))과 함께 지속적으로 유지보수 및 발전시키고 있습니다.
+> 이슈와 PR을 환영하며, 모든 기여자분들께 감사드립니다.
+
+---
+
+## ✨ 빠른 시작
+
+### 방법 1: 랍스터에게 배포 맡기기 (OpenClaw 사용자 추천)
+
+[OpenClaw](https://github.com/openclaw/openclaw)를 사용 중이라면, 아래 문장을 그대로 랍스터에게 보내세요:
+
+```text
+Please follow this SKILL.md to deploy Star Office UI for me:
+https://github.com/ringhyacinth/Star-Office-UI/blob/master/SKILL.md
+```
+
+랍스터가 자동으로 저장소 클론, 의존성 설치, 백엔드 실행, 상태 동기화 설정을 마치고 접속 주소를 알려줍니다.
+
+### 방법 2: 30초 수동 설치
+
+> **요구 사항: Python 3.10+** (코드에서 `X | Y` 유니온 타입 문법을 사용하므로 3.9 이하는 지원하지 않습니다)
+
+```bash
+# 1) 저장소 클론
+git clone https://github.com/ringhyacinth/Star-Office-UI.git
+cd Star-Office-UI
+
+# 2) 의존성 설치 (Python 3.10+ 필요)
+python3 -m pip install -r backend/requirements.txt
+
+# 3) 상태 파일 초기화 (최초 1회)
+cp state.sample.json state.json
+
+# 4) 백엔드 실행
+cd backend
+python3 app.py
+```
+
+**http://127.0.0.1:19000** 을 열고 상태를 전환해 보세요:
+
+```bash
+python3 set_state.py writing "문서 정리 중"
+python3 set_state.py error "문제 발견, 디버깅 중"
+python3 set_state.py idle "대기 중"
+```
+
+![Star Office UI 미리보기](docs/screenshots/readme-cover-1.jpg)
+
+---
+
+## 🤔 누구에게 적합한가요?
+
+### OpenClaw / AI 에이전트 사용자
+**완전한 경험**을 누릴 수 있습니다. 에이전트가 작업할 때 자동으로 상태가 전환되고, 사무실 안의 픽셀 캐릭터가 해당 영역으로 실시간으로 이동합니다 — 웹페이지만 열어두면 AI가 지금 무엇을 하고 있는지 바로 확인할 수 있습니다.
+
+### OpenClaw 미사용자
+배포해서 사용하는 데 전혀 문제없습니다. 다음과 같이 활용할 수 있습니다:
+- `set_state.py` 또는 API로 수동/스크립트로 상태 푸시
+- 픽셀 아트 개인 상태 페이지 / 원격 근무 대시보드로 활용
+- HTTP 요청을 보낼 수 있는 모든 시스템에서 상태 갱신
+
+---
+
+## 📋 기능 한눈에 보기
+
+1. **상태 시각화** — 6가지 상태(`idle` / `writing` / `researching` / `executing` / `syncing` / `error`)가 사무실의 각 영역에 자동 매핑되어, 애니메이션 + 말풍선으로 실시간 표시
+2. **어제의 메모** — `memory/*.md`에서 최근 하루치 작업 기록을 자동으로 읽어 마스킹 후 "어제의 메모" 카드로 표시
+3. **멀티 에이전트 협업** — Join Key로 다른 에이전트를 사무실에 초대하고 모두의 상태를 실시간 확인
+4. **다국어 UI** — 중국어 / 영어 / 일본어 원클릭 전환, 인터페이스 텍스트·말풍선·로딩 메시지가 일제히 갱신
+5. **아트 에셋 커스터마이징** — 사이드바에서 캐릭터 / 장면 / 장식 에셋을 관리, 동적 프레임 동기화로 깜빡임 방지
+6. **AI 기반 룸 디자인** — Gemini API 연결로 사무실 배경을 AI가 새로 그려줌. API 없이도 핵심 기능은 정상 동작
+7. **모바일 대응** — 휴대폰에서 그대로 열 수 있어 외출 시에도 빠르게 확인 가능
+8. **보안 강화** — 사이드바 비밀번호 보호, 프로덕션 환경 약한 비밀번호 차단, 세션 쿠키 강화
+9. **유연한 외부 접속** — Cloudflare Tunnel로 원클릭 공개, 자체 도메인 / 리버스 프록시 사용 가능
+10. **데스크톱 펫 버전** — 픽셀 사무실을 투명 창의 데스크톱 펫으로 만들어주는 선택형 Electron 래퍼 제공 (아래 설명 참고)
+
+---
+
+## 🚀 상세 배포 가이드
+
+### 1) 의존성 설치
+
+```bash
+cd Star-Office-UI
+python3 -m pip install -r backend/requirements.txt
+```
+
+### 2) 상태 파일 초기화
+
+```bash
+cp state.sample.json state.json
+```
+
+### 3) 백엔드 실행
+
+```bash
+cd backend
+python3 app.py
+```
+
+`http://127.0.0.1:19000` 을 열어주세요.
+
+> ✅ 로컬 개발은 기본 설정으로 시작해도 무방합니다. 프로덕션 환경에서는 `.env.example`을 `.env`로 복사한 뒤 `FLASK_SECRET_KEY`와 `ASSET_DRAWER_PASS`에 강력한 랜덤 값을 설정하여 약한 비밀번호와 세션 유출을 방지하세요.
+
+### 4) 상태 전환
+
+```bash
+python3 set_state.py writing "문서 정리 중"
+python3 set_state.py syncing "동기화 진행 중"
+python3 set_state.py error "문제 발견, 디버깅 중"
+python3 set_state.py idle "대기 중"
+```
+
+### 5) 외부 접속 (선택)
+
+```bash
+cloudflared tunnel --url http://127.0.0.1:19000
+```
+
+발급받은 `https://xxx.trycloudflare.com` 링크를 공유하면 됩니다.
+
+### 6) 설치 검증 (선택)
+
+```bash
+python3 scripts/smoke_test.py --base-url http://127.0.0.1:19000
+```
+
+모든 검사 항목에 `OK`가 표시되면 배포 성공입니다.
+
+---
+
+## 🦞 OpenClaw 심층 통합
+
+> 이 섹션은 [OpenClaw](https://github.com/openclaw/openclaw) 사용자를 위한 내용입니다. OpenClaw를 사용하지 않는 경우 건너뛰셔도 됩니다.
+
+### 상태 자동 동기화
+
+`SOUL.md`(또는 에이전트 규칙 파일)에 아래 규칙을 추가하면 에이전트가 스스로 상태를 갱신합니다:
+
+```markdown
+## Star Office 상태 동기화 규칙
+- 작업 시작 시: 작업 전에 `python3 set_state.py <상태> "<설명>"` 실행
+- 작업 완료 시: 응답 전에 `python3 set_state.py idle "대기 중"` 실행
+```
+
+**6가지 상태 → 3개 영역 매핑:**
+
+| 상태 | 사무실 영역 | 사용 시점 |
+|------|-----------|---------|
+| `idle` | 🛋 휴게실 (소파) | 대기 / 작업 완료 |
+| `writing` | 💻 작업 영역 (책상) | 코드 / 문서 작성 |
+| `researching` | 💻 작업 영역 | 검색 / 리서치 |
+| `executing` | 💻 작업 영역 | 명령 실행 / 작업 수행 |
+| `syncing` | 💻 작업 영역 | 데이터 동기화 / 푸시 |
+| `error` | 🐛 버그 코너 | 에러 / 디버깅 |
+
+### 다른 에이전트를 사무실로 초대하기
+
+**Step 1: Join Key 준비**
+
+백엔드를 처음 실행할 때 프로젝트 루트에 `join-keys.json`이 없으면, 서비스가 `join-keys.sample.json`을 기반으로 자동 생성합니다(예시 키 `ocj_example_team_01` 포함). 생성된 `join-keys.json`에서 키를 추가/수정/삭제할 수 있으며, 각 키는 기본적으로 최대 3명 동시 접속을 지원합니다.
+
+**Step 2: 게스트 에이전트가 푸시 스크립트 실행**
+
+게스트는 `office-agent-push.py`만 다운로드해 변수 3개를 채우면 됩니다:
+
+```python
+JOIN_KEY = "ocj_starteam02"          # 호스트가 발급한 키
+AGENT_NAME = "민수의 랍스터"          # 표시 이름
+OFFICE_URL = "https://office.hyacinth.im"  # 사무실 주소
+```
+
+```bash
+python3 office-agent-push.py
+```
+
+스크립트가 자동으로 사무실에 입장하고 15초마다 상태를 푸시합니다. 게스트는 대시보드에 등장하여 상태에 따라 해당 영역으로 이동합니다.
+
+**Step 3 (선택): 게스트가 Skill 설치**
+
+`frontend/join-office-skill.md`을 Skill로 사용하면, 게스트의 에이전트가 설정과 푸시를 자동으로 처리합니다.
+
+> 자세한 게스트 온보딩 가이드는 [`frontend/join-office-skill.md`](./frontend/join-office-skill.md)를 참고하세요.
+
+---
+
+## 📡 주요 API
+
+| 엔드포인트 | 설명 |
+|----------|------|
+| `GET /health` | 헬스 체크 |
+| `GET /status` | 메인 에이전트 상태 조회 |
+| `POST /set_state` | 메인 에이전트 상태 설정 |
+| `GET /agents` | 에이전트 목록 조회 |
+| `POST /join-agent` | 게스트 사무실 입장 |
+| `POST /agent-push` | 게스트 상태 푸시 |
+| `POST /leave-agent` | 게스트 퇴장 |
+| `GET /yesterday-memo` | 어제의 메모 조회 |
+| `GET /config/gemini` | Gemini API 설정 조회 |
+| `POST /config/gemini` | Gemini API 설정 저장 |
+| `GET /assets/generate-rpg-background/poll` | 이미지 생성 진행 상황 폴링 |
+
+---
+
+## 🖥 데스크톱 펫 버전 (선택)
+
+`desktop-pet/` 디렉터리에는 픽셀 사무실을 투명 창의 데스크톱 펫으로 만들어주는 **Electron** 기반 데스크톱 래퍼가 포함되어 있습니다.
+
+```bash
+cd desktop-pet
+npm install
+npm run dev
+```
+
+- 시작 시 Python 백엔드 자동 실행
+- 창은 기본적으로 `http://127.0.0.1:19000/?desktop=1`을 가리킴
+- 환경 변수로 프로젝트 경로와 Python 경로를 커스터마이징 가능
+
+> ⚠️ 이 기능은 **선택형 실험 기능**으로, 주로 macOS에서 개발/테스트 중입니다. 자세한 내용은 [`desktop-pet/README.md`](./desktop-pet/README.md)를 참조하세요.
+>
+> 🙏 데스크톱 펫 버전은 [@Zhaohan-Wang](https://github.com/Zhaohan-Wang)님이 단독으로 개발해 주셨습니다. 기여에 감사드립니다!
+
+---
+
+## 🎨 아트 에셋 및 라이선스
+
+### 에셋 출처
+
+게스트 캐릭터 애니메이션은 **LimeZu**의 무료 에셋을 사용합니다:
+- [Animated Mini Characters 2 (Platformer) [FREE]](https://limezu.itch.io/animated-mini-characters-2-platform-free)
+
+재배포 / 데모 시 출처 표기를 유지하고 원작자의 라이선스 조항을 준수해 주세요.
+
+### 라이선스
+
+- **코드 / 로직: MIT** ([`LICENSE`](./LICENSE) 참조)
+- **아트 에셋: 상업적 사용 금지** (학습 / 데모 / 교류 용도만 허용)
+
+> 상업적 용도로 사용하려면 모든 아트 에셋을 본인이 직접 제작한 원본 자산으로 교체해야 합니다.
+
+---
+
+## 📝 변경 이력
+
+| 날짜 | 요약 | 상세 |
+|------|------|------|
+| 2026-03-06 | 🔌 기본 포트 변경 — 백엔드 기본 포트가 18791에서 19000으로 변경되어 OpenClaw Browser Control과의 충돌을 회피, 스크립트·데스크톱 셸·문서 기본값도 동기화 | [`docs/CHANGELOG_2026-03.md`](./docs/CHANGELOG_2026-03.md) |
+| 2026-03-05 | 📱 안정성 수정 — CDN 캐시 수정, 이미지 생성 비동기화, 모바일 사이드바 UX 개선, Join Key 만료 및 동시성 제어 | [`docs/UPDATE_REPORT_2026-03-05.md`](./docs/UPDATE_REPORT_2026-03-05.md) |
+| 2026-03-04 | 🔒 P0/P1 보안 강화 — 약한 비밀번호 차단, 백엔드 모듈 분리, stale 상태 자동 idle 복귀, 첫 화면 스켈레톤 최적화 | [`docs/UPDATE_REPORT_2026-03-04_P0_P1.md`](./docs/UPDATE_REPORT_2026-03-04_P0_P1.md) |
+| 2026-03-03 | 📋 오픈소스 릴리스 체크리스트 완료 | [`docs/OPEN_SOURCE_RELEASE_CHECKLIST.md`](./docs/OPEN_SOURCE_RELEASE_CHECKLIST.md) |
+| 2026-03-01 | 🎉 **v2 리메이크 릴리스** — 3개 언어 지원 추가, 에셋 관리 시스템, AI 룸 디자인, 아트 에셋 전면 교체 | [`docs/FEATURES_NEW_2026-03-01.md`](./docs/FEATURES_NEW_2026-03-01.md) |
+
+---
+
+## 📁 프로젝트 구조
+
+```text
+Star-Office-UI/
+├── backend/            # Flask 백엔드
+│   ├── app.py
+│   ├── requirements.txt
+│   └── run.sh
+├── frontend/           # 프런트엔드 페이지 및 에셋
+│   ├── index.html
+│   ├── join.html
+│   ├── invite.html
+│   └── layout.js
+├── desktop-pet/        # Electron 데스크톱 펫 (선택)
+├── docs/               # 문서 및 스크린샷
+│   └── screenshots/
+├── office-agent-push.py  # 게스트 푸시 스크립트
+├── set_state.py          # 상태 전환 스크립트
+├── state.sample.json     # 상태 파일 템플릿
+├── join-keys.sample.json # Join Key 템플릿 (실행 시 join-keys.json 생성)
+├── SKILL.md              # OpenClaw Skill
+└── LICENSE               # MIT 라이선스
+```
+
+---
+
+## ⭐ Star History
+
+[![Star History Chart](https://api.star-history.com/image?repos=ringhyacinth/Star-Office-UI&type=date&legend=top-left)](https://www.star-history.com/?repos=ringhyacinth%2FStar-Office-UI&type=date&legend=top-left)
diff --git a/README.md b/README.md
index de6ead6a..2d9aeda3 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # Star Office UI
 
-🌐 Language: **中文** | [English](./README.en.md) | [日本語](./README.ja.md)
+🌐 Language: **中文** | [한국어](./README.ko.md) | [English](./README.en.md) | [日本語](./README.ja.md)
 
 ![Star Office UI 封面](docs/screenshots/readme-cover-2.jpg)