Merge pull request #19 from CommitTheKermit/docs/keybuddy-docs-root

docs: keybuddy 기술 문서를 레포 루트 docs/로 일원화

Author: CommitTheKermit

…dy/docs/deployment-version-management.md docs/deployment-version-management.mdimpl/keybuddy/docs/deployment-version-management.md renamed to docs/deployment-version-management.md impl/keybuddy/docs/deployment-version-management.md renamed to docs/deployment-version-management.md

@@ -6,7 +6,7 @@
 
 - `impl/keybuddy/README.md`
   - `## 배포` 섹션에 앱 버전 단일 소스, 버전 증가 방식, Supabase Edge Function 배포 및 버전 확인 방법을 반영했습니다.
-- `impl/keybuddy/docs/deployment-version-management.md`
+- `docs/deployment-version-management.md`
   - 이 파일입니다. 어떤 내용을 어디에 기록했는지와 코드 변경 이유를 별도로 정리합니다.
 
 대화에서 언급된 Firebase 프로젝트 `socratic-learn-web` 관련 배포 절차는 이 저장소의 실제 배포 대상이 아니므로 그대로 적용하지 않았습니다. 대신 해당 프로젝트의 원칙 중 “배포할 때마다 SemVer 기준으로 단일 버전을 올린다”는 부분만 Supabase Edge Function 구조에 맞게 적용했습니다.

…/keybuddy/intent-harness-before-after.md docs/intent-harness-before-after.mdimpl/keybuddy/intent-harness-before-after.md renamed to docs/intent-harness-before-after.md impl/keybuddy/intent-harness-before-after.md renamed to docs/intent-harness-before-after.md

@@ -1,5 +1,8 @@
 # 의도 하네싱 전/후 비교 (AC8 정성 리포트)
 
+> **상태: 미연결 클라이언트 설계의 검증 리포트.** 이 비교는 현재 배포 추천 경로(Supabase + OpenAI)가 아니라
+> 앱에 미연결된 클라이언트 의도 하네싱 설계를 대상으로 한다. 배경은 루트 `AGENTS.md`와 [`tag-extraction-flow.md`](tag-extraction-flow.md) 참조.
+
 평면 추출(의도=평면 소프트 태그, 점수만)과 의도 하네싱(의도->차원별 강도, 필수=하드 승격)을 대표 쿼리 10개로 비교한다. 추출값은 결정론적으로 고정(LLM 미사용).
 
 핵심 지표 = **BEFORE 상위 5개 중 의도 필수 차원 위반 수**(예: 사무용->저소음 필수인데 시끄러운 기계식이 상위에 노출된 건수). AFTER는 필수를 하드 필터로 승격하므로, 완화가 일어나지 않은 한 0이 된다. 필수끼리 모순돼 완화된 경우에만 완화된 필수에 대한 위반이 남으며 이는 설계상 의도된 동작이다(무결과 대신 근접 제시).

impl/keybuddy/docs/tag-extraction-flow.md docs/tag-extraction-flow.mdimpl/keybuddy/docs/tag-extraction-flow.md renamed to docs/tag-extraction-flow.md

@@ -1,6 +1,12 @@
 # 자연어 → 태그 추출 플로우
 
-keybuddy 추천은 **2단계 분리** 구조입니다.
+> **상태: 미연결 클라이언트 설계 기록.** 현재 배포된 추천 경로는 이 문서가 아니라
+> Supabase Edge Function + OpenAI(`gpt-5.4`) 서버사이드다(루트 `AGENTS.md`의 "아키텍처: 두 개의 추천 경로",
+> `impl/keybuddy/README.md` 참조). 아래 의도 하네싱(`extractIntentInput`/`expandIntents`/`searchWithProfile`)은
+> `impl/keybuddy/frontend/src/lib/`에 코드·테스트로 존재하나 앱 진입점(`App.tsx → lib/recommend.ts`)에
+> 연결돼 있지 않다. 이 문서의 코드 경로는 `impl/keybuddy/frontend/` 기준이다.
+
+이 설계에서 추천은 **2단계 분리** 구조입니다.
 
 - **LLM은 자연어를 "의도 + 명시 제약"으로 번역만** 합니다.
 - 그걸 **태그로 펼치고 검색하는 건 전부 결정론**입니다 (LLM 호출 0회).
@@ -173,4 +179,4 @@ LLM이 정숙 요구를 `경쾌함`으로 잘못 섞는 것을 1차로 차단합
 | `src/lib/searchEngine.ts` | 하드 필터·완화 순서 등 코어(미수정, 조합만) |
 | `src/lib/recommend.ts` | 전체 오케스트레이션 + 개발 콘솔 로그 |
 
-검증/비교: [`../intent-harness-before-after.md`](../intent-harness-before-after.md) (전/후 정성 리포트)
+검증/비교: [`intent-harness-before-after.md`](intent-harness-before-after.md) (전/후 정성 리포트)

impl/keybuddy/README.md

@@ -4,7 +4,7 @@
 추천해 주는 웹 서비스입니다.
 
 브라우저에서 OpenAI API를 직접 호출하지 않고, Supabase Edge Function이 서버사이드에서
-OpenAI를 호출합니다. Edge Function에서 먼저 후보를 25개 이하로 압축한 뒤 추천 품질을
+OpenAI를 호출합니다. Edge Function에서 먼저 후보를 40개 이하로 압축한 뒤 추천 품질을
 위해 `gpt-5.4` 모델에 넘깁니다.
 
 ## 구조
@@ -27,6 +27,14 @@ keybuddy/
         keyboards.json              추천 후보 카탈로그
 ```
 
+## 더 읽을거리 (기술 문서)
+
+설계·운영 관련 기술 문서는 저장소 루트 `docs/`에 모여 있습니다.
+
+- `docs/tag-extraction-flow.md` - 자연어를 의도/제약 태그로 번역하고 결정론적으로 확장하는 흐름
+- `docs/intent-harness-before-after.md` - 의도 하네스 적용 전/후 정성 비교
+- `docs/deployment-version-management.md` - 배포 및 버전 관리 규칙
+
 ## 크롤링 데이터와 스위치 매칭
 
 `../crawl.py`는 상세 페이지를 열지 않고 다나와 키보드 목록만 조회합니다. 같은 상품에
@@ -56,7 +64,7 @@ keybuddy/
 React 브라우저
   -> Supabase Edge Function /recommend
   -> OPENAI_API_KEY secret 읽기
-  -> 후보 25개 이하로 압축
+  -> 후보 40개 이하로 압축
   -> OpenAI gpt-5.4 모델 호출
   -> catalog index 기반 추천 JSON 반환
   -> 프론트가 결과 렌더링
@@ -347,7 +355,7 @@ npm run sync:data
 - `VITE_` 환경변수는 브라우저 번들에 포함됩니다.
 - `OPENAI_API_KEY`는 Supabase secret으로만 저장합니다.
 - 기본 모델은 추천 품질을 고려해 `gpt-5.4`로 설정합니다.
-- Edge Function은 LLM 호출 전에 후보를 25개 이하로 줄여 입력 토큰을 줄입니다.
+- Edge Function은 LLM 호출 전에 후보를 40개 이하로 줄여 입력 토큰을 줄입니다.
 - `recommend` 함수에는 IP 기준 1분 10회 best-effort rate limit을 둡니다.
 - `recommend` 함수는 공개 엔드포인트이므로 운영 시 Supabase Dashboard의 Edge
   Functions rate limit 또는 별도 인증/사용량 제한을 반드시 설정합니다.