easygap · Sep 22, 2026 · Sep 22, 2026 · Sep 22, 2026
diff --git a/README.md b/README.md
@@ -2,98 +2,78 @@
 
 # 눈금
 
-**국내 주식·ETF 자동매매 프로그램**
+**국내 주식·ETF 자동매매**
 
-한국투자증권 KIS API를 지원하는 Python 프로그램입니다. 설정한 종목과 비중에 따라 자동으로 매매하고, 웹 화면에서 투자금과 수익률을 확인합니다. 기본 설정은 모의투자입니다.
+정해 둔 종목과 비중에 맞춰 주식과 ETF를 사고파는 프로그램입니다. 계좌 화면에서 투자금, 수익률, 보유 종목을 볼 수 있습니다.
 
-[설치 방법](#설치-및-실행) · [백테스트 결과](docs/RISK_REVIEW_20260922.md) · [문의](https://github.com/easygap/quant_trader/issues/new/choose)
+내 PC에 설치해서 사용하며, 모의투자로 시작합니다.
 
-![계좌에서 날짜별 수익률을 확인하고 차트 모양을 바꾸는 모습](docs/images/readme-walkthrough-20260922.gif)
+[설치하기](docs/GETTING_STARTED.md) · [사용법](docs/USER_GUIDE.md) · [백테스트](#백테스트) · [문의](https://github.com/easygap/quant_trader/issues/new/choose)
 
-2026년 9월 22일에 촬영한 모의투자 화면입니다. [이미지로 보기](docs/images/readme-account-20260922.png)
+## 수익률
 
-## 주요 기능
+![날짜별 투자금과 수익률, 입체·평면 차트](docs/images/readme-walkthrough-20260922.gif)
 
-- **계좌 조회**: 투자원금, 평가금액, 수익률을 날짜별로 확인하고 CSV로 저장합니다.
-- **자동매매**: 정해 둔 종목과 비중에 맞춰 매수·매도합니다. 주문 전에 잔고와 거래 한도를 확인합니다.
-- **모의투자**: 가상 자금으로 매매해 보고, 주문 내역과 수익률을 확인합니다.
-- **백테스트**: 과거 주가로 매매 규칙을 시험하고 수익률, 손실, 거래 비용을 비교합니다.
+모의투자 화면 · 2026.09.22 · [정지 화면](docs/images/readme-account-20260922.png)
 
-계좌에 돈을 추가로 넣어도 수익률이 부풀려지지 않도록 계산합니다. 차트 아래에서 날짜를 고르면 그날의 투자금과 수익률이 함께 바뀝니다.
+날짜를 고르면 그날의 금액과 수익률이 나옵니다. 추가로 넣은 돈은 원금으로 따로 계산합니다. 차트 아래 **기록 내려받기**를 누르면 날짜별 내역을 CSV 파일로 저장할 수 있습니다.
 
-## 설치 및 실행
-
-**Python 3.11 또는 3.12와 Git**이 필요합니다. 아래는 Windows PowerShell 기준입니다.
-
-```powershell
-git clone https://github.com/easygap/quant_trader.git
-cd quant_trader
-python -m venv .venv
-.\.venv\Scripts\python.exe -m pip install -r requirements.txt
+## 보유 종목
 
-if (-not (Test-Path config/settings.yaml)) {
-    Copy-Item config/settings.yaml.example config/settings.yaml
-}
-if (-not (Test-Path .env)) {
-    Copy-Item .env.example .env
-}
+![대형주 계좌의 보유 수량, 평균 매수가, 종목별 비중](docs/images/readme-holdings-20260922.png)
 
-.\.venv\Scripts\python.exe main.py --mode dashboard
-```
+종목별 보유 수량과 평균 매수가, 투자 비중을 보여 줍니다. 지금 비중이 처음 정한 목표와 얼마나 다른지도 바로 비교할 수 있습니다.
 
-브라우저에서 **[127.0.0.1:8080](http://127.0.0.1:8080)**을 열면 됩니다. 이 명령은 계좌 화면만 엽니다. 자동매매는 별도로 실행해야 합니다.
+비중은 매수한 금액으로 계산합니다. 현재 가격을 반영한 평가금액과 손익은 표 아래에 있습니다.
 
-처음 설치하면 저장된 거래가 없어 계좌가 비어 있습니다. [설정과 모의투자 실행 방법](docs/GETTING_STARTED.md)을 따라 시작하세요.
+## 자동매매
 
-## 보유 종목
+**ETF 적립**과 **대형주 분산 투자**, 두 가지 기본 설정이 들어 있습니다. 종목과 투자 비중은 직접 바꿀 수 있습니다. ETF 적립 설정은 현재 모의투자 전용입니다.
 
-몇 주를 샀는지, 평균 매수가는 얼마인지, 목표 비중과 얼마나 차이가 나는지 확인할 수 있습니다.
+주문 전에는 잔고와 거래 한도를 확인합니다. 마지막 실행 시각과 거래 중지 사유는 **자동매매 상태**에 표시합니다.
 
-![대형주 계좌의 보유 수량, 평균 매수가, 종목별 비중](docs/images/readme-holdings-20260922.png)
+![마지막 실행 시각, 거래 중지 여부, 증권사 연결 상태](docs/images/readme-operations-20260922.png)
 
-종목별 비중은 **매수한 금액 기준**입니다. 현재 가격으로 계산한 보유 주식의 금액과 손익은 표 아래에 따로 나옵니다.
+[기본 매매 설정과 사용법](docs/USER_GUIDE.md#매매-설정)
 
 <details>
-<summary>자동매매 상태와 모바일 화면 보기</summary>
+<summary>모바일 화면</summary>
 
-### 자동매매 상태
+<a href="docs/images/dashboard-mobile-20260922.png"><img src="docs/images/readme-mobile-20260922.png" alt="휴대폰 크기의 계좌 화면" width="300"></a>
 
-마지막 실행 시각과 거래 중지 여부, 증권사 연결 상태를 확인할 수 있습니다. 문제가 있으면 안내를 눌러 해당 화면으로 이동합니다.
+작은 화면에서는 계좌 금액과 차트를 위아래로 배치합니다. 날짜는 터치로 바꿀 수 있습니다. 휴대폰 접속에는 [별도의 연결 설정](docs/USER_GUIDE.md#모바일-접속)이 필요합니다.
 
-![자동매매의 마지막 실행 시각과 연결 상태](docs/images/readme-operations-20260922.png)
-
-### 모바일 화면
+</details>
 
-휴대폰 화면에 맞춰 수익률, 계좌 금액, 차트 순서로 표시합니다. 차트의 날짜는 터치로 바꿀 수 있습니다. 휴대폰에서 접속하려면 PC의 기본 접속 설정을 바꿔야 합니다.
+## 백테스트
 
-<a href="docs/images/dashboard-mobile-20260922.png"><img src="docs/images/readme-mobile-20260922.png" alt="모바일 화면의 ETF 적립 계좌와 수익률 차트" width="300"></a>
+과거 주가로 매매 조건을 시험해 볼 수 있습니다. 거래 비용을 반영한 수익률과 크게 하락했던 구간을 함께 비교합니다.
 
-[모바일 전체 화면 보기](docs/images/dashboard-mobile-20260922.png)
+[백테스트 결과와 계산 조건](docs/RISK_REVIEW_20260922.md)
 
-</details>
+모의투자와 백테스트에서 수익이 났더라도 실제 투자에서는 손실이 날 수 있습니다. CD금리 ETF도 원금을 보장하지 않습니다.
 
-## 기본 매매 설정
+## 시작하기
 
-- **ETF 적립**: KODEX 200과 TIGER CD금리 ETF에 나눠 투자합니다. 시작 금액은 30만원, 월 적립 계획은 10만원입니다.
-- **대형주 분산 투자**: 국내 대형주에 나눠 투자합니다. 주식 60%·현금 40%를 목표로 하며, 비중 차이가 커지면 조정합니다.
+**Python 3.11 또는 3.12와 Git**이 필요합니다. 설치 안내는 Windows PowerShell 기준입니다.
 
-종목과 비중은 [config/baskets.yaml](config/baskets.yaml)에서 바꿀 수 있습니다. ETF 적립은 현재 모의투자 전용입니다. 추가 투자금은 화면에 직접 기록하며, 자동이체 기능은 없습니다.
+1. [설치 안내](docs/GETTING_STARTED.md)에 따라 프로그램을 설치합니다.
+2. [모의투자](docs/GETTING_STARTED.md#모의투자)를 실행합니다.
+3. 설치한 PC에서 [계좌 화면](http://127.0.0.1:8080)을 엽니다. 날짜 선택과 파일 저장은 [사용법](docs/USER_GUIDE.md)에 설명했습니다.
 
-백테스트 결과에는 수익률뿐 아니라 **가장 많이 하락한 폭과 거래 비용**도 함께 정리했습니다. [비교 조건과 결과 보기](docs/RISK_REVIEW_20260922.md)
+처음 실행하면 거래 기록이 없는 계좌가 열립니다. 자동매매는 계좌 화면과 별도로 실행하며, PC와 자동매매 프로그램을 켜 두어야 합니다.
 
-모의투자와 백테스트 결과가 좋아도 실제 투자에서는 손실이 날 수 있습니다. CD금리 ETF도 원금을 보장하지 않습니다. 실제 계좌를 연결하기 전에는 [주문 설정과 확인 사항](docs/PAPER_TO_LIVE_RUNBOOK.md)을 읽어 주세요.
+실제 계좌 연결은 한국투자증권 KIS API를 사용합니다. 연결 방법과 주문 설정은 [실제 계좌 사용 안내](docs/PAPER_TO_LIVE_RUNBOOK.md)에 있습니다.
 
-## 사용 안내
+## 문의
 
-- [설치와 첫 모의투자](docs/GETTING_STARTED.md)
-- [자동 실행과 설정 파일 설명](docs/PROJECT_GUIDE.md)
-- [실제 계좌 연결](docs/PAPER_TO_LIVE_RUNBOOK.md)
-- [거래가 중지됐을 때 확인할 것](docs/SAFETY_MODEL.md)
+오류가 나거나 필요한 기능이 있으면 [오류 제보·기능 제안](https://github.com/easygap/quant_trader/issues/new/choose)에 남겨 주세요. 화면이나 오류 메시지를 올릴 때는 계좌번호와 API 키를 지워 주세요.
 
-Python · aiohttp · SQLite를 사용합니다. 웹 화면은 HTML/CSS/JavaScript로 만들었으며, 프런트엔드는 따로 설치하거나 빌드할 필요가 없습니다.
+도움이 됐다면 **Star**를 눌러 주세요.
 
-## 문의와 의견
+<details>
+<summary>개발 문서</summary>
 
-잘 안 되는 기능이나 필요한 기능이 있으면 [GitHub Issues](https://github.com/easygap/quant_trader/issues/new/choose)에 남겨 주세요. 오류 화면이나 메시지를 함께 올려 주시면 원인을 찾는 데 도움이 됩니다. 계좌번호와 API 키는 지우고 올려 주세요.
+Python · aiohttp · SQLite · HTML/CSS/JavaScript를 사용합니다. 코드 구조와 자동 실행 설정은 [개발 문서](docs/PROJECT_GUIDE.md)에 정리했습니다.
 
-유용하게 쓰셨다면 오른쪽 위 **Star**를 눌러 주세요.
+</details>
diff --git a/docs/GETTING_STARTED.md b/docs/GETTING_STARTED.md
@@ -38,6 +38,8 @@ if (-not (Test-Path .env)) {
 
 처음 설치하면 저장된 거래가 없어 계좌가 비어 있습니다. README의 캡처는 기존 모의투자 계좌의 기록입니다. 설치 직후에는 캡처에 나온 금액과 수익률이 표시되지 않습니다.
 
+계좌 선택, 날짜별 수익률, 적립금 입력은 [계좌 화면 사용법](USER_GUIDE.md)에 설명했습니다.
+
 기본 접속 주소는 이 PC에서만 열립니다. 포트를 바꾸려면 다음처럼 실행합니다.
 
 ```powershell
@@ -46,6 +48,8 @@ if (-not (Test-Path .env)) {
 
 ## 모의투자
 
+계좌 화면을 켜 둔 채 진행하려면 PowerShell 창을 새로 열고, 설치한 `quant_trader` 폴더로 이동하세요.
+
 매매할 종목과 비중은 [config/baskets.yaml](../config/baskets.yaml)에서 정합니다. `kr_pocket`은 ETF 적립 계좌, `kr_diversified_hold`는 대형주 분산 계좌입니다.
 
 먼저 어떤 주문을 낼지 확인합니다. 주가를 불러오므로 인터넷 연결이 필요합니다.

diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md
@@ -0,0 +1,76 @@
+# 계좌 화면 사용법
+
+[설치 안내](GETTING_STARTED.md) · [README](../README.md)
+
+## 계좌 선택
+
+화면 위쪽에서 **ETF 적립** 또는 **대형주 분산 투자**를 누릅니다. 선택한 계좌에 맞춰 금액, 수익률 차트, 보유 종목이 바뀝니다.
+
+처음 설치했다면 아직 거래 기록이 없습니다. [모의투자 실행 방법](GETTING_STARTED.md#모의투자)에 따라 한 번 실행한 뒤 화면을 새로고침하세요. 주문 조건에 맞지 않으면 거래가 없을 수도 있습니다.
+
+## 수익률
+
+차트 아래의 날짜 막대를 움직이면 그날의 금액과 수익률이 나옵니다. **최근 날짜**를 누르면 마지막 기록으로 돌아갑니다.
+
+- **투자원금**: 처음 넣은 돈과 나중에 추가한 돈입니다.
+- **평가금액**: 보유 주식·ETF의 금액과 현금을 합한 금액입니다.
+- **수익률**: 돈을 넣고 뺀 영향을 제외한 투자 수익률입니다.
+
+입금은 수익으로 계산하지 않습니다. 수익률 계산 방식은 흔히 쓰는 이름으로 **시간가중수익률(TWR)**이라고 합니다.
+
+**입체**와 **평면**은 같은 수익률을 다른 모양으로 보여 줍니다. 입체 차트의 띠 너비가 별도의 투자 지표를 뜻하지는 않습니다.
+
+[계좌 화면 크게 보기](images/readme-account-20260922.png)
+
+## 내역 저장
+
+차트 아래 **기록 내려받기**를 누르면 CSV 파일이 저장됩니다. 선택한 계좌와 기간에 해당하는 날짜, 평가금액, 투자원금, 수익률, 고점 대비 하락률이 들어 있습니다. 엑셀에서도 열 수 있습니다.
+
+## 보유 종목
+
+종목마다 보유 수량, 평균 매수가, 매수한 금액, 비중이 나옵니다. 지금 비중과 목표 비중을 나란히 비교할 수 있습니다.
+
+이 표의 비중은 **매수한 금액 기준**입니다. 현재 가격으로 계산한 보유 주식의 금액과 손익은 표 아래에 따로 표시합니다.
+
+[보유 종목 화면 크게 보기](images/readme-holdings-20260922.png)
+
+## 적립금 기록
+
+모의투자에 쓸 가상 자금을 추가하는 기능입니다.
+
+1. 화면 위쪽의 **적립금 기록**을 누릅니다.
+2. 계좌를 고르고 금액을 입력합니다. 필요하면 메모도 남깁니다.
+3. **내용 확인**을 누른 뒤 계좌, 금액, 모의투자 여부를 다시 확인하고 기록합니다.
+
+은행에서 돈을 가져오거나 자동이체를 등록하는 기능은 아닙니다. 추가한 금액은 모의투자 원금에 더해집니다.
+
+## 매매 설정
+
+기본으로 사용하는 설정은 두 가지입니다.
+
+- **ETF 적립**: KODEX 200과 TIGER CD금리 ETF에 나눠 투자합니다. 시작 금액은 30만원, 월 적립 계획은 10만원입니다. 추가 투자금은 직접 기록합니다.
+- **대형주 분산 투자**: 국내 대형주에 나눠 투자합니다. 주식 60%·현금 40%를 목표로 하며, 비중 차이가 커지면 조정합니다.
+
+종목과 비중은 [config/baskets.yaml](../config/baskets.yaml)에서 바꿉니다. 설정 파일의 `kr_pocket`은 ETF 적립, `kr_diversified_hold`는 대형주 분산 투자입니다.
+
+ETF 적립 설정은 현재 모의투자 전용입니다. 1주 가격과 최소 주문금액 때문에 실제 매수 비중이 목표와 다를 수 있습니다. CD금리 ETF도 원금을 보장하지 않습니다.
+
+## 자동매매 상태
+
+**자동매매 상태**에는 마지막 실행 시각, 거래 중지 여부, 증권사 연결과 데이터 갱신 상태가 나옵니다. 오류가 표시되면 **다시 확인**을 눌러 상태를 새로 불러옵니다.
+
+자동매매는 계좌 화면과 별도로 실행합니다. 계속 매매하려면 PC와 자동매매 프로그램을 켜 두어야 합니다. 화면만 열어 놓아서는 매매가 시작되지 않습니다.
+
+- [자동 실행 설정](PROJECT_GUIDE.md)
+- [거래가 중지됐을 때 확인할 것](SAFETY_MODEL.md)
+- [실제 계좌 연결과 주문 설정](PAPER_TO_LIVE_RUNBOOK.md)
+
+## 모바일 접속
+
+화면은 휴대폰 크기에 맞춰 바뀝니다. 차트의 날짜도 터치로 고를 수 있습니다.
+
+기본 주소 `127.0.0.1`은 프로그램을 실행한 PC에서만 열립니다. 휴대폰에서 접속하려면 접속 주소와 인증을 별도로 설정해야 합니다. [연결 설정](PROJECT_GUIDE.md)을 참고하세요.
+
+## 문의
+
+[오류 제보·기능 제안](https://github.com/easygap/quant_trader/issues/new/choose)에 문제가 생긴 상황과 화면을 남겨 주세요. 계좌번호, API 키, 비밀번호는 지우고 올려 주세요.