feat: ToolCard 버전 관리 + 퀵 테스트 + Admin UX 개선 + README 전면 재작성

- ToolCardStore: JSON 영속화, 버전 이력, Diff, 롤백 지원
- Admin Dashboard 퀵 테스트 탭: 실시간 쿼리 검색, 배치 Recall 평가, LLM-as-Judge 분석
- Admin UX: 비개발자 가이드 패널, 안전/위험 동작 시각 구분, 마크다운 렌더링
- 검색 결과 가독성: 점수 바 시각화, Recall 카드 설명 추가, 스텝 넘버링
- README: 음/슴체 통일, 구조 재편(문제→전략→결과→상세→운영), 핵심 중심 압축

Co-authored-by: Cursor <cursoragent@cursor.com>

README.md

@@ -8,33 +8,31 @@ app_port: 7860
 pinned: false
 ---
 
-# AI TMR Assistant — Tool Routing 고도화
+# AI TMR Assistant — Intelligent Tool Routing
 
-> **Intelligent Tool Routing**으로 정확도를 개선하고, **Scalable Tool Architecture**로 운영 효율과 확장성을 동시에 확보함
+> 54개 도구를 운용하는 보험 AI 챗봇에서, **필요한 도구만 골라 전달하는 검색 기반 라우팅**으로 정확도·비용·지연을 동시에 개선함
 
 ---
 
-## 1. 무엇을 해결하려 했는가
+## 1. 문제
 
-12개 보험 상품 × 9개 기능(조회·산출·심사·보장·청구·컴플라이언스 등) = **54개 도구**를 운용하는 AI 챗봇.
-도구가 많아지면서 세 가지 문제가 발생함.
+12개 보험 상품 × 9개 기능(조회·산출·심사·보장·청구 등) = **54개 도구**.
+도구가 많아지면서 세 가지 문제가 생김.
 
 | 문제 | 원인 | 영향 |
 |------|------|------|
 | 오호출 | 유사 도구 혼동 (premium_estimate ↔ plan_options) | 잘못된 답변 |
-| 비용 증가 | 매 요청마다 54개 스키마가 LLM 컨텍스트에 포함 | 토큰 낭비 |
-| 지연 증가 | 컨텍스트 길이에 비례한 응답 시간 상승 | UX 저하 |
+| 비용 증가 | 매 요청마다 54개 스키마가 LLM 컨텍스트에 포함됨 | 토큰 낭비 |
+| 지연 증가 | 컨텍스트 길이에 비례하여 응답 시간이 상승함 | UX 저하 |
 
