KIS·정성매도·스냅샷어드민·캘리브레이션을 CI/npm/문서에 통합 배선

이전 커밋들에서 추가한 기능을 실제로 동작시키는 배선 작업.

- .gitea/workflows/ci.yml: No Direct API Trading 게이트, KIS 자격증명
  검증(mock), 캘리브레이션 백로그 빌드, 정성매도 파이프라인 검증,
  Gitea secrets 계약 검증, snapshot admin 워크플로/웹 검증 단계 추가
- package.json: ops:data-collect, ops:sell-*, ops:snapshot-*,
  ops:calibration-* npm 스크립트 추가
- src/gas/core/gas_lib.gs doPost(): "trigger_run_all" action 추가 —
  Gitea CI가 공유 비밀키로 run_all()을 원격 트리거(주문 실행 없음,
  governance/rules/06·07과 동일 원칙)
- tools/trigger_gas_run_all_v1.py: 위 GAS 엔드포인트를 호출하는 CLI
- AGENTS.md/README.md: 신규 파일 인덱스 및 사용 가이드 갱신

README.md

@@ -10,6 +10,20 @@
 - 최종 후보 내 KOSDAQ: 최대 20개
 - 1차 탐색 총량은 v3와 동일한 200개로 유지하여 호출 수 증가를 막습니다.
 
+## KIS 사용 가이드
+
+이 저장소의 데이터 팩터 수집 기본 코어는 KIS Open API입니다.
+
+- 실제계좌: `KIS_APP_Key`, `KIS_APP_Secret`
+- 모의계좌: `KIS_APP_Key_TEST`, `KIS_APP_Secret_TEST`
+- API 유효성 확인은 모의계좌 환경변수로 수행하고, 데이터 수집은 실제계좌 환경변수로 수행
+- 사용 범위: 조회형 `quotations` / `ranking` 계열만 사용
+- 금지 범위: 주문, 정정, 취소, 잔고조회는 사용하지 않음
+- 폴백 순서: `KIS -> Naver Finance -> Yahoo Finance -> OpenDART -> Investing.com(best-effort)`
+
+CI 스케줄러는 `GatherTradingData.json`을 seed snapshot으로 사용하고, read-only API로 보강한 뒤 SQLite에 누적 저장합니다.
+코드는 저장 백엔드를 `backend contract`로 분리해 두었고, 지금은 SQLite만 실행하지만 향후 PostgreSQL로 옮겨도 수집기 호출부를 크게 바꾸지 않도록 해 둔 상태입니다.
+
 ## 설치
 
 ```powershell
@@ -24,6 +38,52 @@ $env:DART_API_KEY="발급받은키"
 node core_satellite_collector.js
 ```
 
+SQLite 기반 데이터 수집을 실행하려면:
+
+```powershell
+$env:KIS_APP_Key="실제계좌키"
+$env:KIS_APP_Secret="실제계좌시크릿"
+python tools/run_kis_data_collection_v1.py --input-json GatherTradingData.json --sqlite-db outputs/kis_data_collection/kis_data_collection.db --output-json Temp/kis_data_collection_v1.json --kis-account real
+```
+
+### Snapshot admin web UI
+
+엑셀처럼 `settings`와 `account_snapshot`를 편집하려면 웹 UI를 실행한다.
+
+```bash
+python tools/run_snapshot_admin_server_v1.py --db outputs/snapshot_admin/snapshot_admin.db --seed GatherTradingData.json
+```
+
+기본 흐름은 다음과 같다.
+
+1. `GatherTradingData.json` 또는 기존 SQLite DB를 seed로 적재
+2. 웹 화면에서 `settings`와 `account_snapshot`을 검토/편집
+3. 저장 시 SQLite에 반영
+4. 필요하면 `/api/export`로 JSON을 내려받아 CI 또는 검증에 사용
+5. 변경 이력, 승인, 잠금, undo는 웹 화면의 `Approval & Locks` 영역에서 관리
+6. 변경 검토용 승인 패킷은 `Export approval packet` 버튼으로 `Temp/snapshot_admin_approval_packet_v1.json`에 저장한다.
+
+웹 UI 스모크 검증은 아래 명령으로 실행한다.
+
+```bash
+python tools/validate_snapshot_admin_web_v1.py
+```
+```
+
+### Calibration backlog
+
+보정 백로그와 change ledger를 다시 만들려면 아래 명령을 사용한다.
+
+```powershell
+python tools/build_calibration_priority_v1.py
+python tools/build_calibration_change_ledger_v4.py
+python tools/build_calibration_review_report_v1.py
+python tools/build_calibration_approval_list_v1.py
+python tools/validate_calibration_change_ledger_v1.py
+```
+
+Gitea 스케줄러에서는 `.gitea/workflows/calibration_backlog.yml`이 weekday 자동 갱신을 수행한다.
+
 ## 운영 표준
 
 릴리즈와 패키징의 기준 진입점은 아래를 사용합니다.
@@ -52,6 +112,7 @@ npm run prepare-upload-zip
 - `npm run ops:package`
 - `npm run ops:validate`
 - `npm run ops:build`
+- `npm run ops:snapshot-web-validate`
 - `npm run render-report-json`
 - `npm run validate-proposal-reference`
 - `npm run validate-gas-call-arity`
@@ -70,6 +131,14 @@ npm run prepare-upload-zip
 6. `npm run full-gate` 실행
 7. 최종 운영 전환 시 `npm run prepare-upload-zip`로 패키지 생성 여부를 확인
 
+## CI 전환 체크리스트
+
+1. `python tools/run_kis_data_collection_v1.py` 또는 `npm run ops:data-collect`로 SQLite 수집을 먼저 검증
+2. `outputs/kis_data_collection/kis_data_collection.db`에 `collection_runs` / `collection_snapshots`가 생성되는지 확인
+3. Gitea 스케줄러가 `GatherTradingData.json`을 seed로 읽는지 확인
+4. `GatherTradingData.xlsx` 의존성을 제거한 후에도 수집이 유지되는지 확인
+5. 이후 PostgreSQL 업그레이드 시 동일 row contract를 유지
+
 ## 운영 리포트 계약
 
 운영 리포트는 사람이 읽는 `Temp/operational_report.md`와 기계 검증용 `Temp/operational_report.json`을 함께 생성합니다.