운영 문서와 상태판 동기화

docs/guides/local-development.md

@@ -124,6 +124,9 @@ npm install
 | `AUTH_EMAIL_COHORT_MAP` | `{}` | 특정 이메일을 cohort id로 매핑한다. 값은 comma-separated 문자열도 허용 |
 | `AUTH_DOMAIN_COHORT_MAP` | `{}` | 이메일/Google hosted domain을 cohort id로 매핑한다. Google/SAML/dev-login 세션 `cohort_ids`에 반영 |
 | `VIGNETTE_VOICE_POC_SAMPLE_TTS` | `false` | P1 무참조 샘플 음성을 `/voice/ws` TTS에 연결하는 개발 전용 플래그. 마이크/STT는 `OPENAI_API_KEY` 필요, 프로덕션 금지 |
+| `EVALUATOR_SEMANTIC_CACHE_ENABLED` | `true` | fast/deep evaluator structured 결과 인메모리 캐시 활성화. 원문 prompt/completion은 저장하지 않음 |
+| `EVALUATOR_SEMANTIC_CACHE_TTL_SECONDS` | `900` | evaluator cache TTL(초). 0 이하면 비활성 |
+| `EVALUATOR_SEMANTIC_CACHE_MAX_ENTRIES` | `256` | evaluator cache LRU 최대 엔트리 수. 0 이하면 비활성 |
 
 > 참고: 프로세스 환경변수(`$env:KEY`)는 `.env`보다 우선한다. 일회성 오버라이드에 쓸 수 있다.
 
@@ -153,6 +156,13 @@ python -m uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload
 이 호출은 `(code, version)` 누락분만 insert하며, 교수자가 수정한 DB 저작본이나 `archived` 보관본을 덮어쓰거나 재노출하지 않는다.
 (또는 `apps/api/.env`에 두 키를 `true`로 적어도 된다.)
 
+seed manifest만 확인할 때는 API 서버 없이 저장소 루트에서 dry-run runner를 실행한다. Windows에서 `python` 별칭이 다른 인터프리터를 가리키면 API 의존성이 없을 수 있으므로, 이 저장소에서는 Python 3.11 런처를 우선 쓴다. `--apply`는 DB pool을 초기화한 뒤 기존 idempotent DB materializer를 호출하므로 로컬 DB 대상이 맞는지 확인한 뒤에만 쓴다.
+
+```powershell
+cd D:\workspace\vignette
+py -3.11 scripts\materialize-persona-seeds.py --json
+```
+
 ### 2.4 DB 없이 degraded 기동 (정상 동작)
 
 DB 연결이 안 되어도 dev에서는 그대로 기동한다. `main.py` lifespan이 풀 초기화 예외를 잡고
@@ -180,6 +190,32 @@ Invoke-RestMethod http://127.0.0.1:8000/health
 curl.exe http://127.0.0.1:8000/health
 ```
 
+운영 콘솔 헬스 샘플을 브라우저 방문 없이 DB에 1회 적재하려면 저장소 루트에서 아래를 실행한다.
+이 스크립트는 `apps/api/.env`를 읽고 API lifespan과 같은 DB/engine/voice 초기화 경로를 사용해
+`app.admin_health_event`에 서비스별 샘플을 append한다. SLA 수치가 아니라 관측 샘플 이력이다.
+
+```powershell
+C:\Users\encep\AppData\Local\Programs\Python\Python311\python.exe scripts\record-admin-health-sample.py --json
+
+# 예약 작업 명령 확인만
+powershell -NoProfile -ExecutionPolicy Bypass -File scripts\install-health-sampler-task.ps1 -PrintOnly
+
+# 실제 등록 + 즉시 1회 실행
+powershell -NoProfile -ExecutionPolicy Bypass -File scripts\install-health-sampler-task.ps1 -IntervalMinutes 5 -RunNow
+```
+
+쌓인 원시 헬스 샘플은 명시 기간을 준 maintenance 스크립트로 일별 rollup에 먼저 집계한 뒤 정리한다.
+기본은 dry-run이며, 실제 삭제는 `--apply`를 붙였을 때만 수행한다. non-dev 환경에서는
+`--allow-non-dev-apply`가 없으면 apply가 차단된다.
+
+```powershell
+# 영향 범위 확인
+C:\Users\encep\AppData\Local\Programs\Python\Python311\python.exe scripts\maintain-admin-health-events.py --rollup-days 2 --retention-days 30 --json
+
+# dev DB에서만 실제 적용
+C:\Users\encep\AppData\Local\Programs\Python\Python311\python.exe scripts\maintain-admin-health-events.py --rollup-days 2 --retention-days 30 --apply --json
+```
+
 ---
 
 ## 3. dev 로그인 (로컬/E2E용 서버 로그인)
@@ -271,8 +307,23 @@ Invoke-RestMethod -Method Post `
 ```
 
 응답의 `skipped_unchanged`가 0보다 크면 content_hash가 동일해 재색인을 건너뛴 source pack이 있다는 뜻이다.
+현재 sync 경로는 active `kb.document`의 hash/version을 먼저 읽고, hash가 바뀐 pack만 다음 document version으로 색인한다.
 임베딩 모델이 없으면 `degraded=true`로 BM25-only 색인이 되지만, 라이브 코칭 기본 로컬 근거는 계속 동작한다.
 
+API 서버 없이 DB에 직접 비교/적용하려면 저장소 루트에서 runner를 쓴다. 기본은 DB-backed dry-run이라 write하지 않고, `--apply`에서만 `kb.source` upsert와 `kb.document/kb.chunk` 색인을 수행한다.
+
+```powershell
+cd D:\workspace\vignette
+py -3.11 scripts\sync-persona-sources.py --json
+py -3.11 scripts\sync-persona-sources.py --apply --json
+```
+
+DB 없이 CLI shape만 확인하려면:
+
+```powershell
+py -3.11 scripts\sync-persona-sources.py --help
+```
+
 ---
 
 ## 4. 웹(프런트엔드) 실행