Gitea Act Runner — Synology 기동 스크립트 + 토큰 홈 검증 도구

로컬 워크스페이스에서 Gitea Actions를 검증·디스패치할 수 있는
GITEA_TOKEN_HOME API 토큰 계약과, Synology에서 act_runner를
기동하는 스크립트를 추가한다.

- validate_gitea_token_home_v1.py: 저장소 메타데이터 조회, 워크플로
  접근 확인, workflow_dispatch 트리거 + 최신 실행 결과 폴링
- start_act_runner_synology.sh: Synology 환경에서 act_runner 기동
- setup_act_runner.sh: 기동 절차 갱신

docs/GITEA_TOKEN_HOME.md

@@ -0,0 +1,43 @@
+# GITEA_TOKEN_HOME
+
+`GITEA_TOKEN_HOME` is the local API token used to validate and optionally dispatch Gitea Actions from this workspace.
+
+## Purpose
+
+- Read repository metadata
+- Confirm workflow access
+- Optionally trigger a workflow dispatch
+- Poll the latest run for evidence
+
+## Harness
+
+Use:
+
+```bash
+python tools/validate_gitea_token_home_v1.py
+```
+
+To dispatch the KIS collector workflow as a smoke test:
+
+```bash
+python tools/validate_gitea_token_home_v1.py --dispatch --workflow kis_data_collection.yml --ref main
+```
+
+## Expected behavior
+
+- Without `GITEA_TOKEN_HOME`, the harness exits with `GITEA_TOKEN_HOME missing or empty`.
+- With a valid token, the harness should return `gate: PASS`.
+- With `--dispatch`, the harness posts a workflow dispatch and reports the latest run evidence.
+
+## Security notes
+
+- Do not print the token value.
+- Do not commit the token into repo files.
+- Treat the token as a repo-scoped write credential.
+
+## Troubleshooting
+
+- `401 Unauthorized`: token is missing, expired, or scoped to the wrong repository.
+- `404 Not Found`: repo path or workflow filename is wrong.
+- `latest_run_missing`: dispatch succeeded, but the workflow run did not appear in time; increase `--wait-seconds`.
+

docs/GITEA_TOKEN_HOME_RUNBOOK.md

@@ -0,0 +1,51 @@
+# GITEA_TOKEN_HOME Runbook
+
+## 1. Confirm presence
+
+Check that `GITEA_TOKEN_HOME` is set in the shell that runs the harness.
+
+## 2. Validate read-only access
+
+```bash
+python tools/validate_gitea_token_home_v1.py
+```
+
+Expected:
+
+- `gate = PASS`
+- repo access works
+- workflow metadata is readable
+
+## 3. Dispatch smoke test
+
+```bash
+python tools/validate_gitea_token_home_v1.py --dispatch --workflow kis_data_collection.yml --ref main
+```
+
+Expected:
+
+- dispatch returns `204` or `201`
+- latest run is visible in the API
+- run status becomes visible in the response payload
+
+## 4. If it fails
+
+- `GITEA_TOKEN_HOME missing or empty`: environment is not configured
+- `401 Unauthorized`: token is wrong or lacks repo scope
+- `404 Not Found`: repo or workflow path mismatch
+- `latest_run_missing`: dispatch accepted, but run listing lagged behind
+- `queued` or long `in_progress`: runner is busy or the job is waiting for the self-hosted runner slot
+
+## 5. Evidence to capture
+
+- Harness JSON output
+- Workflow run URL
+- Failing step name if the dispatched run fails
+- Runner status from the API if the job stays queued
+
+## Current run 161 finding
+
+- `Checkout Code` failed before Python started.
+- The repository checkout did not contain `GatherTradingData.json`.
+- This means the next fix is not token-related; it is seed-file availability at workflow runtime.
+- The workflow is now updated to regenerate the JSON from `GatherTradingData.xlsx` when possible and to fail with explicit recovery instructions when both are missing.