oh-my-llmwikimode 1.0.0

package/docs/stage4-slice1-user-guide.md

@@ -0,0 +1,269 @@
+# Stage 4 Slice 1 — 실사용 가이드 (일상 사용 관점)
+
+> "이 기능이 내 일상에서 어떻게 쓰이는가?" 관점에서 작성했습니다.
+
+---
+
+## 이 기능이 뭔가요?
+
+당신이 위키에 쌓아둔 메모/노트/버그기록 등을 **자동으로 분석**해서 아래처럼 알려줍니다:
+
+- 🏝️ **고립된 메모**: "이 메모는 다른 메모와 연결이 안 되어 있어요"
+- 🔗 **허브 메모**: "이 메모는 너무 많은 메모와 연결되어 있어요"
+- 📦 **묶음 제안**: "이 두 메모는 관련있어 보여요, 정리필요"
+- ⏰ **오래된 메모**: "이 메모는 30일 넘게 방치됐어요"
+
+**중요**: 자동으로 아무것도 수정하지 않습니다. 알림만 주고 **사용자가 직접 판단**합니다.
+
+---
+
+## 설치 및 설정 (처음 한 번)
+
+### 1. 위키 폴드 준비
+
+```powershell
+# 위키 폴드를 만듭니다 (이미 있으면 스킵)
+$wikiRoot = "C:\Users\USER\Documents\llm-wiki"
+New-Item -ItemType Directory -Path "$wikiRoot\inbox" -Force
+New-Item -ItemType Directory -Path "$wikiRoot\problems" -Force
+New-Item -ItemType Directory -Path "$wikiRoot\editorial\lessons" -Force
+```
+
+### 2. llmwiki CLI 확인
+
+```powershell
+cd C:\Users\USER\Desktop\OpenCode_Modes\plugins\oh-my-llmwikimode
+
+# 버전 확인
+node bin/llmwiki.js --help
+# 출력에 "stage4"가 보이면 OK
+```
+
+### 3. 환경 변수 등록 (선택)
+
+매번 긴 경로 치기 귀찮으면:
+
+```powershell
+# PowerShell 프로필에 추가
+notepad $PROFILE
+
+# 아래 내용 추가:
+function llmwiki {
+    node "C:\Users\USER\Desktop\OpenCode_Modes\plugins\oh-my-llmwikimode\bin\llmwiki.js" @args
+}
+```
+
+이제 `llmwiki stage4 graph-reasoning analyze`처럼 간단히 사용 가능합니다.
+
+---
+
+## 일상 사용 시나리오
+
+### 시나리오 1: 주말 위키 정리 타임
+
+**언제**: 주말 아침, 위키를 정리하고 싶을 때
+
+**무엇을**:
+```powershell
+# 1. 그래프 최신화 (새로 추가한 메모 반영)
+llmwiki rebuild
+
+# 2. 분석 실행
+llmwiki stage4 graph-reasoning analyze
+
+# 3. 결과 확인
+llmwiki stage4 graph-reasoning list --json
+```
+
+**결과 해석**:
+```json
+{
+  "graph_reasoning": {
+    "insights": [
+      {
+        "id": "insight-orphaned-...",
+        "kind": "orphaned_entry_review",
+        "title": "Review isolated entry: 메모1",
+        "artifact_path": ".system/stage4/graph-reasoning/insights/..."
+      }
+    ]
+  }
+}
+```
+
+**행동**:
+- orphaned → "이 메모에 링크를 추가할까?" 고민
+- high_connectivity → "이 메모가 너무 중심이네, 정리가 필요한가?"
+- stale → "이 메모 오래됐는데, 아직 유효한가?"
+
+---
+
+### 시나리오 2: 새 메모를 추가한 후
+
+**언제**: 새 메모를 추가한 직후
+
+**무엇을**:
+```powershell
+# 새 메모 추가
+llmwiki ingest --stdin --title "새로운 아이디어"
+# Ctrl+V로 내용 붙여넣기 → Ctrl+D (또는 Ctrl+Z Enter)
+
+# 그래프 리빌드
+llmwiki rebuild
+
+# 이 새 메모가 어디에 연결될 수 있는지 분석
+llmwiki stage4 graph-reasoning analyze
+```
+
+**기대 효과**:
+- "새 메모"가 orphaned로 잡히면 → 다른 메모와 연결 필요
+- 기존 메모들 중 연결 가능한 게 있으면 → backlog_cluster로 제안됨
+
+---
+
+### 시나리오 3: 큐레이터 워크벤치와 함께 사용
+
+**언제**: Stage 3 큐레이터에서 "이 메모를 레슨으로 승격할까?" 고민할 때
+
+**무엇을**:
+```powershell
+# 큐레이터 queue 확인
+llmwiki curator list --json
+
+# 그래프 분석 (이 메모가 위키에서 얼마나 중요한지 확인)
+llmwiki stage4 graph-reasoning analyze
+```
+
+**결과 해석**:
+- high_connectivity로 잡힌 메모 → 레슨으로 승격 가치 있음
+- orphaned로 잡힌 메모 → 더 많은 연결 필요, 아직 레슨 아님
+
+---
+
+### 시나리오 4: 월간 위키 건강 체크
+
+**언제**: 매월 1일, 위키 전체 상태 파악
+
+**무엇을**:
+```powershell
+# 분석 실행
+llmwiki stage4 graph-reasoning analyze --json | ConvertFrom-Json
+
+# 결과를 변수에 저장해서 통계 확인
+$result = llmwiki stage4 graph-reasoning list --json | ConvertFrom-Json
+
+# 통계 출력
+Write-Host "총 Insight: $($result.graph_reasoning.summary.insight_count)"
+Write-Host "고립된 메모: $($result.graph_reasoning.insights | Where-Object { $_.kind -eq 'orphaned_entry_review' }).Count"
+Write-Host "허브 메모: $($result.graph_reasoning.insights | Where-Object { $_.kind -eq 'high_connectivity_review' }).Count"
+Write-Host "오래된 메모: $($result.graph_reasoning.insights | Where-Object { $_.kind -eq 'stale_review_candidate' }).Count"
+```
+
+---
+
+## 결과 해석 가이드
+
+### Insight 종류별 의미
+
+| 종류 | 제목 예시 | 의미 | 내가 할 일 |
+|------|-----------|------|------------|
+| `orphaned_entry_review` | "Review isolated entry: 메모1" | 이 메모는 아물와 연결 안 됨 | 다른 메모와 링크 연결 검토 |
+| `high_connectivity_review` | "Review highly connected entry: 메모2" | 이 메모는 너무 많이 연결됨 | 과잉 연결 정리 필요 |
+| `curator_backlog_cluster` | "Review related curator cards: A / B" | 큐레이터 큐에 관련 메모 2개 | 통합/정렬 검토 |
+| `stale_review_candidate` | "Review stale candidate: 메모3" | 7일 넘게 업데이트 안 됨 | 내용 갱신 또는 상태 변경 |
+
+### Browser Data 확인 (VS Code 확장 사용 시)
+
+VS Code 확장이 설치되어 있다면, 명령 팔레트에서:
+
+```
+LLM Wiki: Stage 4 Graph Reasoning
+```
+
+현재는 UI가 없으므로, 터미널에서 확인:
+
+```powershell
+# browser-data.json에서 stage4 섹션만 보기
+Get-Content "$env:USERPROFILE\Documents\llm-wiki\.system\browser-data.json" | 
+    ConvertFrom-Json | 
+    Select-Object -ExpandProperty stage4_graph_reasoning
+```
+
+---
+
+## 실패했을 때
+
+### "insight_count: 0"이 나와요
+
+- 위키 항목이 3개 미만 → 더 추가하세요
+- `rebuild` 안 했음 → `llmwiki rebuild` 먼저 실행
+- 모든 메모가 서로 연결됨 → 고립된 게 없어서 orphaned 안 나옴 (정상)
+
+### 명령어가 안 먹어요
+
+```powershell
+# 프로젝트 폴드로 이동했는지 확인
+cd C:\Users\USER\Desktop\OpenCode_Modes\plugins\oh-my-llmwikimode
+
+# Node.js 설치 확인
+node --version
+# v18 이상 필요
+```
+
+### 권한 에러가 나요
+
+```powershell
+# 위키 폴드 권한 확인
+$wiki = "$env:USERPROFILE\Documents\llm-wiki"
+Test-Path "$wiki\.system"  # false면 권한 문제
+```
+
+---
+
+## 팁
+
+### 1. 매일 아침 간단히 확인
+
+```powershell
+# PowerShell 프로필에 함수 등록핸 경우
+function wiki-health {
+    cd C:\Users\USER\Desktop\OpenCode_Modes\plugins\oh-my-llmwikimode
+    llmwiki rebuild | Out-Null
+    $result = llmwiki stage4 graph-reasoning analyze --json | ConvertFrom-Json
+    Write-Host "오늘의 Insight: $($result.insight_count)개" -ForegroundColor Green
+}
+```
+
+### 2. 결과를 파일로 저장
+
+```powershell
+llmwiki stage4 graph-reasoning list --json | 
+    Out-File "$env:USERPROFILE\Documents\llm-wiki\.system\weekly-report.json"
+```
+
+### 3. 특정 종류만 필터링
+
+```powershell
+# orphaned만 보기
+llmwiki stage4 graph-reasoning list --json | 
+    ConvertFrom-Json | 
+    Select-Object -ExpandProperty graph_reasoning | 
+    Select-Object -ExpandProperty insights | 
+    Where-Object { $_.kind -eq 'orphaned_entry_review' }
+```
+
+---
+
+## 다음 단계
+
+이 가이드대로 일상적으로 써보시고, 아래 중 필요한 것을 말씀해주세요:
+
+1. **잘못된 insight가 너무 많이 나와요** → 임계값 조정 (ex: 고립 판정 기준 변경)
+2. **원하는 분석이 안 나와요** → 새로운 규칙 추가 (ex: 특정 태그끼리 묶기)
+3. **VS Code에서 보고 싶어요** → Slice 2: UI 워크벤치 구현
+4. **자동으로 주기적으로 분석하고 싶어요** → 스케줄러 연동 가이드
+
+---
+
+*문서 버전: Stage 4 Slice 1 (2026-05-08)*  
+*GitHub: https://github.com/wjdtmddn325-maker/oh-my-llmwikimode*