-> 도구 10개 초과 시 정확도가 저하되고, 37개 기준 ~6,200 토큰 소비 [(참고)](https://achan2013.medium.com/how-many-tools-functions-can-an-ai-agent-has-21e0a82b7847).
-> "전부 넘기지 말고, 필요한 것만 검색해서 넘기자" — RAG-MCP 패턴 [(참고)](https://writer.com/engineering/rag-mcp/)
+도구 10개를 넘으면 정확도가 떨어지고, 37개 기준 ~6,200 토큰이 소비됨 [(참고)](https://achan2013.medium.com/how-many-tools-functions-can-an-ai-agent-has-21e0a82b7847).
+"전부 넘기지 말고 필요한 것만 검색해서 넘기자" — 이것이 RAG-MCP 패턴의 핵심임 [(참고)](https://writer.com/engineering/rag-mcp/).
 
 ---
 
-## 2. 어떻게 해결했는가
+## 2. 해결 전략
 
-### 전략 A. Intelligent Tool Routing — 54개를 5개로 줄임
-
-Guardrail → Tool Search → LLM 선택, 3단계 필터링으로 정확한 도구만 LLM에 전달함.
+### 2-1. 3단계 필터링으로 54개를 5개로 줄임
 
 ```
 사용자 질문
@@ -49,32 +47,51 @@ Guardrail → Tool Search → LLM 선택, 3단계 필터링으로 정확한 도
 
 | 단계 | 모듈 | 기능 | 속도 |
 |------|------|------|------|
-| Guardrail | 정규식(L1) + 임베딩(L2) | 탈옥·비보험 질문 차단 | <5ms |
+| Guardrail | 정규식(L1) + 임베딩(L2) | 탈옥·비보험 질문 사전 차단 | <5ms |
 | Tool Search | ChromaDB 멀티벡터 | 54개 → Top-K 후보 추출 | ~10ms |
-| LLM Selection | bind_tools() | 후보 중 실제 필요한 도구만 호출 | 1~5s |
+| LLM Selection | bind_tools() | 후보 중 최종 도구 선택·호출 | 1~5s |
 
-**핵심:** Guardrail이 먼저 동작하므로 "오늘 날씨 어때?" 같은 질문은 벡터 검색·LLM 호출 없이 즉시 차단됨.
+Guardrail이 먼저 동작하므로 "오늘 날씨 어때?" 같은 질문은 벡터 검색이나 LLM 호출 없이 즉시 차단됨.
 
-### 전략 B. Scalable Tool Architecture — 도구 추가가 운영 부담이 되지 않도록
+### 2-2. Tool Card로 검색 정확도를 높임
 
-```
-새 Tool 추가 → Tool Card 작성 → 임베딩 자동 생성 → 즉시 검색 대상에 포함
+LLM 도구 description은 보통 한두 줄이라, 유사 도구끼리 벡터가 거의 같아져서 구분이 어려움.
+이를 해결하기 위해 도구마다 **ToolCard**를 작성하여 임베딩 표면을 확장함.
+
+```python
+ToolCard(
+    name="premium_estimate",
+    purpose="나이·성별을 입력해 특정 상품의 예상 월 보험료를 산출한다.",
+    when_to_use=("보험료 얼마야?", "40세 남성 보험료 계산해줘"),
+    when_not_to_use=("납입 플랜이 궁금하다 → plan_options 사용",),
+    tags=("보험료", "산출"),
+)
 ```
 
-| 방식 | 절차 | 서버 재시작 |
-|------|------|-------------|
-| 정적 등록 | Tool 함수 + ToolCard → 서버 재시작 | 필요 |
-| 런타임 핫리로드 | Tool 함수 + API 호출 (`POST /api/tools/reload-module/{module}`) | **불필요** |
+| 필드 | 임베딩 포함 | 역할 |
+|------|:-----------:|------|
+| `purpose` | O | 도구의 핵심 기능을 한 문장으로 설명 |
+| `when_to_use` | O | 실제 사용자 발화 예시 → 검색 표면 확장 |
+| `tags` | O | 도메인 키워드 → 클러스터링 보조 |
+| `when_not_to_use` | **X** | 혼동 가능한 도구 안내 → LLM 최종 선택 시에만 사용 |
 
-ToolRegistry가 동적 관리하고, 변경 시 ChromaDB 재인덱싱을 자동 트리거함.
+`when_not_to_use`를 임베딩에서 제외하는 이유: 타 도구 이름("premium_estimate 사용")이 포함되면 벡터가 오염됨.
+Tool-DE [(Lu et al., 2025)](https://arxiv.org/abs/2510.22670) ablation에서도 negative example 포함 시 성능이 저하됨.
 
-### 전략 C. Validation — 감이 아니라 숫자로 판단
+각 필드는 **별도 문서**로 ChromaDB에 인덱싱하고, 검색 시 tool별 max score로 집계함.
+단일 벡터로 합치면 여러 예시의 평균으로 희석되지만, 이 방식은 ColBERT 등 multi-vector 모델과 동일한 원리로 희석 없이 정확한 매칭이 가능함 [(Pinecone)](https://www.pinecone.io/blog/cascading-retrieval-with-multi-vector-representations/).
 
-`scripts/eval_tool_recall.py`로 Recall@k, MRR, Hit@1을 정량 측정함.
+### 2-3. 코드 변경 없이 운영 중 튜닝
 
-```bash
-python -m scripts.eval_tool_recall --compare    # k=1,3,5,7,10 비교표
-python -m scripts.eval_tool_recall --verbose     # 오판 사례 상세
+Admin Dashboard(`/admin/tools`)에서 ToolCard를 수정하면 즉시 챗봇에 반영됨.
+배치 Recall 평가와 LLM 분석을 내장하여, 수정 전후 성능 차이를 바로 확인할 수 있음.
+
+```
+Admin UI에서 when_to_use 문장 수정
+    ↓  [저장 & 반영] 클릭
+① 메모리 REGISTRY 업데이트 + ChromaDB 재인덱싱
+② data/toolcard_overrides.json 저장 (서버 재시작 후에도 유지)
+③ 버전 이력 기록 → 문제 시 롤백 가능
 ```
 
 ---
@@ -86,26 +103,22 @@ python -m scripts.eval_tool_recall --verbose     # 오판 사례 상세
 | 지표 | k=1 | k=3 | **k=5 (운영)** | k=7 | k=10 |
 |------|-----|-----|----------------|-----|------|
 | **Recall@k** | 96.9% | 100% | **100%** | 100% | 100% |
-| **Hit@1** | 96.9% | 96.9% | **96.9%** | 96.9% | 96.9% |
-| **MRR** | 0.969 | 0.984 | **0.984** | 0.984 | 0.984 |
-| **No-Call Acc** | 80.0% | 80.0% | **80.0%** | 80.0% | 80.0% |
-
-| 점수 분포 (k=10) | min | avg | max |
-|-------------------|-----|-----|-----|
-| Tool-Call top-1 | 0.867 | 0.921 | 0.947 |
-| No-Call top-1 | 0.831 | 0.853 | 0.877 |
+| **Hit@1** | 96.9% | — | **96.9%** | — | 96.9% |
+| **MRR** | 0.969 | 0.984 | **0.984** | — | 0.984 |
+| **No-Call Acc** | — | — | **80.0%** | — | 80.0% |
 
-- k=1 미탐 2건: 유사 도구 간 경계 사례 (coverage_detail ↔ benefit_amount, renewal_projection ↔ renewal_notice)
-- k=3부터 Recall 100%. 64개 tool-call 쿼리 전부 Top-3 안에 정답 도구 포함
-- no-call 오판 3건: 비보험 질문이지만 유사도 0.86~0.88로 경계에 걸림. Guardrail(L1+L2)에서 사전 차단되므로 실운영에서는 Tool Search 미도달
+- k=1 미탐 2건: 유사 도구 경계 사례 (coverage_detail ↔ benefit_amount, renewal_projection ↔ renewal_notice)
+- k=3부터 Recall 100% — 64개 tool-call 쿼리가 전부 Top-3 안에 포함됨
+- no-call 오판 3건: 유사도 0.86~0.88로 경계에 걸리지만, Guardrail에서 사전 차단되므로 실운영에서는 Tool Search에 도달하지 않음
 
-**결론:** 54개 → 5개로 90% 축소해도 **Recall@5 = 100%, MRR = 0.98**. 정확도를 유지하면서 비용과 지연을 동시에 줄임.
+**54개 → 5개로 90% 축소해도 Recall@5 = 100%, MRR = 0.98.
+정확도를 유지하면서 비용과 지연을 동시에 줄임.**
 
 ---
 
 ## 4. 구현 상세
 
-### 4-1. 5노드 파이프라인 (LangGraph)
+### 4-1. LangGraph 5노드 파이프라인
 
 ```
 START → [input_guardrail] → [query_rewriter] → [agent ↔ tools] → [output_guardrail] → END
@@ -114,78 +127,71 @@ START → [input_guardrail] → [query_rewriter] → [agent ↔ tools] → [outp
 | 노드 | 역할 | 소요 시간 |
 |------|------|-----------|
 | input_guardrail | 정규식(L1) + 임베딩(L2)으로 이상 요청 차단 | <5ms |
-| query_rewriter | 짧은 후속질문을 이전 맥락으로 재작성 | 0~1s |
-| agent | ChromaDB Top-K 필터링 → LLM 호출 | 1~5s |
-| tools | ToolRegistry 동적 디스패치 | 10~100ms |
+| query_rewriter | "그거 얼마야?" 같은 후속질문을 이전 맥락으로 재작성 | 0~1s |
+| agent | ChromaDB Top-K 검색 → LLM 도구 호출 | 1~5s |
+| tools | ToolRegistry 동적 디스패치 → 도구 실행 | 10~100ms |
 | output_guardrail | PII·금칙어 검사 + 면책 문구 자동 추가 | <2ms |
 
-### 4-2. 쿼리 재작성 (Query Rewriter)
+쿼리 재작성은 Advanced RAG 핵심 기법인 Query Transformation에 해당함 [(참고)](https://www.promptingguide.ai/research/rag).
+짧은 후속질문의 벡터 검색 정확도를 보완하는 역할임.
 
-"그거 얼마야?", "그건?" 같은 짧은 후속질문은 벡터 검색 정확도가 떨어짐. 이전 대화 맥락을 참조해 구체적 쿼리로 재작성하여 Tool Search 정확도를 보완함. Query Transformation은 Advanced RAG 핵심 기법 [(참고)](https://www.promptingguide.ai/research/rag).
+### 4-2. 상품공시실 PDF RAG
 
-### 4-3. 상품공시실 PDF 기반 RAG
+보험 상품공시실에서 12개 상품요약서 + 표준약관 + 회사 정보를 수집함.
+PyMuPDF로 텍스트 추출 → 500자 청크 → ChromaDB 인제스트(~1,400 벡터).
+도구 데이터에 없는 약관 조항·면책 규정을 RAG가 보완함.
 
-보험 상품공시실에서 12개 상품요약서 PDF + 표준약관 + 회사 정보를 수집. PyMuPDF로 텍스트 추출 → 500자 청크 → ChromaDB 인제스트(~1,400 벡터). 도구 데이터에 없는 약관 조항·면책 규정을 RAG가 보완함.
+### 4-3. LLM 연동
 
-### 4-4. Agentic 시스템 프롬프트
-
-12개 상품 목록이 PRODUCTS 딕셔너리에서 동적 반영. 새 상품 추가 시 프롬프트가 자동 업데이트됨. 도구 체이닝 규칙("상품명만 알면 product_search → 해당 도구 순서")도 포함하여 LLM이 자율적으로 연쇄 호출함.
-
-### 4-5. LLM 사고과정 필터링
-
-Qwen3의 `<think>...</think>` 블록을 스트리밍 중 실시간 필터링. 사용자에게는 최종 답변만 노출, SSE 이벤트로 파이프라인 진행 상태를 표시하여 체감 지연을 줄임.
-
-### 4-6. 도구 레벨 입력 가드
-
-보험료 산출·가입 심사 등 나이/성별이 필수인 도구는, 사용자가 제공하지 않은 정보를 추측하지 않음. 도구가 `needs_user_input`을 반환하면 LLM이 해당 정보를 질문함.
-
-### 4-7. 상품 카탈로그 UI
-
-헤더의 "상품 목록" 버튼 또는 페이지 접속 시 자동으로 12개 상품 카탈로그 모달이 표시됨. 카테고리·갱신유형·간편심사 태그로 필터링하고, 상품 클릭 시 보장 내용 질문이 자동 세팅됨. 모바일 반응형 대응.
+| 항목 | 설명 |
+|------|------|
+| 시스템 프롬프트 | 12개 상품 목록이 PRODUCTS 딕셔너리에서 동적 반영됨. 도구 체이닝 규칙도 포함 |
+| 사고과정 필터링 | Qwen3 `<think>` 블록을 스트리밍 중 실시간 필터링. 사용자에게 최종 답변만 노출 |
+| 도구 레벨 가드 | 나이/성별 등 필수값 미제공 시 `needs_user_input` 반환 → LLM이 되묻는 구조 |
 
-### 4-8. 서빙: 두 가지 인터페이스
+### 4-4. 서빙
 
 | 방식 | 설명 | 대상 |
 |------|------|------|
-| FastAPI (REST/SSE) | 웹 Chat UI + REST API | 일반 사용자 |
+| FastAPI (REST/SSE) | 웹 Chat UI + REST API + Admin Dashboard | 일반 사용자·운영자 |
 | MCP Server (SSE/stdio) | 도구 54 + 리소스 17 + 프롬프트 8 노출 | Claude Desktop, Cursor 등 |
 
-MCP Inspector UI로 도구 입출력, 리소스 조회, 프롬프트 렌더링을 브라우저에서 직접 테스트 가능.
-
 ```bash
-python run_mcp.py --inspect
+python run.py                  # FastAPI → http://localhost:8080
+python run_mcp.py              # MCP Server
+python run_mcp.py --inspect    # MCP Inspector UI → http://localhost:5173
 ```
 
-### 4-9. 도구 추가 체크리스트
+---
 
-새 도구를 추가할 때 아래 4단계를 순서대로 수행한다.
+## 5. 운영
 
-**① 도구 함수 작성** — `app/tools/` 아래 해당 모듈에 `@tool` 함수를 추가한다. 함수의 `tool.name`이 이후 모든 연동의 키가 된다.
+### 5-1. 도구 추가 체크리스트
 
-**② ToolCard 등록** — `app/tool_search/tool_cards.py`의 `_CARDS` 리스트에 카드를 추가한다.
+새 도구를 추가할 때 아래 순서를 따름.
 
-| 필드 | 규칙 | 예시 |
-|------|------|------|
-| `name` | tool.name과 **정확히** 일치 | `"premium_estimate"` |
-| `purpose` | 한 문장으로 명확하게 | `"예상 월 보험료를 산출한다."` |
-| `when_to_use` | **실제 사용자 발화** 패턴으로 작성 | `("보험료 얼마야?", "40세 남성 보험료")` |
-| `when_not_to_use` | 혼동 도구명을 `→ tool_name 사용` 형식으로 명시 | `("납입 플랜 → plan_options 사용",)` |
-| `tags` | 도메인 키워드 (필터링용) | `("보험료", "산출")` |
+**① 도구 함수 작성** — `app/tools/` 아래 해당 모듈에 `@tool` 함수를 추가함. `tool.name`이 이후 모든 연동의 키가 됨.
 
-> `when_to_use`가 다른 도구 카드와 **중복되면 임베딩이 충돌**한다. `validate_duplicate_when_to_use()`가 자동 검출하므로 평가 스크립트를 반드시 실행할 것.
+**② ToolCard 등록** — `app/tool_search/tool_cards.py`의 `_CARDS` 리스트에 카드를 추가함.
 
-ToolCard 설계는 Tool Document Expansion [(Tool-DE, Lu et al. 2025)](https://arxiv.org/abs/2510.22670) 연구에 기반한다. purpose·when_to_use·tags로 임베딩 표면을 확장하고, when_not_to_use는 LLM description에만 주입하여 벡터 오염을 방지한다. Re-Invoke [(Google, EMNLP 2024)](https://arxiv.org/abs/2408.01875)의 합성 쿼리 전략과 동일 원리이며, ablation 결과 negative example을 임베딩에서 제외할 때 NDCG가 가장 높았다.
+| 필드 | 규칙 |
+|------|------|
+| `name` | tool.name과 정확히 일치해야 함 |
+| `purpose` | 한 문장으로 도구 기능을 설명 |
+| `when_to_use` | 실제 사용자 발화 패턴으로 작성 |
+| `when_not_to_use` | 혼동 도구를 `→ tool_name 사용` 형식으로 명시 |
+| `tags` | 도메인 키워드 (필터링용) |
+
+> `when_to_use`가 다른 카드와 중복되면 임베딩이 충돌함. `validate_duplicate_when_to_use()`가 자동 검출하므로 평가 시 확인할 것.
 
-**③ ��동 쌍 관리** — 기능이 유사한 도구가 있으면 양방향으로 처리한다.
+**③ 혼동 쌍 관리** — 기능이 유사한 도구가 있으면 양방향으로 처리함.
 
 ```
-1. 새 카드의 when_not_to_use에 기존 유사 도구 언급
-2. 기존 유사 도구의 when_not_to_use에 새 도구 언급
+1. 새 카드 when_not_to_use에 기존 유사 도구 언급
+2. 기존 유사 도구 when_not_to_use에 새 도구 언급
 3. CONFUSION_PAIRS 리스트에 (기존, 신규) 쌍 등록
 ```
 
-`validate_confusion_pairs()`가 양방향 누락을 검출한다. 유사 도구 간 명시적 cross-reference는 ToolBench [(ICLR 2024)](https://arxiv.org/abs/2307.16789)에서 도구 수 증가 시 정확도 저하를 방지하는 핵심 전략으로 제시되었다.
-
 **④ 검증**
 
 ```bash
@@ -193,65 +199,44 @@ python -m scripts.eval_tool_recall --compare   # Recall@k, MRR 확인
 python -m scripts.eval_tool_recall --verbose    # 오판 사례 상세
 ```
 
-**연동 자동/수동 요약:**
-
-| 연동 지점 | 자동/수동 | 설명 |
+| 연동 지점 | 자동/수동 | 비고 |
 |-----------|:---------:|------|
-| ChromaDB 임베딩 | 자동 | 서버 재시작 시 해시 비교 → 변경 감지되면 재인덱싱 |
-| LLM tool description | 자동 | `when_not_to_use`가 bind_tools() 시 description에 주입 |
-| 평가 스크립트 | 자동 | 카드 정합성 검증이 평가 시 자동 실행 |
-| 도구 함수 (`app/tools/`) | **수동** | 카드만 있고 실제 함수가 없으면 동작하지 않음 |
-| `CONFUSION_PAIRS` | **수동** | 유사 도구가 있을 경우 반드시 등록 |
-
-> ToolCard가 없는 도구는 `tool.description` 단일 문서로 fallback 되어 동작은 하지만 검색 정확도가 낮다. 서버 로그에 `"ToolCard 없는 도구 N개"` 경고가 출력된다.
+| ChromaDB 임베딩 | 자동 | 서버 시작 시 해시 비교 → 변경분만 재인덱싱 |
+| LLM tool description | 자동 | `when_not_to_use`가 description에 자동 주입 |
+| 도구 함수 | **수동** | 카드만 있고 함수가 없으면 동작하지 않음 |
+| `CONFUSION_PAIRS` | **수동** | 유사 도구 존재 시 반드시 등록 |
 
-### 4-10. 런타임 도구 관리 API
+> ToolCard가 없는 도구는 `tool.description` 단일 문서로 fallback 됨. 동작은 하지만 검색 정확도가 낮음.
 
-서버 재시작 없이 도구를 추가·제거·확인할 수 있는 REST API를 제공한다. ToolRegistry [(동적 레지스트리 패턴)](https://python.langchain.com/docs/how_to/tools_runtime/)가 변경을 감지하고 ChromaDB 재인덱싱을 자동 트리거한다.
-
-```bash
-# 전체 도구 목록 조회
-curl http://localhost:8080/api/tools
+### 5-2. Admin Dashboard
 
-# 특정 도구 런타임 해제 (ChromaDB 벡터도 자동 삭제)
-curl -X DELETE http://localhost:8080/api/tools/premium_estimate
+CLI 대신 브라우저(`/admin/tools`)에서 도구 레지스트리를 관리하는 웹 UI임.
+FastAPI 앱에 내장되어 별도 서버 없이 HF Spaces 등 배포 환경에서도 동작함.
 
-# 모듈 단위 핫리로드 (수정한 도구 코드를 서버 재시작 없이 반영)
-curl -X POST http://localhost:8080/api/tools/reload-module/premium
-```
+| 기능 | 설명 |
+|------|------|
+| 대시보드 | 도구 수, ChromaDB 벡터 수, Registry 버전, 상태 모니터링 |
+| ToolCard 편집 | purpose, when_to_use, when_not_to_use, tags 수정 → 즉시 반영 |
+| 버전 이력 | 변경 이력 조회, Diff 비교, 특정 버전으로 롤백 |
+| 퀵 테스트 | 실시간 쿼리 검색, 배치 Recall 평가, LLM 실패 분석 |
+| 도구 해제 | 확인 모달 → DELETE → ChromaDB 벡터 즉시 삭제 |
+| 모듈 핫리로드 | 8개 모듈 선택 → 코드 변경분 서버 재시작 없이 반영 |
 
-| API | 메서드 | 기능 |
-|-----|--------|------|
-| `/api/tools` | GET | 전체 도구 목록 + 메타데이터 |
-| `/api/tools/{tool_name}` | DELETE | 도구 해제 + ChromaDB 벡터 삭제 |
-| `/api/tools/reload-module/{module}` | POST | 모듈 `importlib.reload()` → 도구 재등록 |
+퀵 테스트 탭에서 수정 전후 Recall@k를 비교하고, 실패 쿼리에 대해 LLM이 ToolCard 개선안을 제안하므로 **코드 변경 없이** 검색 정확도를 튜닝할 수 있음.
 
-MCP Inspector에서도 도구 입출력을 브라우저에서 직접 테스트할 수 있다.
+### 5-3. 런타임 API
 
 ```bash
-python run_mcp.py --inspect    # Inspector UI → http://localhost:5173
+curl http://localhost:8080/api/tools                              # 전체 도구 목록
+curl -X DELETE http://localhost:8080/api/tools/premium_estimate    # 도구 해제
+curl -X POST http://localhost:8080/api/tools/reload-module/premium # 모듈 핫리로드
 ```
 
-### 4-11. Tool Admin Dashboard
-
-CLI 대신 브라우저에서 도구 레지스트리를 관리하는 웹 UI(`/admin/tools`)를 제공한다. 별도 서버·포트 없이 기존 FastAPI 앱에 내장되어 HF Spaces 등 배포 환경에서도 동작함.
-
-| 기능 | 설명 |
-|------|------|
-| 대시보드 | 등록 ��구 수, ChromaDB 벡터 수, Registry 버전, 서비스 상태 (10초 자동 갱신) |
-| 도구 테이블 | 이름, purpose, 태그, when_to_use 예시, ToolCard 유무 |
-| 도구 해제 | 확인 모달 → DELETE API → ChromaDB 벡터 즉시 삭제 |
-| 모듈 핫리로드 | 8개 모듈 선택 → register_many() → 재인덱싱 1회 |
-| 상세보기 | purpose, module, tags, when_to_use, when_not_to_use 전체 표시 |
-| 검색 | 이름·설명·태그 실시간 필터링 |
-
-챗봇 UI 헤더의 **Tool Admin** 버튼 또는 `/admin/tools` 직접 접속으로 사용한다.
-
-> **MCP Inspector와의 차이:** MCP Inspector는 MCP 프로토콜 레벨의 디버깅 도구(도구 입출력 테스트)이고, Tool Admin은 애플리케이션 레벨의 운영 도구(도구 해제·복원, 임베딩 상태 모니터링)이다. 개발 시에는 Inspector, 운영 시에는 Admin Dashboard를 사용한다.
+ToolRegistry가 변경을 감지하고 ChromaDB 재인덱싱을 자동 트리거함.
 
 ---
 
-## 5. 기술 선택 근거
+## 6. 기술 선택 근거
 
 ### ChromaDB
 
@@ -262,54 +247,35 @@ CLI 대신 브라우저에서 도구 레지스트리를 관리하는 웹 UI(`/ad
 | 실시간 upsert | rebuild 필요 | O | **O** |
 | 인프라 | 없음 | Docker 3개 | **pip 1줄** |
 
-벡터 ~1,800개 규모에서 Milvus는 오버엔지니어링, FAISS는 메타데이터 필터링 미지원. 10M 벡터 미만 프로젝트에서 ChromaDB 권장 [(Firecrawl)](https://www.firecrawl.dev/blog/best-vector-databases) [(DataCamp)](https://www.datacamp.com/blog/the-top-5-vector-databases).
+~1,800 벡터 규모에서 Milvus는 오버엔지니어링, FAISS는 메타데이터 필터링 미지원.
+10M 벡터 미만에서 ChromaDB 권장 [(Firecrawl)](https://www.firecrawl.dev/blog/best-vector-databases) [(DataCamp)](https://www.datacamp.com/blog/the-top-5-vector-databases).
 
 ### multilingual-e5-large
 
-[Kor-IR 벤치마크](https://github.com/Atipico1/Kor-IR)에서 오픈소스 최상위(NDCG@10 = 80.35). Mr. TyDi 한국어 MRR@10 = 61.6으로 e5-base(55.8) 대비 +10% [(모델 카드)](https://huggingface.co/intfloat/multilingual-e5-large). 비대칭 검색 시 "query: " / "passage: " 프리픽스 필수 [(E5 논문)](https://arxiv.org/abs/2402.05672). 로컬 추론(~10ms/쿼리)으로 외부 API 미의존.
-
-### Multi-Vector 인덱싱
-
-도구 하나를 단일 벡터로 임베딩하면 여러 사용 예시의 평균으로 벡터가 희석됨. purpose + when_to_use를 별도 문서로 인덱싱하고, 검색 시 tool별 max score로 집계하여 희석 없이 정확한 매칭을 달성. ColBERT 등 multi-vector 모델이 single-vector 대비 정확도가 높은 것과 동일 원리 [(Pinecone)](https://www.pinecone.io/blog/cascading-retrieval-with-multi-vector-representations/).
+[Kor-IR 벤치마크](https://github.com/Atipico1/Kor-IR) 오픈소스 최상위(NDCG@10 = 80.35).
+Mr. TyDi 한국어 MRR@10 = 61.6으로 e5-base(55.8) 대비 +10% [(모델 카드)](https://huggingface.co/intfloat/multilingual-e5-large).
+비대칭 검색 시 `"query: "` / `"passage: "` 프리픽스 필수 [(논문)](https://arxiv.org/abs/2402.05672).
+로컬 추론(~10ms/쿼리)으로 외부 API에 의존하지 않음.
 
-### Tool Card (Tool Document Expansion)
+### Tool Card 학술 근거
 
-LLM 도구 description은 보통 한두 줄. 이 짧은 텍스트만 임베딩하면 유사 도구 간 벡터가 거의 같아져 검색 정확도가 떨어짐.
-
-```python
-ToolCard(
-    name="premium_estimate",
-    purpose="나이·성별을 입력해 특정 상품의 예상 월 보험료를 산출한다.",
-    when_to_use=("보험료 얼마야?", "40세 남성 보험료 계산해줘"),
-    when_not_to_use=("납입 플랜이 궁금하다 → plan_options 사용",),
-    tags=("보험료", "산출"),
-)
-```
-
-| ToolCard 필드 | 학술 대응 | 임베딩 포함 | 역할 |
-|---------------|-----------|:-----------:|------|
-| `purpose` | Tool-DE의 function_description | O | 도구 핵심 기능 |
-| `when_to_use` | Re-Invoke의 synthetic queries | O | 검색 표면 확장 |
-| `tags` | Tool-DE의 tags | O | 도메인 클러스터링 |
-| `when_not_to_use` | Tool-DE의 limitations | X | LLM 최종 선택 시 혼동 방지 |
-
-when_not_to_use를 임베딩에서 제외한 이유: 타 도구 어휘("premium_estimate 사용")가 포함되어 벡터가 오염됨. Tool-DE ablation에서도 negative example 포함 시 성능 저하 확인.
-
-**학술 근거:**
-- **Tool-DE** (Lu et al., 2025) — 도구 문서 확장으로 NDCG@10 +6~7ppt, Recall@10 +10ppt 개선 [(논문)](https://arxiv.org/abs/2510.22670)
-- **Re-Invoke** (Google, EMNLP 2024) — 합성 쿼리 생성으로 nDCG@5 유의미 향상 [(논문)](https://arxiv.org/abs/2408.01875)
-- **RAG-MCP** (WRITER, 2025) — 메타데이터 기반 인덱싱 → 토큰 50%+ 절감 [(블로그)](https://writer.com/engineering/rag-mcp/)
+| 출처 | 핵심 기여 |
+|------|-----------|
+| [Tool-DE (Lu et al., 2025)](https://arxiv.org/abs/2510.22670) | 도구 문서 확장으로 NDCG@10 +6~7ppt, Recall@10 +10ppt |
+| [Re-Invoke (Google, EMNLP 2024)](https://arxiv.org/abs/2408.01875) | 합성 쿼리 생성으로 nDCG@5 유의미 향상 |
+| [ToolBench (ICLR 2024)](https://arxiv.org/abs/2307.16789) | 도구 수 증가 시 cross-reference가 정확도 저하를 방지 |
+| [RAG-MCP (WRITER, 2025)](https://writer.com/engineering/rag-mcp/) | 메타데이터 기반 인덱싱 → 토큰 50%+ 절감 |
 
 ---
 
-## 6. 알려진 한계 및 고도화 방향
+## 7. 알려진 한계 및 고도화 방향
 
-| 한계 | 현상 | 고도화 방향 |
-|------|------|-------------|
-| product_search when_to_use 오버핏 | 타 도구 영역 발화 10개가 임베딩을 희석 | 순수 상품 검색 발화만 유지 |
-| 유사 도구 cross-reference 누락 | renewal_projection ↔ renewal_notice 등 양방향 가이드 부재 | when_not_to_use 양방향 보완 |
-| 수동 작성 한계 | 54개 × 7개 = ~380개 when_to_use 수동 관리 | Re-Invoke 방식 LLM 합성 쿼리 자동 생성 |
-| 정적 no-call 임계값 | Tool-Call min(0.867)과 No-Call max(0.877)이 겹침 | Reranker 2단계 도입 (Tool-Rank) |
+| 한계 | 현상 | 방향 |
+|------|------|------|
+| when_to_use 오버핏 | product_search에 타 도구 영역 발화가 임베딩을 희석함 | 순수 상품 검색 발화만 유지 |
+| cross-reference 누락 | renewal_projection ↔ renewal_notice 양방향 가이드 부재 | when_not_to_use 양방향 보완 |
+| 수동 작성 한계 | 54개 × ~7개 = ~380개 when_to_use를 수동 관리 중 | Re-Invoke 방식 LLM 합성 쿼리 자동 생성 |
+| 정적 no-call 임계값 | tool-call min(0.867)과 no-call max(0.877)이 겹침 | Reranker 2단계 도입 |
 
 ---
 
@@ -355,7 +321,8 @@ app/
 │   └── data.py             #   12개 상품 데이터 + 시스템 프롬프트
 ├── tool_search/            # ChromaDB 멀티벡터 라우팅
 │   ├── embedder.py         #   임베딩 + Top-K 검색
-│   └── tool_cards.py       #   54개 ToolCard
+│   ├── tool_cards.py       #   54개 ToolCard
+│   └── toolcard_store.py   #   ToolCard JSON 영속화 + 버전 이력
 ├── rag/                    # 상품공시실 PDF RAG
 │   ├── retriever.py        #   인제스트 + 검색
 │   └── splitter.py         #   한국어 문장경계 청크 분할

app/main.py

@@ -12,6 +12,9 @@ Endpoints:
   DELETE /api/tools/{tool_name}           — 도구 런타임 해제
   POST   /api/tools/reload-module/{mod}   — 모듈 핫리로드
   GET    /admin/tools                     — Tool Admin UI
+  POST   /api/admin/eval/search           — 단일 쿼리 검색 테스트
+  POST   /api/admin/eval/batch/{name}     — ToolCard 배치 Recall 평가
+  POST   /api/admin/eval/judge            — LLM-as-Judge 실패 분석
 """
 
 from __future__ import annotations
@@ -80,7 +83,16 @@ async def lifespan(app: FastAPI):
     get_graph()
     logger.info("LangGraph compiled")
 
-    # 4. Tool embeddings 초기 인덱싱
+    # 4. ToolCard JSON override 로딩
+    try:
+        from app.tool_search.tool_cards import apply_overrides
+        n = apply_overrides()
+        if n:
+            logger.info("Applied %d ToolCard overrides from JSON", n)
+    except Exception as e:
+        logger.warning("ToolCard override loading skipped: %s", e)
+
+    # 5. Tool embeddings 초기 인덱싱
     try:
         from app.tool_search.embedder import get_tool_search
         searcher = get_tool_search()
@@ -521,6 +533,244 @@ async def admin_list_tools():
     return {"count": len(result), "registry_version": registry.version, "tools": result}
 
 
+# ── ToolCard CRUD API ─────────────────────────────────────────────────────────
+
+def _get_store():
+    from app.tool_search.toolcard_store import get_toolcard_store
+    return get_toolcard_store(on_publish=_on_card_publish)
+
+
+def _on_card_publish(card) -> None:
+    """ToolCard publish 후 ChromaDB 재인덱싱 트리거."""
+    try:
+        from app.tool_search.embedder import get_tool_search
+        registry = get_tool_registry()
+        get_tool_search().index_tools(registry.get_all())
+        logger.info("ChromaDB re-indexed after ToolCard publish (%s)", card.name)
+    except Exception as e:
+        logger.warning("ChromaDB re-index after card publish failed: %s", e)
+
+
+@app.get("/api/admin/toolcards/{name}")
+async def get_toolcard(name: str):
+    """ToolCard 상세 — published/draft/code 원본 + 상태."""
+    from app.tool_search.tool_cards import CODE_REGISTRY, REGISTRY
+
+    store = _get_store()
+    status = store.get_status(name)
+    draft = store.get_draft(name)
+    effective = REGISTRY.get(name)
+    code_card = CODE_REGISTRY.get(name)
+
+    return {
+        **status,
+        "effective": {
+            "purpose": effective.purpose,
+            "when_to_use": list(effective.when_to_use),
+            "when_not_to_use": list(effective.when_not_to_use),
+            "tags": list(effective.tags),
+        } if effective else None,
+        "code_original": {
+            "purpose": code_card.purpose,
+            "when_to_use": list(code_card.when_to_use),
+            "when_not_to_use": list(code_card.when_not_to_use),
+            "tags": list(code_card.tags),
+        } if code_card else None,
+        "draft": draft,
+    }
+
+
+@app.put("/api/admin/toolcards/{name}/draft")
+async def save_toolcard_draft(name: str, request: Request):
+    """ToolCard draft 저장. 챗봇에는 미반영."""
+    body = await request.json()
+    store = _get_store()
+    draft = store.save_draft(name, body)
+    return {"status": "draft_saved", "name": name, "draft": draft}
+
+
+@app.post("/api/admin/toolcards/{name}/publish")
+async def publish_toolcard(name: str, request: Request):
+    """Draft → Published. 메모리 + ChromaDB 즉시 반영."""
+    body = await request.json()
+    note = body.get("note", "")
+    store = _get_store()
+
+    has_draft = store.get_draft(name)
+    if not has_draft:
+        data = body.get("data")
+        if not data:
+            raise HTTPException(400, "No draft exists and no data provided")
+        store.save_draft(name, data)
+
+    card = store.publish(name, note)
+    status = store.get_status(name)
+    return {"status": "published", "name": name, "version": status["version"]}
+
+
+@app.post("/api/admin/toolcards/{name}/rollback")
+async def rollback_toolcard(name: str, request: Request):
+    """특정 버전으로 롤백."""
+    body = await request.json()
+    target_version = body.get("version")
+    if not target_version:
+        raise HTTPException(400, "version is required")
+    store = _get_store()
+    card = store.rollback(name, int(target_version))
+    status = store.get_status(name)
+    return {"status": "rolled_back", "name": name, "version": status["version"]}
+
+
+@app.get("/api/admin/toolcards/{name}/history")
+async def toolcard_history(name: str):
+    """버전 이력 조회."""
+    store = _get_store()
+    history = store.get_history(name)
+    return {"name": name, "history": history}
+
+
+@app.delete("/api/admin/toolcards/{name}/override")
+async def reset_toolcard(name: str):
+    """Override 제거 → 코드 원본 카드로 복원."""
+    store = _get_store()
+    card = store.reset_to_code(name)
+    return {"status": "reset_to_code", "name": name, "has_code_card": card is not None}
+
+
+@app.post("/api/admin/toolcards/{name}/discard-draft")
+async def discard_toolcard_draft(name: str):
+    """Draft 폐기."""
+    store = _get_store()
+    store.discard_draft(name)
+    return {"status": "draft_discarded", "name": name}
+
+
+# ── Quick Eval API ────────────────────────────────────────────────────────────
+
+@app.post("/api/admin/eval/search")
+async def eval_search(request: Request):
+    """단일 쿼리 → top-k 검색 결과 반환. 실시간 라우팅 확인용."""
+    body = await request.json()
+    query = body.get("query", "").strip()
+    top_k = body.get("top_k", 5)
+    if not query:
+        raise HTTPException(400, "query is required")
+
+    from app.tool_search.embedder import get_tool_search
+    candidates = get_tool_search().search(query, top_k=top_k)
+    return {
+        "query": query,
+        "results": [
+            {"name": c.name, "score": c.score, "description": c.description[:80]}
+            for c in candidates
+        ],
+    }
+
+
+@app.post("/api/admin/eval/batch/{tool_name}")
+async def eval_batch(tool_name: str):
+    """ToolCard의 when_to_use 전체를 검색하여 Recall@1/3/5 산출."""
+    from app.tool_search.tool_cards import REGISTRY
+    from app.tool_search.embedder import get_tool_search
+
+    card = REGISTRY.get(tool_name)
+    if not card or not card.when_to_use:
+        raise HTTPException(404, f"No ToolCard or when_to_use for '{tool_name}'")
+
+    searcher = get_tool_search()
+    details = []
+    for query in card.when_to_use:
+        hits = searcher.search(query, top_k=5)
+        rank = next(
+            (i + 1 for i, c in enumerate(hits) if c.name == tool_name), None
+        )
+        details.append({
+            "query": query,
+            "rank": rank,
+            "pass_at_3": rank is not None and rank <= 3,
+            "top_hits": [
+                {"name": c.name, "score": c.score} for c in hits[:5]
+            ],
+        })
+
+    n = len(details)
+    return {
+        "tool_name": tool_name,
+        "total": n,
+        "recall_at_1": round(sum(1 for d in details if d["rank"] == 1) / n, 4) if n else 0,
+        "recall_at_3": round(sum(1 for d in details if d["pass_at_3"]) / n, 4) if n else 0,
+        "recall_at_5": round(sum(1 for d in details if d["rank"] and d["rank"] <= 5) / n, 4) if n else 0,
+        "details": details,
+    }
+
+
+@app.post("/api/admin/eval/judge")
+async def eval_judge(request: Request):
+    """LLM-as-Judge: 실패 케이스를 분석하고 ToolCard 개선안을 제안."""
+    body = await request.json()
+    tool_name = body.get("tool_name", "")
+    failures = body.get("failures", [])
+
+    if not tool_name or not failures:
+        raise HTTPException(400, "tool_name and failures are required")
+
+    from app.tool_search.tool_cards import REGISTRY
+    from app.llm import get_llm
+
+    card = REGISTRY.get(tool_name)
+    card_info = ""
+    if card:
+        card_info = (
+            f"purpose: {card.purpose}\n"
+            f"when_to_use: {list(card.when_to_use)}\n"
+            f"when_not_to_use: {list(card.when_not_to_use)}\n"
+            f"tags: {list(card.tags)}"
+        )
+
+    failure_lines = []
+    for f in failures[:10]:
+        top_str = ", ".join(
+            f"{h['name']}({h['score']})" for h in f.get("top_hits", [])[:3]
+        )
+        failure_lines.append(
+            f"  쿼리: \"{f['query']}\"  → 상위결과: [{top_str}]  "
+            f"(expected: {tool_name}, rank: {f.get('rank', 'N/A')})"
+        )
+
+    prompt = f"""당신은 Tool Routing 전문가입니다. 아래 도구의 ToolCard 정보와, 해당 도구로 라우팅되어야 했지만 실패한 쿼리들을 분석해주세요.
+
+## 도구: {tool_name}
+{card_info}
+
+## 실패 케이스 ({len(failure_lines)}건)
+{chr(10).join(failure_lines)}
+
+## 요청사항
+1. 각 실패 쿼리가 왜 다른 도구로 라우팅되었는지 원인을 분석하세요.
+2. ToolCard를 어떻게 수정하면 이 쿼리들이 올바르게 라우팅될지 구체적으로 제안하세요.
+   - 추가할 when_to_use 예시
+   - 추가할 tags
+   - 수정할 purpose
+3. 주의: when_to_use에 이미 있는 쿼리와 너무 유사한 문장은 효과가 적습니다. 다양한 표현을 제안하세요.
+
+한국어로 간결하게 답변하세요."""
+
+    llm = get_llm()
+    try:
+        result = await llm.ainvoke(prompt)
+        analysis = result.content if hasattr(result, "content") else str(result)
+        analysis = _strip_think(analysis)
+    except Exception as e:
+        logger.warning("LLM Judge failed: %s", e)
+        analysis = f"LLM 분석 실패: {e}"
+
+    return {
+        "tool_name": tool_name,
+        "failure_count": len(failures),
+        "analysis": analysis,
+    }
+
+
 # ── UI ────────────────────────────────────────────────────────────────────────
 
 @app.get("/", response_class=HTMLResponse)

app/tool_search/tool_cards.py

@@ -899,12 +899,29 @@ CONFUSION_PAIRS: list[tuple[str, str]] = [
 # ──────────────────────────────────────────────────────────────
 REGISTRY: dict[str, ToolCard] = {card.name: card for card in _CARDS}
 
+# 코드 정의 원본 (override 복원용)
+CODE_REGISTRY: dict[str, ToolCard] = dict(REGISTRY)
+
 
 def get_card(tool_name: str) -> ToolCard | None:
     """도구 이름으로 ToolCard를 반환한다. 없으면 None."""
     return REGISTRY.get(tool_name)
 
 
+def apply_overrides() -> int:
+    """JSON Store에서 published override를 REGISTRY에 적용. 서버 시작 시 호출."""
+    from app.tool_search.toolcard_store import get_toolcard_store
+
+    store = get_toolcard_store()
+    count = 0
+    for name in store.list_overrides():
+        card = store.get_published(name)
+        if card:
+            REGISTRY[name] = card
+            count += 1
+    return count
+
+
 def missing_cards(tool_names: list[str]) -> list[str]:
     """카드가 없는 도구 이름 목록을 반환한다. 신규 tool 추가 시 경고용."""
     return [n for n in tool_names if n not in REGISTRY]

app/tool_search/toolcard_store.py

@@ -0,0 +1,281 @@
+"""ToolCard JSON Store — 영속화 + 버전 이력 + Draft/Publish/Rollback.
+
+운영자가 Admin UI에서 ToolCard 메타데이터를 수정하면:
+  1. draft로 임시 저장 (챗봇 미반영)
+  2. publish 시 메모리 REGISTRY + ChromaDB 즉시 반영 + JSON 영속화
+  3. 이전 버전은 history에 누적되어 롤백 가능
+
+JSON 파일(data/toolcard_overrides.json)이 없으면 코드 정의 카드만 사용.
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+import logging
+import threading
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Callable
+
+from app.tool_search.tool_cards import ToolCard, REGISTRY as CODE_REGISTRY
+
+logger = logging.getLogger("insurance.toolcard_store")
+
+_DEFAULT_PATH = Path("data/toolcard_overrides.json")
+_MAX_HISTORY = 30
+
+
+def _card_to_dict(card: ToolCard) -> dict[str, Any]:
+    return {
+        "name": card.name,
+        "purpose": card.purpose,
+        "when_to_use": list(card.when_to_use),
+        "when_not_to_use": list(card.when_not_to_use),
+        "tags": list(card.tags),
+    }
+
+
+def _dict_to_card(d: dict[str, Any]) -> ToolCard:
+    return ToolCard(
+        name=d["name"],
+        purpose=d.get("purpose", ""),
+        when_to_use=tuple(d.get("when_to_use", ())),
+        when_not_to_use=tuple(d.get("when_not_to_use", ())),
+        tags=tuple(d.get("tags", ())),
+    )
+
+
+class ToolCardStore:
+    """ToolCard 영속 저장소. 스레드 안전."""
+
+    def __init__(
+        self,
+        path: Path = _DEFAULT_PATH,
+        on_publish: Callable[[ToolCard], None] | None = None,
+    ) -> None:
+        self._path = path
+        self._lock = threading.Lock()
+        self._on_publish = on_publish
+        self._store: dict[str, dict[str, Any]] = {}
+        self._load()
+
+    # ── 로드/저장 ─────────────────────────────────────────────────
+
+    def _load(self) -> None:
+        if not self._path.exists():
+            logger.info("ToolCard override file not found, starting fresh")
+            return
+        try:
+            raw = json.loads(self._path.read_text(encoding="utf-8"))
+            self._store = raw.get("cards", {})
+            logger.info("Loaded %d ToolCard overrides from %s", len(self._store), self._path)
+        except Exception:
+            logger.exception("Failed to load ToolCard overrides")
+
+    def _save(self) -> None:
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        payload = {
+            "updated_at": datetime.now(timezone.utc).isoformat(),
+            "cards": self._store,
+        }
+        self._path.write_text(
+            json.dumps(payload, ensure_ascii=False, indent=2),
+            encoding="utf-8",
+        )
+
+    # ── 읽기 ─────────────────────────────────────────────────────
+
+    def get_published(self, name: str) -> ToolCard | None:
+        """Publish된 override 카드. 없으면 None(코드 카드 사용)."""
+        with self._lock:
+            entry = self._store.get(name)
+            if entry and entry.get("published"):
+                return _dict_to_card(entry["published"])
+        return None
+
+    def get_draft(self, name: str) -> dict[str, Any] | None:
+        with self._lock:
+            entry = self._store.get(name)
+            return copy.deepcopy(entry.get("draft")) if entry else None
+
+    def get_history(self, name: str) -> list[dict[str, Any]]:
+        with self._lock:
+            entry = self._store.get(name)
+            return copy.deepcopy(entry.get("history", [])) if entry else []
+
+    def get_effective_card(self, name: str) -> ToolCard | None:
+        """실제 적용 중인 카드: published override > 코드 정의."""
+        pub = self.get_published(name)
+        return pub if pub else CODE_REGISTRY.get(name)
+
+    def list_overrides(self) -> list[str]:
+        """Override가 있는 도구 이름 목록."""
+        with self._lock:
+            return list(self._store.keys())
+
+    def get_status(self, name: str) -> dict[str, Any]:
+        """도구의 현재 상태 요약."""
+        with self._lock:
+            entry = self._store.get(name, {})
+            has_code = name in CODE_REGISTRY
+            has_published = bool(entry.get("published"))
+            has_draft = bool(entry.get("draft"))
+            history = entry.get("history", [])
+            return {
+                "name": name,
+                "source": "override" if has_published else "code" if has_code else "none",
+                "has_draft": has_draft,
+                "version": history[-1]["version"] if history else 0,
+                "history_count": len(history),
+            }
+
+    # ── 쓰기 ─────────────────────────────────────────────────────
+
+    def save_draft(self, name: str, data: dict[str, Any]) -> dict[str, Any]:
+        """Draft 임시 저장. 챗봇에는 미반영."""
+        data["name"] = name
+        with self._lock:
+            if name not in self._store:
+                self._store[name] = {"published": None, "draft": None, "history": []}
+            self._store[name]["draft"] = data
+            self._save()
+        logger.info("Draft saved for '%s'", name)
+        return data
+
+    def publish(self, name: str, note: str = "") -> ToolCard:
+        """Draft → Published. 메모리 + ChromaDB 반영 + JSON 저장."""
+        with self._lock:
+            entry = self._store.get(name)
+            if not entry or not entry.get("draft"):
+                raise ValueError(f"No draft to publish for '{name}'")
+
+            draft_data = entry["draft"]
+            draft_data["name"] = name
+
+            prev_published = copy.deepcopy(entry.get("published"))
+            history = entry.get("history", [])
+            next_version = (history[-1]["version"] + 1) if history else 1
+
+            history.append({
+                "version": next_version,
+                "timestamp": datetime.now(timezone.utc).isoformat(),
+                "data": copy.deepcopy(draft_data),
+                "note": note or f"v{next_version} published",
+                "previous": prev_published,
+            })
+
+            if len(history) > _MAX_HISTORY:
+                history[:] = history[-_MAX_HISTORY:]
+
+            entry["published"] = draft_data
+            entry["draft"] = None
+            entry["history"] = history
+            self._save()
+
+            card = _dict_to_card(draft_data)
+
+        from app.tool_search.tool_cards import REGISTRY
+        REGISTRY[name] = card
+        logger.info("Published ToolCard '%s' (v%d)", name, next_version)
+
+        if self._on_publish:
+            self._on_publish(card)
+
+        return card
+
+    def publish_direct(self, name: str, data: dict[str, Any], note: str = "") -> ToolCard:
+        """Draft 없이 바로 Publish. 간편 수정용."""
+        self.save_draft(name, data)
+        return self.publish(name, note)
+
+    def rollback(self, name: str, target_version: int) -> ToolCard:
+        """특정 버전으로 롤백."""
+        with self._lock:
+            entry = self._store.get(name)
+            if not entry:
+                raise ValueError(f"No override history for '{name}'")
+
+            history = entry.get("history", [])
+            target = next((h for h in history if h["version"] == target_version), None)
+            if not target:
+                raise ValueError(f"Version {target_version} not found for '{name}'")
+
+            rollback_data = copy.deepcopy(target["data"])
+            prev_published = copy.deepcopy(entry.get("published"))
+
+            next_version = (history[-1]["version"] + 1) if history else 1
+            history.append({
+                "version": next_version,
+                "timestamp": datetime.now(timezone.utc).isoformat(),
+                "data": rollback_data,
+                "note": f"rollback to v{target_version}",
+                "previous": prev_published,
+            })
+
+            if len(history) > _MAX_HISTORY:
+                history[:] = history[-_MAX_HISTORY:]
+
+            entry["published"] = rollback_data
+            entry["draft"] = None
+            entry["history"] = history
+            self._save()
+
+            card = _dict_to_card(rollback_data)
+
+        from app.tool_search.tool_cards import REGISTRY
+        REGISTRY[name] = card
+        logger.info("Rolled back '%s' to v%d (new v%d)", name, target_version, next_version)
+
+        if self._on_publish:
+            self._on_publish(card)
+
+        return card
+
+    def discard_draft(self, name: str) -> None:
+        """Draft 폐기."""
+        with self._lock:
+            entry = self._store.get(name)
+            if entry:
+                entry["draft"] = None
+                self._save()
+
+    def reset_to_code(self, name: str) -> ToolCard | None:
+        """Override를 제거하고 코드 정의 카드로 복원."""
+        with self._lock:
+            if name in self._store:
+                del self._store[name]
+                self._save()
+
+        code_card = CODE_REGISTRY.get(name)
+        if code_card:
+            from app.tool_search.tool_cards import REGISTRY
+            REGISTRY[name] = code_card
+            if self._on_publish:
+                self._on_publish(code_card)
+        return code_card
+
+    @staticmethod
+    def diff(card_a: dict[str, Any], card_b: dict[str, Any]) -> dict[str, Any]:
+        """두 카드 데이터의 필드별 차이를 반환."""
+        changes: dict[str, Any] = {}
+        all_keys = {"purpose", "when_to_use", "when_not_to_use", "tags"}
+        for key in all_keys:
+            old_val = card_a.get(key)
+            new_val = card_b.get(key)
+            if old_val != new_val:
+                changes[key] = {"old": old_val, "new": new_val}
+        return changes
+
+
+_store_instance: ToolCardStore | None = None
+_store_lock = threading.Lock()
+
+
+def get_toolcard_store(**kwargs) -> ToolCardStore:
+    global _store_instance
+    if _store_instance is None:
+        with _store_lock:
+            if _store_instance is None:
+                _store_instance = ToolCardStore(**kwargs)
+    return _store_instance

data/toolcard_overrides.json

@@ -0,0 +1,4 @@
+{
+  "updated_at": "2026-02-25T06:58:39.264096+00:00",
+  "cards": {}
+}

templates/admin_tools.html

@@ -105,17 +105,17 @@
       border-bottom:1px solid var(--border); position:sticky; top:58px; z-index:10;
     }
     .tool-table td {
-      padding:10px 14px; font-size:13px; border-bottom:1px solid var(--border);
+      padding:12px 14px; font-size:13px; border-bottom:1px solid var(--border);
       vertical-align:top;
     }
     .tool-table tr:last-child td { border-bottom:none; }
-    .tool-table tr:hover td { background:rgba(108,92,231,0.04); }
+    .tool-table tr:hover td { background:rgba(108,92,231,0.06); }
 
-    .tool-name { font-weight:600; color:var(--accent-light); font-family:'SF Mono',monospace; font-size:12px; }
-    .tool-purpose { color:var(--text-dim); font-size:12px; margin-top:2px; }
+    .tool-name { font-weight:600; color:var(--accent-light); font-family:'SF Mono',monospace; font-size:12.5px; }
+    .tool-purpose { color:var(--text-dim); font-size:12px; margin-top:3px; line-height:1.4; }
     .tag {
-      display:inline-block; padding:2px 7px; border-radius:4px;
-      font-size:10px; font-weight:600; margin:1px 2px;
+      display:inline-block; padding:2px 8px; border-radius:4px;
+      font-size:10.5px; font-weight:600; margin:1px 2px;
     }
     .tag.card { background:var(--success-dim); color:var(--success); }
     .tag.no-card { background:var(--warning-dim); color:var(--warning); }
@@ -144,9 +144,9 @@
     .modal p { font-size:13px; color:var(--text-dim); margin-bottom:16px; line-height:1.5; }
     .modal .modal-actions { display:flex; gap:8px; justify-content:flex-end; }
 
-    .modal label { display:block; font-size:12px; color:var(--text-dim); margin-bottom:6px; }
+    .modal label { display:block; font-size:12px; color:var(--text-dim); margin-bottom:6px; font-weight:500; }
     .modal input, .modal select {
-      width:100%; padding:8px 12px; border:1px solid var(--border);
+      width:100%; padding:9px 12px; border:1px solid var(--border);
       border-radius:8px; background:var(--surface2); color:var(--text);
       font-size:13px; margin-bottom:14px; outline:none;
     }
@@ -174,6 +174,204 @@
     .when-to-use.expanded { max-height:500px; }
     .when-to-use span { display:block; padding:1px 0; }
 
+    .modal.wide { max-width:700px; max-height:90vh; display:flex; flex-direction:column; }
+    .modal.wide .modal-body { flex:1; overflow-y:auto; padding-right:4px; }
+    .edit-header { display:flex; align-items:center; justify-content:space-between; margin-bottom:14px; flex-wrap:wrap; gap:8px; }
+    .edit-header h3 { margin:0; }
+    .edit-status { display:flex; gap:6px; }
+
+    .tab-bar { display:flex; gap:0; margin-bottom:16px; border-bottom:1px solid var(--border); }
+    .tab-btn {
+      padding:8px 18px; font-size:12px; font-weight:600; cursor:pointer;
+      background:transparent; border:none; color:var(--text-muted);
+      border-bottom:2px solid transparent; transition:all 0.2s;
+    }
+    .tab-btn:hover { color:var(--text); }
+    .tab-btn.active { color:var(--accent-light); border-bottom-color:var(--accent); }
+
+    .list-editor { margin-bottom:8px; }
+    .list-item {
+      display:flex; align-items:center; gap:8px; padding:7px 10px;
+      background:var(--surface2); border:1px solid var(--border); border-radius:6px;
+      margin-bottom:4px; font-size:12px; line-height:1.4;
+    }
+    .list-item span { flex:1; word-break:break-word; }
+    .list-item .rm-btn {
+      width:20px; height:20px; border:none; background:transparent;
+      color:var(--danger); cursor:pointer; font-size:14px; flex-shrink:0;
+      display:flex; align-items:center; justify-content:center; border-radius:4px;
+    }
+    .list-item .rm-btn:hover { background:var(--danger-dim); }
+    .add-row { display:flex; gap:6px; margin-bottom:14px; }
+    .add-row input { flex:1; margin-bottom:0; }
+    .add-row .btn { padding:6px 14px; }
+
+    .tag-editor { display:flex; flex-wrap:wrap; gap:4px; margin-bottom:8px; }
+    .tag-chip {
+      display:flex; align-items:center; gap:4px; padding:3px 8px;
+      background:var(--info-dim); color:var(--info); border-radius:4px;
+      font-size:11px; font-weight:600;
+    }
+    .tag-chip .rm-btn { color:var(--info); font-size:12px; cursor:pointer; background:transparent; border:none; }
+    .tag-chip .rm-btn:hover { color:var(--danger); }
+
+    .history-item {
+      display:flex; align-items:center; gap:12px; padding:12px 14px;
+      background:var(--surface2); border:1px solid var(--border); border-radius:8px;
+      margin-bottom:6px; font-size:12px; line-height:1.4;
+    }
+    .history-item .ver { font-weight:700; color:var(--accent-light); min-width:28px; }
+    .history-item .note { flex:1; color:var(--text-dim); }
+    .history-item .ts { color:var(--text-muted); font-size:11px; white-space:nowrap; }
+    .history-actions { display:flex; gap:4px; }
+
+    .diff-block { margin:8px 0 14px; padding:10px; background:var(--surface2); border:1px solid var(--border); border-radius:8px; font-size:12px; }
+    .diff-block .diff-field { margin-bottom:8px; }
+    .diff-block .diff-label { font-weight:600; color:var(--text); margin-bottom:4px; }
+    .diff-old { color:var(--danger); text-decoration:line-through; }
+    .diff-new { color:var(--success); }
+
+    .edit-note-input { margin-bottom:0 !important; }
+
+    /* Quick Test tab */
+    .eval-section {
+      margin-bottom:24px; padding-bottom:20px;
+      border-bottom:1px solid var(--border);
+    }
+    .eval-section:last-child { border-bottom:none; margin-bottom:0; }
+    .eval-section h4 {
+      font-size:14px; font-weight:700; margin-bottom:4px; color:var(--accent-light);
+      display:flex; align-items:center; gap:8px;
+    }
+    .eval-section h4 .step-num {
+      background:var(--accent); color:#fff; width:22px; height:22px; border-radius:50%;
+      display:inline-flex; align-items:center; justify-content:center;
+      font-size:11px; font-weight:700; flex-shrink:0;
+    }
+    .eval-section .section-desc {
+      font-size:12px; color:var(--text-muted); margin-bottom:12px; line-height:1.5;
+    }
+    .search-test-row { display:flex; gap:8px; margin-bottom:14px; }
+    .search-test-row input { flex:1; margin-bottom:0; }
+
+    .search-result {
+      display:flex; align-items:center; gap:10px; padding:8px 12px;
+      background:var(--surface2); border:1px solid var(--border); border-radius:8px;
+      margin-bottom:4px; font-size:12px; transition:border-color 0.15s;
+    }
+    .search-result .rank {
+      min-width:28px; height:28px; border-radius:50%; font-weight:700;
+      display:flex; align-items:center; justify-content:center;
+      background:var(--surface3); color:var(--text-muted); font-size:11px;
+    }
+    .search-result .sr-name { font-family:'SF Mono',monospace; color:var(--accent-light); min-width:150px; font-weight:600; }
+    .search-result .sr-score-wrap { min-width:100px; display:flex; flex-direction:column; gap:2px; }
+    .search-result .sr-score { color:var(--success); font-weight:700; font-size:12px; }
+    .search-result .sr-bar { height:3px; border-radius:2px; background:var(--surface3); }
+    .search-result .sr-bar-fill { height:100%; border-radius:2px; background:var(--success); }
+    .search-result .sr-desc { flex:1; color:var(--text-muted); font-size:11px; line-height:1.4; }
+    .search-result.is-target {
+      border-color:var(--success); background:var(--success-dim);
+    }
+    .search-result.is-target .rank { background:var(--success); color:#fff; }
+    .search-result.is-miss { border-color:var(--danger); background:var(--danger-dim); }
+
+    .recall-bar { display:flex; gap:12px; margin-bottom:16px; flex-wrap:wrap; }
+    .recall-card {
+      background:var(--surface2); border:1px solid var(--border); border-radius:10px;
+      padding:14px 20px; text-align:center; min-width:90px; flex:1;
+    }
+    .recall-card .rc-label { font-size:11px; color:var(--text-muted); font-weight:600; letter-spacing:0.3px; }
+    .recall-card .rc-value { font-size:24px; font-weight:800; margin-top:4px; }
+    .recall-card .rc-sub { font-size:10px; color:var(--text-muted); margin-top:2px; }
+    .recall-card .rc-value.good { color:var(--success); }
+    .recall-card .rc-value.ok { color:var(--warning); }
+    .recall-card .rc-value.bad { color:var(--danger); }
+
+    .batch-detail {
+      display:flex; align-items:center; gap:8px; padding:8px 12px;
+      background:var(--surface2); border:1px solid var(--border); border-radius:8px;
+      margin-bottom:4px; font-size:12px;
+    }
+    .batch-detail .bd-icon { font-size:14px; min-width:20px; text-align:center; }
+    .batch-detail .bd-query { flex:1; word-break:break-word; line-height:1.4; }
+    .batch-detail .bd-rank {
+      font-weight:700; min-width:32px; text-align:center;
+      padding:2px 6px; border-radius:4px; font-size:11px;
+    }
+    .batch-detail.pass .bd-rank { background:var(--success-dim); color:var(--success); }
+    .batch-detail.fail .bd-rank { background:var(--danger-dim); color:var(--danger); }
+    .batch-detail .bd-top { color:var(--text-muted); font-size:11px; max-width:200px; white-space:nowrap; overflow:hidden; text-overflow:ellipsis; }
+    .batch-detail.pass .bd-icon { color:var(--success); }
+    .batch-detail.fail .bd-icon { color:var(--danger); }
+    .batch-detail.fail { border-color:var(--danger); background:var(--danger-dim); }
+
+    .judge-box {
+      background:var(--surface2); border:1px solid var(--border); border-radius:10px;
+      padding:18px 20px; font-size:13px; line-height:1.8; color:var(--text-dim);
+      max-height:400px; overflow-y:auto;
+    }
+    .judge-box h3 { font-size:14px; color:var(--accent-light); margin:16px 0 8px; font-weight:700; }
+    .judge-box h3:first-child { margin-top:0; }
+    .judge-box h4 { font-size:13px; color:var(--text); margin:12px 0 6px; font-weight:600; }
+    .judge-box strong { color:var(--text); }
+    .judge-box em { color:var(--warning); font-style:normal; font-weight:600; }
+    .judge-box code { background:var(--surface3); color:var(--accent-light); padding:1px 5px; border-radius:3px; font-size:12px; }
+    .judge-box ul, .judge-box ol { margin:6px 0 6px 18px; }
+    .judge-box li { margin:3px 0; }
+    .judge-box hr { border:none; border-top:1px solid var(--border); margin:14px 0; }
+    .judge-box blockquote {
+      border-left:3px solid var(--accent); padding:6px 12px; margin:8px 0;
+      background:rgba(108,92,231,0.06); border-radius:0 6px 6px 0; font-size:12px;
+    }
+
+    .spinner { display:inline-block; width:14px; height:14px; border:2px solid var(--border); border-top-color:var(--accent); border-radius:50%; animation:spin 0.6s linear infinite; }
+    @keyframes spin { to { transform:rotate(360deg); } }
+
+    /* Guide & Safety UX */
+    .guide-panel {
+      background:var(--surface); border:1px solid var(--border); border-radius:var(--radius);
+      padding:16px 20px; margin-bottom:20px; font-size:12px; line-height:1.7;
+    }
+    .guide-toggle {
+      display:flex; align-items:center; justify-content:space-between; cursor:pointer;
+      font-weight:700; font-size:13px; color:var(--accent-light);
+    }
+    .guide-toggle .arrow { transition:transform 0.2s; }
+    .guide-panel.collapsed .guide-body { display:none; }
+    .guide-panel.collapsed .arrow { transform:rotate(-90deg); }
+    .guide-body { margin-top:12px; }
+    .guide-row { display:flex; gap:10px; align-items:flex-start; margin-bottom:8px; }
+    .guide-row .gl { min-width:72px; font-weight:700; padding:3px 8px; border-radius:4px; text-align:center; font-size:10px; flex-shrink:0; margin-top:1px; }
+    .gl-safe { background:var(--success-dim); color:var(--success); }
+    .gl-live { background:var(--danger-dim); color:var(--danger); }
+    .gl-warn { background:var(--warning-dim); color:var(--warning); }
+
+    .tab-badge {
+      font-size:9px; padding:1px 5px; border-radius:3px; margin-left:4px;
+      font-weight:700; vertical-align:middle; letter-spacing:0.3px;
+    }
+    .tab-badge.safe { background:var(--success-dim); color:var(--success); }
+    .tab-badge.live { background:var(--danger-dim); color:var(--danger); }
+
+    .publish-warning {
+      background:var(--warning-dim); border:1px solid rgba(253,203,110,0.3); border-radius:8px;
+      padding:10px 14px; margin-bottom:14px; font-size:11px; line-height:1.6; color:var(--warning);
+    }
+    .publish-warning strong { color:var(--text); }
+
+    .btn.publish-btn {
+      background:#c0392b; color:#fff; border-color:#c0392b;
+      font-weight:700;
+    }
+    .btn.publish-btn:hover { background:#e74c3c; border-color:#e74c3c; }
+
+    .safe-banner {
+      background:var(--success-dim); border:1px solid rgba(0,184,148,0.2); border-radius:8px;
+      padding:8px 12px; margin-bottom:14px; font-size:11px; color:var(--success);
+      display:flex; align-items:center; gap:6px;
+    }
+
     @media (max-width:768px) {
       .content { padding:12px; }
       .stats-row { grid-template-columns:1fr 1fr; }
@@ -181,6 +379,9 @@
       .tool-table th, .tool-table td { padding:8px 10px; }
       .col-tags, .col-when { display:none; }
       header { padding:10px 14px; }
+      .modal.wide { max-width:100%; width:100%; margin:8px; max-height:calc(100vh - 16px); }
+      .tab-btn { padding:8px 12px; font-size:11px; }
+      .edit-header { flex-direction:column; align-items:flex-start; }
     }
   </style>
 </head>
@@ -197,6 +398,39 @@
   </header>
 
   <div class="content">
+    <!-- 온보딩 가이드 -->
+    <div class="guide-panel" id="guide-panel">
+      <div class="guide-toggle" onclick="toggleGuide()">
+        <span>이 화면 사용법</span>
+        <span class="arrow">▼</span>
+      </div>
+      <div class="guide-body">
+        <div class="guide-row">
+          <span class="gl gl-safe">안전</span>
+          <span>검색, 상세보기, 퀵 테스트 — 챗봇에 아무 영향 없음. 마음껏 써도 됨</span>
+        </div>
+        <div class="guide-row">
+          <span class="gl gl-warn">주의</span>
+          <span>편집 탭에서 내용을 고치는 것 자체는 안전. 아직 반영 안 됨</span>
+        </div>
+        <div class="guide-row">
+          <span class="gl gl-live">즉시 반영</span>
+          <span><strong>「저장 & 즉시 반영」</strong> 클릭 → 지금 돌아가는 챗봇에 바로 적용됨</span>
+        </div>
+        <div class="guide-row">
+          <span class="gl gl-live">즉시 반영</span>
+          <span><strong>「도구 해제」</strong> 클릭 → 챗봇이 해당 도구를 바로 못 씀 (모듈 리로드로 복원 가능)</span>
+        </div>
+        <div class="guide-row">
+          <span class="gl gl-live">즉시 반영</span>
+          <span><strong>「롤백」</strong> 클릭 → 과거 버전으로 교체. 지금 반영 중인 카드가 바뀜</span>
+        </div>
+        <div style="margin-top:8px;color:var(--text-muted);font-size:11px">
+          잘못 반영했을 때: 「코드 원본 복원」 또는 「롤백」으로 되돌릴 수 있음
+        </div>
+      </div>
+    </div>
+
     <div class="stats-row" id="stats-row">
       <div class="stat-card"><div class="label">등록 도구</div><div class="value" id="s-tools">—</div></div>
       <div class="stat-card"><div class="label">ChromaDB 벡터</div><div class="value" id="s-vectors">—</div></div>
@@ -235,11 +469,19 @@
   <!-- Delete Confirm Modal -->
   <div class="modal-overlay" id="delete-modal">
     <div class="modal">
-      <h3>도구 해제 확인</h3>
-      <p><strong id="del-name" style="color:var(--danger)"></strong> 도구를 런타임에서 해제합니다.<br>ChromaDB 벡터도 즉시 삭제됩니다. 모듈 리로드로 복원할 수 있습니다.</p>
+      <h3 style="color:var(--danger)">도구 해제 — 즉시 반영됨</h3>
+      <div class="publish-warning" style="border-color:rgba(225,112,85,0.3)">
+        <strong style="color:var(--danger)">이 작업은 지금 돌아가는 챗봇에 바로 적용됩니다.</strong>
+      </div>
+      <p>
+        <strong id="del-name" style="color:var(--danger)"></strong> 도구를 해제하면:<br>
+        • 챗봇이 이 도구를 <strong>더 이상 사용할 수 없게</strong> 됩니다<br>
+        • ChromaDB에서 벡터가 즉시 삭제됩니다<br><br>
+        <span style="color:var(--success)">되돌리는 방법:</span> 상단의 「모듈 리로드」 버튼으로 복원할 수 있습니다.
+      </p>
       <div class="modal-actions">
-        <button class="btn" onclick="closeModal('delete-modal')">취소</button>
-        <button class="btn danger" id="del-confirm" onclick="confirmDelete()">해제</button>
+        <button class="btn" onclick="closeModal('delete-modal')">취소 (해제 안 함)</button>
+        <button class="btn danger" id="del-confirm" onclick="confirmDelete()">해제 실행</button>
       </div>
     </div>
   </div>
@@ -273,17 +515,143 @@
       <h3 id="detail-title"></h3>
       <div id="detail-body" style="font-size:13px;line-height:1.6;color:var(--text-dim);max-height:60vh;overflow-y:auto"></div>
       <div class="modal-actions" style="margin-top:16px">
+        <button class="btn primary" onclick="closeModal('detail-modal');openEdit(document.getElementById('detail-title').textContent)">편집</button>
         <button class="btn" onclick="closeModal('detail-modal')">닫기</button>
       </div>
     </div>
   </div>
 
+  <!-- Edit ToolCard Modal -->
+  <div class="modal-overlay" id="edit-modal">
+    <div class="modal wide">
+      <div class="edit-header">
+        <h3 id="edit-title">ToolCard 편집</h3>
+        <div class="edit-status">
+          <span class="tag card" id="edit-source"></span>
+          <span class="tag module" id="edit-version"></span>
+        </div>
+      </div>
+
+      <div class="tab-bar">
+        <button class="tab-btn active" data-tab="edit" onclick="switchEditTab('edit')">편집 <span class="tab-badge live">수정 가능</span></button>
+        <button class="tab-btn" data-tab="history" onclick="switchEditTab('history')">버전 이력 <span class="tab-badge safe">안전</span></button>
+        <button class="tab-btn" data-tab="eval" onclick="switchEditTab('eval')">퀵 테스트 <span class="tab-badge safe">안전</span></button>
+      </div>
+
+      <div class="modal-body">
+        <!-- 편집 탭 -->
+        <div id="tab-edit">
+          <label>Purpose (도구 목적)</label>
+          <input id="edit-purpose" type="text" placeholder="이 도구가 하는 일을 한 문장으로...">
+
+          <label>when_to_use (사용자 발화 예시)</label>
+          <div class="list-editor" id="edit-wtu"></div>
+          <div class="add-row">
+            <input id="new-wtu" type="text" placeholder='예: "보험료 얼마야?"'>
+            <button class="btn" onclick="addListItem('wtu')">추가</button>
+          </div>
+
+          <label>when_not_to_use (혼동 방지)</label>
+          <div class="list-editor" id="edit-wntu"></div>
+          <div class="add-row">
+            <input id="new-wntu" type="text" placeholder='예: "납입 플랜 → plan_options 사용"'>
+            <button class="btn" onclick="addListItem('wntu')">추가</button>
+          </div>
+
+          <label>Tags (도메인 태그)</label>
+          <div class="tag-editor" id="edit-tags"></div>
+          <div class="add-row">
+            <input id="new-tag" type="text" placeholder="태그 추가..." style="max-width:200px">
+            <button class="btn" onclick="addTagItem()">추가</button>
+          </div>
+
+          <label>변경 메모 (이력에 기록됨)</label>
+          <input class="edit-note-input" id="edit-note" type="text" placeholder="무엇을 변경했는지 간단히...">
+
+          <div class="publish-warning">
+            <strong>아래 버튼을 누르면 지금 돌아가는 챗봇에 바로 적용됩니다.</strong><br>
+            먼저 「퀵 테스트」 탭에서 확인한 뒤 반영하는 것을 권장합니다.<br>
+            잘못 반영했으면 「버전 이력」 탭에서 롤백하거나, 「코드 원본 복원」으로 되돌릴 수 있습니다.
+          </div>
+
+          <div class="modal-actions" style="margin-top:8px">
+            <button class="btn" onclick="closeModal('edit-modal')">취소 (변경 안 함)</button>
+            <button class="btn danger" id="btn-reset" onclick="resetToCode()" style="display:none" title="이 도구의 모든 수정을 지우고 원래 코드로 돌아갑니다">코드 원본 복원</button>
+            <button class="btn publish-btn" id="btn-publish" onclick="publishCard()">저장 & 즉시 반영</button>
+          </div>
+        </div>
+
+        <!-- 버전 이력 탭 -->
+        <div id="tab-history" style="display:none">
+          <div class="safe-banner">
+            <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 22s8-4 8-10V5l-8-3-8 3v7c0 6 8 10 8 10z"/></svg>
+            이력 조회와 Diff는 안전합니다. 단, <strong style="color:var(--warning)">「롤백」 버튼은 챗봇에 즉시 반영</strong>되니 주의하세요.
+          </div>
+          <div id="history-list"><div class="empty-state">이력이 없습니다.</div></div>
+          <div id="diff-view"></div>
+        </div>
+
+        <!-- 퀵 테스트 탭 -->
+        <div id="tab-eval" style="display:none">
+          <div class="safe-banner">
+            <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 22s8-4 8-10V5l-8-3-8 3v7c0 6 8 10 8 10z"/></svg>
+            이 탭은 읽기 전용입니다. 여기서 뭘 해도 챗봇에 영향 없습니다.
+          </div>
+          <!-- 1. 실시간 쿼리 검색 -->
+          <div class="eval-section">
+            <h4><span class="step-num">1</span> 실시간 쿼리 테스트</h4>
+            <div class="section-desc">
+              아무 질문이나 입력하면, 챗봇이 어떤 도구를 선택할지 미리 확인합니다. 현재 도구가 초록색으로 표시됩니다.
+            </div>
+            <div class="search-test-row">
+              <input id="eval-query" type="text" placeholder="예: 보험료 좀 알아봐줘">
+              <button class="btn primary" onclick="runSearchTest()">검색</button>
+            </div>
+            <div id="eval-search-results"></div>
+          </div>
+
+          <!-- 2. 배치 Recall 평가 -->
+          <div class="eval-section">
+            <h4><span class="step-num">2</span> 자가 성능 평가</h4>
+            <div class="section-desc">
+              이 도구에 등록된 발화 예시를 전부 검색해봅니다. "100%"면 모든 예시가 정확히 이 도구로 연결된다는 뜻입니다.
+            </div>
+            <button class="btn" id="btn-batch" onclick="runBatchEval()">배치 평가 실행</button>
+            <div id="eval-recall-bar" style="margin-top:12px"></div>
+            <div id="eval-batch-details" style="margin-top:8px"></div>
+          </div>
+
+          <!-- 3. LLM Judge -->
+          <div class="eval-section">
+            <h4><span class="step-num">3</span> AI 개선 제안</h4>
+            <div class="section-desc">
+              2단계에서 실패한 쿼리가 있으면, AI가 원인을 분석하고 어떻게 고치면 되는지 구체적으로 제안합니다.
+            </div>
+            <button class="btn" id="btn-judge" onclick="runLlmJudge()" disabled>LLM 분석 실행</button>
+            <div id="eval-judge-result" style="margin-top:12px"></div>
+          </div>
+        </div>
+      </div>
+    </div>
+  </div>
+
   <div class="toast" id="toast"></div>
 
 <script>
 let allTools = [];
 let toolCards = {};
 let deleteTarget = '';
+let editName = '';
+let editData = { when_to_use: [], when_not_to_use: [], tags: [] };
+
+function toggleGuide() {
+  const panel = document.getElementById('guide-panel');
+  panel.classList.toggle('collapsed');
+  localStorage.setItem('guide-collapsed', panel.classList.contains('collapsed'));
+}
+if (localStorage.getItem('guide-collapsed') === 'true') {
+  document.getElementById('guide-panel').classList.add('collapsed');
+}
 
 async function fetchHealth() {
   try {
@@ -354,10 +722,13 @@ function renderTable(tools) {
       </td>
       <td>
         <div class="action-btns">
+          <button class="action-btn" onclick="openEdit('${t.name}')" title="편집" style="color:var(--accent-light)">
+            <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M11 4H4a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2v-7"/><path d="M18.5 2.5a2.121 2.121 0 0 1 3 3L12 15l-4 1 1-4 9.5-9.5z"/></svg>
+          </button>
           <button class="action-btn" onclick="showDetail('${t.name}')" title="상세보기">
             <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="12" r="10"/><line x1="12" y1="16" x2="12" y2="12"/><line x1="12" y1="8" x2="12.01" y2="8"/></svg>
           </button>
-          <button class="action-btn del" onclick="openDeleteModal('${t.name}')" title="해제">
+          <button class="action-btn del" onclick="openDeleteModal('${t.name}')" title="이 도구를 해제합니다 (챗봇에 즉시 반영됨)">
             <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><polyline points="3 6 5 6 21 6"/><path d="M19 6v14a2 2 0 0 1-2 2H7a2 2 0 0 1-2-2V6m3 0V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2"/></svg>
           </button>
         </div>
@@ -456,6 +827,457 @@ async function refreshAll() {
   await Promise.all([fetchHealth(), fetchTools()]);
 }
 
+// ── Edit ToolCard ──────────────────────────────────────────
+
+async function openEdit(name) {
+  editName = name;
+  document.getElementById('edit-title').textContent = name;
+  document.getElementById('edit-note').value = '';
+  switchEditTab('edit');
+
+  try {
+    const r = await fetch(`/api/admin/toolcards/${name}`);
+    const d = await r.json();
+
+    const src = d.source === 'override' ? 'Override' : d.source === 'code' ? 'Code' : '—';
+    document.getElementById('edit-source').textContent = src;
+    document.getElementById('edit-source').className = 'tag ' + (d.source === 'override' ? 'card' : 'module');
+    document.getElementById('edit-version').textContent = d.version ? `v${d.version}` : 'v0';
+    document.getElementById('btn-reset').style.display = d.source === 'override' ? '' : 'none';
+
+    const card = d.draft || d.effective || {};
+    editData = {
+      when_to_use: [...(card.when_to_use || [])],
+      when_not_to_use: [...(card.when_not_to_use || [])],
+      tags: [...(card.tags || [])],
+    };
+    document.getElementById('edit-purpose').value = card.purpose || '';
+    renderListEditor('wtu', editData.when_to_use);
+    renderListEditor('wntu', editData.when_not_to_use);
+    renderTagEditor(editData.tags);
+
+  } catch(e) {
+    const t = toolCards[name];
+    if (t) {
+      editData = {
+        when_to_use: [...(t.when_to_use || [])],
+        when_not_to_use: [...(t.when_not_to_use || [])],
+        tags: [...(t.tags || [])],
+      };
+      document.getElementById('edit-purpose').value = t.purpose || '';
+      document.getElementById('edit-source').textContent = 'Code';
+      document.getElementById('edit-version').textContent = 'v0';
+      document.getElementById('btn-reset').style.display = 'none';
+      renderListEditor('wtu', editData.when_to_use);
+      renderListEditor('wntu', editData.when_not_to_use);
+      renderTagEditor(editData.tags);
+    }
+  }
+
+  document.getElementById('edit-modal').classList.add('show');
+}
+
+function renderListEditor(key, items) {
+  const container = document.getElementById('edit-' + key);
+  container.innerHTML = items.map((item, i) => `
+    <div class="list-item">
+      <span>${escHtml(item)}</span>
+      <button class="rm-btn" onclick="removeListItem('${key}',${i})">&times;</button>
+    </div>
+  `).join('');
+}
+
+function renderTagEditor(tags) {
+  const container = document.getElementById('edit-tags');
+  container.innerHTML = tags.map((t, i) => `
+    <div class="tag-chip">
+      ${escHtml(t)}
+      <button class="rm-btn" onclick="removeTag(${i})">&times;</button>
+    </div>
+  `).join('');
+}
+
+function addListItem(key) {
+  const input = document.getElementById('new-' + key);
+  const val = input.value.trim();
+  if (!val) return;
+  const dataKey = key === 'wtu' ? 'when_to_use' : 'when_not_to_use';
+  editData[dataKey].push(val);
+  renderListEditor(key, editData[dataKey]);
+  input.value = '';
+  input.focus();
+}
+
+function removeListItem(key, idx) {
+  const dataKey = key === 'wtu' ? 'when_to_use' : 'when_not_to_use';
+  editData[dataKey].splice(idx, 1);
+  renderListEditor(key, editData[dataKey]);
+}
+
+function addTagItem() {
+  const input = document.getElementById('new-tag');
+  const val = input.value.trim();
+  if (!val) return;
+  editData.tags.push(val);
+  renderTagEditor(editData.tags);
+  input.value = '';
+  input.focus();
+}
+
+function removeTag(idx) {
+  editData.tags.splice(idx, 1);
+  renderTagEditor(editData.tags);
+}
+
+async function publishCard() {
+  const ok = confirm(
+    `[즉시 반영] ${editName}\n\n` +
+    `이 변경이 지금 돌아가는 챗봇에 바로 적용됩니다.\n` +
+    `(잘못되면 \"버전 이력\" 탭에서 롤백 가능)\n\n` +
+    `계속 진행할까요?`
+  );
+  if (!ok) return;
+
+  const btn = document.getElementById('btn-publish');
+  btn.disabled = true; btn.textContent = '반영 중...';
+
+  const data = {
+    purpose: document.getElementById('edit-purpose').value.trim(),
+    when_to_use: editData.when_to_use,
+    when_not_to_use: editData.when_not_to_use,
+    tags: editData.tags,
+  };
+
+  if (!data.purpose) {
+    showToast('Purpose는 필수입니다', 'error');
+    btn.disabled = false; btn.textContent = '저장 & 즉시 반영';
+    return;
+  }
+
+  try {
+    const r = await fetch(`/api/admin/toolcards/${editName}/publish`, {
+      method: 'POST',
+      headers: {'Content-Type':'application/json'},
+      body: JSON.stringify({ data, note: document.getElementById('edit-note').value.trim() || undefined }),
+    });
+    const d = await r.json();
+    if (r.ok) {
+      showToast(`${editName} v${d.version} 반영 완료 — 챗봇에 적용됨`, 'success');
+      closeModal('edit-modal');
+      refreshAll();
+    } else {
+      showToast(d.detail || '반영 실패', 'error');
+    }
+  } catch(e) {
+    showToast('요청 실패: ' + e.message, 'error');
+  } finally {
+    btn.disabled = false; btn.textContent = '저장 & 즉시 반영';
+  }
+}
+
+async function resetToCode() {
+  if (!confirm(
+    `[즉시 반영] 코드 원본 복원\n\n` +
+    `${editName}의 모든 수정 내역을 지우고,\n` +
+    `개발자가 작성한 원래 상태로 되돌립니다.\n\n` +
+    `→ 챗봇에 바로 적용됩니다.\n\n계속 진행할까요?`
+  )) return;
+  try {
+    const r = await fetch(`/api/admin/toolcards/${editName}/override`, {method:'DELETE'});
+    if (r.ok) {
+      showToast(`${editName} 코드 원본 복원 완료`, 'success');
+      closeModal('edit-modal');
+      refreshAll();
+    }
+  } catch(e) {
+    showToast('복원 실패: ' + e.message, 'error');
+  }
+}
+
+// ── History / Diff ─────────────────────────────────────────
+
+function switchEditTab(tab) {
+  document.querySelectorAll('.tab-btn').forEach(b => b.classList.toggle('active', b.dataset.tab === tab));
+  document.getElementById('tab-edit').style.display = tab === 'edit' ? '' : 'none';
+  document.getElementById('tab-history').style.display = tab === 'history' ? '' : 'none';
+  document.getElementById('tab-eval').style.display = tab === 'eval' ? '' : 'none';
+  if (tab === 'history') loadHistory();
+}
+
+async function loadHistory() {
+  const container = document.getElementById('history-list');
+  const diffView = document.getElementById('diff-view');
+  diffView.innerHTML = '';
+
+  try {
+    const r = await fetch(`/api/admin/toolcards/${editName}/history`);
+    const d = await r.json();
+    const history = d.history || [];
+
+    if (!history.length) {
+      container.innerHTML = '<div class="empty-state">아직 변경 이력이 없습니다.<br>편집 탭에서 저장 & 반영하면 이력이 생성됩니다.</div>';
+      return;
+    }
+
+    container.innerHTML = history.slice().reverse().map(h => {
+      const ts = new Date(h.timestamp).toLocaleString('ko-KR', {dateStyle:'short',timeStyle:'short'});
+      return `
+        <div class="history-item">
+          <div class="ver">v${h.version}</div>
+          <div class="note">${escHtml(h.note)}</div>
+          <div class="ts">${ts}</div>
+          <div class="history-actions">
+            ${h.previous ? `<button class="action-btn" onclick="showDiff(${h.version})" title="Diff">Diff</button>` : ''}
+            <button class="action-btn" onclick="rollbackTo(${h.version})" title="이 버전으로 롤백" style="color:var(--warning)">롤백</button>
+          </div>
+        </div>`;
+    }).join('');
+  } catch(e) {
+    container.innerHTML = '<div class="empty-state">이력 로드 실패</div>';
+  }
+}
+
+async function showDiff(version) {
+  const diffView = document.getElementById('diff-view');
+
+  try {
+    const r = await fetch(`/api/admin/toolcards/${editName}/history`);
+    const d = await r.json();
+    const entry = (d.history || []).find(h => h.version === version);
+    if (!entry || !entry.previous) { diffView.innerHTML = ''; return; }
+
+    const prev = entry.previous;
+    const curr = entry.data;
+    const fields = ['purpose', 'when_to_use', 'when_not_to_use', 'tags'];
+
+    let html = `<div class="diff-block"><strong>v${version - 1} → v${version} 변경사항</strong>`;
+
+    for (const f of fields) {
+      const oldVal = prev[f]; const newVal = curr[f];
+      if (JSON.stringify(oldVal) === JSON.stringify(newVal)) continue;
+
+      html += `<div class="diff-field"><div class="diff-label">${f}</div>`;
+
+      if (Array.isArray(oldVal) && Array.isArray(newVal)) {
+        const removed = oldVal.filter(x => !newVal.includes(x));
+        const added = newVal.filter(x => !oldVal.includes(x));
+        removed.forEach(x => html += `<div class="diff-old">- ${escHtml(x)}</div>`);
+        added.forEach(x => html += `<div class="diff-new">+ ${escHtml(x)}</div>`);
+      } else {
+        html += `<div class="diff-old">- ${escHtml(String(oldVal || ''))}</div>`;
+        html += `<div class="diff-new">+ ${escHtml(String(newVal || ''))}</div>`;
+      }
+      html += `</div>`;
+    }
+
+    html += `</div>`;
+    diffView.innerHTML = html;
+  } catch(e) {
+    diffView.innerHTML = '<div class="empty-state">Diff 로드 실패</div>';
+  }
+}
+
+async function rollbackTo(version) {
+  if (!confirm(
+    `[즉시 반영] v${version} 롤백\n\n` +
+    `현재 적용 중인 카드를 v${version} 내용으로 교체합니다.\n` +
+    `→ 챗봇에 바로 적용됩니다.\n\n계속 진행할까요?`
+  )) return;
+  try {
+    const r = await fetch(`/api/admin/toolcards/${editName}/rollback`, {
+      method:'POST',
+      headers:{'Content-Type':'application/json'},
+      body: JSON.stringify({version}),
+    });
+    const d = await r.json();
+    if (r.ok) {
+      showToast(`${editName} → v${version} 롤백 완료 (새 v${d.version})`, 'success');
+      closeModal('edit-modal');
+      refreshAll();
+    } else {
+      showToast(d.detail || '롤백 실패', 'error');
+    }
+  } catch(e) {
+    showToast('롤백 실패: ' + e.message, 'error');
+  }
+}
+
+function escHtml(s) {
+  const d = document.createElement('div');
+  d.textContent = s;
+  return d.innerHTML;
+}
+
+function renderMd(text) {
+  if (!text) return '';
+  let h = escHtml(text);
+  h = h.replace(/^### (.+)$/gm, '<h3>$1</h3>');
+  h = h.replace(/^#### (.+)$/gm, '<h4>$1</h4>');
+  h = h.replace(/^---$/gm, '<hr>');
+  h = h.replace(/\*\*(.+?)\*\*/g, '<strong>$1</strong>');
+  h = h.replace(/\*(.+?)\*/g, '<em>$1</em>');
+  h = h.replace(/`([^`]+)`/g, '<code>$1</code>');
+  h = h.replace(/^&gt; (.+)$/gm, '<blockquote>$1</blockquote>');
+  h = h.replace(/^- (.+)$/gm, '<li>$1</li>');
+  h = h.replace(/(<li>.*<\/li>\n?)+/g, m => '<ul>' + m + '</ul>');
+  h = h.replace(/\n{2,}/g, '<br><br>');
+  h = h.replace(/\n/g, '<br>');
+  h = h.replace(/<br>(<h[34]>)/g, '$1');
+  h = h.replace(/(<\/h[34]>)<br>/g, '$1');
+  h = h.replace(/<br>(<hr>)/g, '$1');
+  h = h.replace(/(<hr>)<br>/g, '$1');
+  h = h.replace(/<br>(<ul>)/g, '$1');
+  h = h.replace(/(<\/ul>)<br>/g, '$1');
+  return h;
+}
+
+// ── Quick Eval ────────────────────────────────────────────
+
+let lastBatchFailures = [];
+
+async function runSearchTest() {
+  const query = document.getElementById('eval-query').value.trim();
+  if (!query) return;
+
+  const container = document.getElementById('eval-search-results');
+  container.innerHTML = '<div class="spinner"></div> 검색 중...';
+
+  try {
+    const r = await fetch('/api/admin/eval/search', {
+      method: 'POST',
+      headers: {'Content-Type':'application/json'},
+      body: JSON.stringify({ query, top_k: 5 }),
+    });
+    const d = await r.json();
+
+    container.innerHTML = d.results.map((hit, i) => {
+      const isTarget = hit.name === editName;
+      const cls = isTarget ? 'is-target' : '';
+      const pct = Math.round(hit.score * 100);
+      return `<div class="search-result ${cls}">
+        <div class="rank">${i + 1}</div>
+        <div class="sr-name">${hit.name}</div>
+        <div class="sr-score-wrap">
+          <div class="sr-score">${(hit.score * 100).toFixed(1)}%</div>
+          <div class="sr-bar"><div class="sr-bar-fill" style="width:${pct}%"></div></div>
+        </div>
+        <div class="sr-desc">${escHtml(hit.description)}</div>
+        ${isTarget ? '<span style="color:var(--success);font-weight:700;white-space:nowrap">← 현재 도구</span>' : ''}
+      </div>`;
+    }).join('') || '<div style="color:var(--text-muted);font-size:12px">결과 없음</div>';
+  } catch(e) {
+    container.innerHTML = `<div style="color:var(--danger);font-size:12px">검색 실패: ${e.message}</div>`;
+  }
+}
+
+async function runBatchEval() {
+  const btn = document.getElementById('btn-batch');
+  const recallBar = document.getElementById('eval-recall-bar');
+  const details = document.getElementById('eval-batch-details');
+  btn.disabled = true; btn.innerHTML = '<span class="spinner"></span> 평가 중...';
+  recallBar.innerHTML = ''; details.innerHTML = '';
+  lastBatchFailures = [];
+
+  try {
+    const r = await fetch(`/api/admin/eval/batch/${editName}`, { method: 'POST' });
+    const d = await r.json();
+
+    if (!r.ok) { showToast(d.detail || '평가 실패', 'error'); return; }
+
+    const rc = (v) => v >= 0.9 ? 'good' : v >= 0.7 ? 'ok' : 'bad';
+    recallBar.innerHTML = `
+      <div class="recall-bar">
+        <div class="recall-card">
+          <div class="rc-label">1위 정확도</div>
+          <div class="rc-value ${rc(d.recall_at_1)}">${(d.recall_at_1 * 100).toFixed(0)}%</div>
+          <div class="rc-sub">검색 1위에 나오는 비율</div>
+        </div>
+        <div class="recall-card">
+          <div class="rc-label">Top-3 포함</div>
+          <div class="rc-value ${rc(d.recall_at_3)}">${(d.recall_at_3 * 100).toFixed(0)}%</div>
+          <div class="rc-sub">상위 3개 안에 드는 비율</div>
+        </div>
+        <div class="recall-card">
+          <div class="rc-label">Top-5 포함</div>
+          <div class="rc-value ${rc(d.recall_at_5)}">${(d.recall_at_5 * 100).toFixed(0)}%</div>
+          <div class="rc-sub">상위 5개 안에 드는 비율</div>
+        </div>
+        <div class="recall-card">
+          <div class="rc-label">테스트 수</div>
+          <div class="rc-value" style="color:var(--text)">${d.total}건</div>
+          <div class="rc-sub">등록된 발화 예시 수</div>
+        </div>
+      </div>`;
+
+    lastBatchFailures = d.details.filter(x => !x.pass_at_3);
+
+    details.innerHTML = d.details.map(item => {
+      const pass = item.pass_at_3;
+      const topNames = (item.top_hits || []).slice(0, 3).map(h => h.name).join(', ');
+      return `<div class="batch-detail ${pass ? 'pass' : 'fail'}">
+        <div class="bd-icon">${pass ? '✓' : '✗'}</div>
+        <div class="bd-query">${escHtml(item.query)}</div>
+        <div class="bd-rank">${item.rank ? item.rank + '위' : '—'}</div>
+        <div class="bd-top" title="${topNames}">${topNames}</div>
+      </div>`;
+    }).join('');
+
+    document.getElementById('btn-judge').disabled = lastBatchFailures.length === 0;
+    if (lastBatchFailures.length === 0) {
+      document.getElementById('eval-judge-result').innerHTML =
+        '<div style="color:var(--success);font-size:12px;padding:8px">모든 쿼리가 Top-3에 포함됩니다. LLM 분석이 필요 없습니다.</div>';
+    } else {
+      document.getElementById('eval-judge-result').innerHTML =
+        `<div style="color:var(--warning);font-size:12px;padding:8px">${lastBatchFailures.length}건 실패 — LLM 분석을 실행하세요.</div>`;
+    }
+  } catch(e) {
+    recallBar.innerHTML = `<div style="color:var(--danger);font-size:12px">평가 실패: ${e.message}</div>`;
+  } finally {
+    btn.disabled = false; btn.textContent = '배치 평가 실행';
+  }
+}
+
+async function runLlmJudge() {
+  if (!lastBatchFailures.length) return;
+
+  const btn = document.getElementById('btn-judge');
+  const container = document.getElementById('eval-judge-result');
+  btn.disabled = true; btn.innerHTML = '<span class="spinner"></span> LLM 분석 중...';
+  container.innerHTML = '<div style="font-size:12px;color:var(--text-muted);padding:8px"><span class="spinner"></span> LLM이 실패 원인을 분석하고 있습니다... (10~30초)</div>';
+
+  try {
+    const r = await fetch('/api/admin/eval/judge', {
+      method: 'POST',
+      headers: {'Content-Type':'application/json'},
+      body: JSON.stringify({
+        tool_name: editName,
+        failures: lastBatchFailures,
+      }),
+    });
+    const d = await r.json();
+    container.innerHTML = `<div class="judge-box">${renderMd(d.analysis)}</div>`;
+  } catch(e) {
+    container.innerHTML = `<div style="color:var(--danger);font-size:12px">LLM 분석 실패: ${e.message}</div>`;
+  } finally {
+    btn.disabled = false; btn.textContent = 'LLM 분석 실행';
+  }
+}
+
+// ── Enter key support ─────────────────────────────────────
+['new-wtu','new-wntu','new-tag'].forEach(id => {
+  document.getElementById(id).addEventListener('keydown', e => {
+    if (e.key === 'Enter') {
+      e.preventDefault();
+      if (id === 'new-tag') addTagItem();
+      else addListItem(id.replace('new-',''));
+    }
+  });
+});
+
+document.getElementById('eval-query').addEventListener('keydown', e => {
+  if (e.key === 'Enter') { e.preventDefault(); runSearchTest(); }
+});
+
 document.getElementById('search').addEventListener('input', () => renderTable(allTools));
 
 document.querySelectorAll('.modal-overlay').forEach(el => {