oh-my-llmwikimode 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 oh-my-llmwikimode
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,494 @@
+# oh-my-llmwikimode
+
+> **AI-Powered Local Wiki Knowledge Workbench for OpenCode** — 당신이 말하면 AI가 알아서 위키를 검색하고, 저장하고, 정리합니다.
+
+## 개요
+
+oh-my-llmwikimode는 OpenCode 플러그인으로, **채팅으로 자연어를 말하기만 하면** AI가 알아서 로컬 위키를 관리합니다.
+
+CLI 명령어를 외울 필요 없습니다. OpenCode 채팅창에서 말하기만 하세요.
+
+---
+
+## 설치 (AI가 자동으로)
+
+### 방법 1: 채팅으로 설치 (권장)
+
+OpenCode 채팅창에서 말하세요:
+
+> "oh-my-llmwikimode 플러그인 설치해줘"
+
+AI가 자동으로 플러그인을 다운로드하고 설정합니다.
+
+### 방법 2: 수동 설치
+
+```bash
+npm install oh-my-llmwikimode
+```
+
+`opencode.json` 예시:
+
+```json
+{
+  "plugin": [
+    ["oh-my-llmwikimode", {
+      "wikiRoot": "~/Documents/llm-wiki",
+      "autoMemoryEnabled": true,
+      "autoSearchEnabled": true
+    }]
+  ]
+}
+```
+
+### 설치 후 확인
+
+> "내 위키 상태 확인해줘"
+
+AI가 위키 폴드를 만들고 상태를 보고합니다.
+
+---
+
+## 사용법 — 채팅으로 말하기만 하세요
+
+### 1. 지식 검색
+
+**당신이 말하는 것:**
+> "Docker Compose 볼륨 오류가 나는데, 전에 비슷한 문제 해결한 기록 있어?"
+
+**AI가 뒤에서 하는 것:**
+```
+wiki_search(query="docker compose volume error", max_results=3)
+```
+
+**결과:**
+- 위키에서 관련 메모를 찾아서 보여줌
+- 메모의 제목, 태그, 상태, 내용 요약을 제시
+- "이 메모를 참고하세요" 형태로 제안
+
+---
+
+### 2. 지식 저장
+
+**당신이 말하는 것:**
+> "방금 해결한 이 방법을 다음에도 참고할 수 있게 저장해줘"
+
+**AI가 뒤에서 하는 것:**
+```
+wiki_store(summary="Docker Compose stale volume 해결", 
+           details="docker compose down -v 실행 후 재시작", 
+           tags=["docker", "compose", "troubleshooting"])
+```
+
+**결과:**
+- `inbox/` 폴드에 마크다운 파일로 저장
+- 자동으로 색인 생성
+- "저장 완료: inbox/2026-05-08-docker-compose-stale-volume.md" 알림
+
+---
+
+### 3. 메모 정리 및 승격
+
+**당신이 말하는 것:**
+> "inbox에 있는 Docker 메모를 레슨으로 올려줘"
+
+**AI가 뒤에서 하는 것:**
+```
+wiki_promote(path="inbox/2026-05-08-docker-compose-stale-volume.md")
+```
+
+**결과:**
+- `editorial/lessons/`로 이동
+- 상태가 `candidate` → `lesson`으로 변경
+- "승격 완료: editorial/lessons/docker-compose-stale-volume.md" 알림
+
+---
+
+### 4. 위키 전체 분석 (Stage 4)
+
+**당신이 말하는 것:**
+> "내 위키에서 연결 안 된 메모들 찾아줘"
+
+**실행 방법 (CLI 전용):**
+```
+npx llmwiki stage4 graph-reasoning analyze
+```
+
+> **참고**: graph reasoning은 CLI로만 사용할 수 있습니다. OpenCode 도구로는 등록되어 있지 않습니다.
+
+**결과:**
+- 고립된 메모 목록
+- "이 메모들은 다른 메모와 연결이 없습니다. 링크를 추가하시겠어요?"
+
+---
+
+### 5. 큐레이터 작업
+
+**당신이 말하는 것:**
+> "이 두 메모를 하나로 통합 검토해줘"
+
+**AI가 뒤에서 하는 것:**
+```
+wiki_curator_propose_consolidation(
+  entries=["inbox/memo1.md", "inbox/memo2.md"],
+  rationale="중복 내용 통합 검토"
+)
+```
+
+**결과:**
+- 큐레이터 대기열에 통합 제안 추가
+- 사용자가 승인해야 실제 통합됨 (자동 실행 안 됨)
+
+---
+
+### 6. 주간 요약 (Weekly Digest)
+
+**당신이 말하는 것:**
+> "이번 주 위키 요약해줘"
+
+**실행 방법 (CLI 전용):**
+```bash
+npx llmwiki digest generate
+npx llmwiki digest list --json
+npx llmwiki digest show digest_2026-05-09
+```
+
+**결과:**
+- 고립된 메모, 중복 의심 항목, 승격 제안, 방치 메모 분석
+- `.system/digests/`에 아티팩트로 저장
+- 사용자가 검토 후 직접 조치
+
+> **참고**: Weekly Digest는 Librarian AI가 위키 건강 상태를 분석하는 CLI 전용 기능입니다.
+
+---
+
+## 일상 사용 시나리오
+
+### 시나리오 1: 문제 해결 중 지식 재사용
+
+**당신:** "Spring Boot에서 CORS 오류가 나는데..."
+
+**AI:**
+1. 위키 검색: `wiki_search("spring boot cors error")`
+2. 관련 메모 발견: "2026-03-15-spring-cors-config.md"
+3. 해결책 제시: "이 메모에 WebMvcConfigurer 설정이 있어요. 참고하시겠어요?"
+4. 해결 후: "이번에 새로 알게된 점을 저장할까요?"
+
+### 시나리오 2: 주간 위키 정리
+
+**당신:** "이번 주에 쌓인 메모들 정리해줘"
+
+**AI:**
+1. 분석 실행: orphaned, stale, high-connectivity 검출
+2. 보고: "3개 메모가 고립 상태, 2개가 30일 이상 방치됨"
+3. 제안: "이 메모들을 연결하거나 레슨으로 승격하시겠어요?"
+
+### 시나리오 3: 간단한 TODO 관리 (기본)
+
+**당신:** "이번 주 할 일로 문서 작성 작업 만들어줘"
+
+**AI:**
+1. TODO 생성: `npx llmwiki todo add "문서 작성" --project docs --tags urgent`
+2. 진행 추적: `npx llmwiki todo list --project docs`
+3. 완료 처리: `npx llmwiki todo done "문서 작성"`
+
+> **참고**: Simple TODO가 기본 작업 관리 방식입니다. Agent Team Kanban(`team` 명령)은 **deprecated** 호환 기능이며, 새 작업에는 `todo`를 사용하세요.
+
+### 시나리오 4: NotebookLM 연구 결과 통합
+
+**당신:** "NotebookLM에서 뽑은 React Hooks 리포트를 위키에 넣어줘"
+
+**AI:**
+1. 파일 확인: "C:\Users\USER\Downloads\notebooklm-export 경로가 맞나요?"
+2. 가져오기: `notebooklm_llmwikiflow(input_path, title="React Hooks Research")`
+3. 결과: "3개 파일을 가져왔습니다. inbox에 후보 항목이 생성되었습니다."
+
+---
+
+## 고급: CLI 직접 사용 (선택)
+
+AI가 처리해주지만, 직접 제어하고 싶을 때:
+
+```bash
+# 위키 상태 점검
+npx llmwiki lint
+
+# 코어 상태 점검과 dry-run migration plan
+npx llmwiki doctor --json
+
+# 검색 (그래프 확장)
+npx llmwiki query "docker compose error"
+
+# 파일 가져오기
+npx llmwiki ingest /path/to/file.md
+
+# 원본 자료 가져오기 (CLI 전용, 자동 승격 없음)
+npx llmwiki source-ledger import /path/to/source.md --title "Docker evidence"
+npx llmwiki source-ledger list --json
+npx llmwiki source-ledger search "docker" --json
+
+# 그래프 리빌드
+npx llmwiki rebuild
+
+# Simple TODO (기본 작업 관리)
+npx llmwiki todo add "문서 작성" --project backend --tags urgent
+npx llmwiki todo list --project backend --json
+npx llmwiki todo done "문서 작성"
+npx llmwiki todo remove "문서 작성"
+
+# Weekly Digest (Librarian AI)
+npx llmwiki digest generate
+npx llmwiki digest list --json
+npx llmwiki digest show digest_2026-05-09
+
+# Stage 4 분석
+npx llmwiki stage4 graph-reasoning analyze
+
+# 검색 피드백 (선택적, B1/B2 sidecar)
+npx llmwiki search-feedback list --json
+npx llmwiki search-feedback record --query "docker volume reset" --result-count 0 --json
+npx llmwiki search-feedback suggest-aliases --json
+```
+
+> **참고**: `search-feedback`는 검색 실패를 기록하고 alias 제안을 생성하는 **선택적** CLI 전용 기능입니다. 제안은 `review_required` 상태로 생성되며 자동으로 적용되지 않습니다.
+
+> **참고**: 대부분의 사용자는 CLI를 사용할 필요가 없습니다. 채팅으로 충분합니다.
+
+### Simple TODO (기본 작업 관리)
+
+`todo`는 Agent Team Kanban보다 단순한 기본 작업 관리 기능입니다.
+
+- TODO는 `.system/todos.json`에 versioned JSON으로 저장됩니다.
+- 사용자가 명시적으로 `todo add`를 실행할 때만 TODO가 생성됩니다.
+- `add`, `done`, `remove` 후에는 `.system/browser-data.json`이 갱신됩니다.
+- 기존 `team` 명령은 deprecated 호환 기능으로 남아 있지만, 새 작업에는 `todo`를 권장합니다.
+
+```bash
+npx llmwiki todo add "문서 작성" --project backend --tags urgent
+npx llmwiki todo list --project backend --json
+npx llmwiki todo done todo_abc123
+npx llmwiki todo remove "문서 작성"
+```
+
+### 반복 패턴 자동 lesson 제안 (B1 Auto Lesson Proposal)
+
+`lesson-proposal`은 사용자가 반복해서 검색하거나 참조하는 주제를 자동으로 감지하여 lesson 제안을 생성하는 CLI 전용 기능입니다.
+
+- 제안은 `.system/lesson-proposals/`에 JSON 아티팩트로 저장됩니다.
+- 모든 제안은 `review_required` 상태로 생성되며, **자동으로 승격되지 않습니다**.
+- 원본 항목(inbox/ 문제 메모 등)은 절대 수정되지 않습니다.
+- frontmatter에 `used_count`, `last_used` 등을 기록하지 않습니다.
+
+```bash
+# usage event 분석 후 lesson 제안 생성
+npx llmwiki lesson-proposal analyze
+
+# 현재 제안 목록 조회
+npx llmwiki lesson-proposal list --json
+
+# 특정 제안 상세 보기
+npx llmwiki lesson-proposal show lp_abc123
+
+# 사용자 승인 후 lesson으로 승격
+npx llmwiki lesson-proposal apply lp_abc123
+```
+
+### 검색 피드백 및 Alias 제안 (Search Feedback)
+
+`search-feedback`는 검색 실패를 안전하게 기록하고 review-only alias suggestion을 생성하는 CLI 전용 기능입니다.
+
+- 실패한 검색어는 `.system/search-feedback/failures.jsonl`에 append-only로 저장됩니다.
+- API 키, 토큰, 비밀번호는 저장 전 자동으로 마스킹됩니다.
+- `search-feedback suggest-aliases`는 기존 alias/title과 중복되지 않는 제안만 생성합니다.
+- 제안은 `.system/search-feedback/suggestions/`에 `review_required` 상태로 저장되며, **자동으로 적용되지 않습니다**.
+- Markdown entry frontmatter는 변경되지 않습니다.
+
+### 원본 자료 창고 (Source Ledger)
+
+`source-ledger`는 검토되지 않은 원본 자료를 `raw/sources/`에 보관하는 CLI 전용 기능입니다.
+
+- 원본 자료는 `raw/sources/ledger.jsonl`과 `raw/sources/files/{source_id}/`에 저장됩니다.
+- 자료를 가져와도 `inbox/`, `problems/`, `editorial/lessons/`는 자동으로 변경되지 않습니다.
+- `source-ledger search` 결과는 `review_status: "raw_evidence"`로 표시되며, 검토된 지식(`wiki_search` 결과)과 구분됩니다.
+- 원본 자료를 위키 지식으로 변환하려면 명시적으로 `wiki_ingest`나 수동 편집을 사용해야 합니다.
+
+### 원본 자료 통합 관리 (Raw Folder)
+
+`raw/`는 원본 자료와 외부 가져오기를 통합 관리하는 공간입니다. 3개 하위 시스템이 공존합니다:
+
+```text
+raw/
+├── sources/              # Source Ledger 원본 자료
+│   ├── ledger.jsonl
+│   └── files/{source_id}/
+├── notebooklm/           # NotebookLM 가져오기 결과
+│   └── imports/{run_id}/
+└── packs/                # Knowledge Pack 원본
+    └── {pack_id}/{version}/
+```
+
+**CLI 명령어:**
+
+```bash
+# 전체 raw 항목 목록
+npx llmwiki raw list --json
+
+# raw 통계 요약
+npx llmwiki raw status --json
+
+# raw 구조 검증 (malformed pack 감지)
+npx llmwiki raw validate --json
+```
+
+- `raw list`는 source-ledger, notebooklm imports, packs를 카테고리별로 보여줍니다.
+- `raw status`는 파일 수와 바이트 수를 카테고리별로 집계합니다.
+- `raw validate`는 `raw/` 디렉터리 구조를 검증하고 malformed pack을 감지합니다 (버전 디렉터리 누락, manifest.json 누락 등).
+- 모든 raw 조회는 read-only이며 curated 영역(inbox/problems/lessons)을 변경하지 않습니다.
+
+---
+
+### 6. 프로젝트별 지식 분류
+
+**당신이 말하는 것:**
+> "이 Docker 설정은 'my-web-project' 프로젝트에 저장해줘"
+
+**AI가 뒤에서 하는 것:**
+```
+wiki_store(summary="Docker Compose 설정", 
+           details="...",
+           tags=["docker"],
+           project="my-web-project")
+```
+
+**결과:**
+- `projects/my-web-project/inbox/` 폴드에 저장
+- 프로젝트별로 지식이 분리되어 관리됨
+- "my-web-project 관련 메모 보여줘"라고 검색 가능
+
+---
+
+## 프로젝트별 지식 관리
+
+프로젝트별로 지식을 분리하여 관리할 수 있습니다. 이는 여러 프로젝트를 동시에 진행할 때 유용합니다.
+
+### 위키 폴드 구조
+
+```text
+~/Documents/llm-wiki/
+├── inbox/                    # 기본 메모 (프로젝트 미지정)
+├── problems/
+├── editorial/
+│   └── lessons/
+├── projects/                 # 프로젝트별 지식
+│   ├── my-web-project/
+│   │   ├── inbox/
+│   │   ├── problems/
+│   │   └── editorial/
+│   │       └── lessons/
+│   └── another-project/
+│       ├── inbox/
+│       ├── problems/
+│       └── editorial/
+│           └── lessons/
+├── raw/
+└── .system/
+```
+
+### 채팅으로 사용하기
+
+**저장:**
+> "이 메모를 'backend-api' 프로젝트에 저장해줘"
+
+**검색:**
+> "backend-api 프로젝트에서 Docker 관련 메모 찾아줘"
+
+**프로젝트 지정 없이 저장:**
+> "이 메모 저장해줘" (기본 inbox/에 저장됨)
+
+### CLI로 사용하기
+
+```bash
+# 파일을 프로젝트 지정하여 가져오기
+npx llmwiki ingest /path/to/memo.md --project my-web-project --tags docker,compose
+
+# 전체 위키 검색 (프로젝트 필터는 그래프 확장 검색에서 자동 적용)
+npx llmwiki query "docker" --json
+
+# 특정 프로젝트 폴드 구조 확인
+ls ~/Documents/llm-wiki/projects/my-web-project/
+
+# 전체 인덱스 재생성 (프로젝트 포함)
+npx llmwiki rebuild
+```
+
+### 동작 방식
+
+- **저장**: `project`를 지정하면 `projects/{project}/inbox/`에 저장됩니다.
+- **검색**: `project`를 지정하면 해당 프로젝트 내에서만 검색합니다.
+- **인덱스**: 프로젝트별 인덱스는 `.system/index.json`에 통합되어 있어, 프로젝트 지정 여부에 따라 필터링됩니다.
+- **역호환**: 기존 메모(프로젝트 미지정)는 그대로 `inbox/`에 저장되며, 프로젝트별 메모와 공존합니다.
+
+---
+
+## 설정 옵션
+
+| 옵션 | 기본값 | 설명 |
+|------|--------|------|
+| `wikiRoot` | `~/Documents/llm-wiki` | 위키 폴드 경로 |
+| `autoMemoryEnabled` | `true` | 문제 해결 대화 자동 캡처 |
+| `autoSearchEnabled` | `true` | 시스템 프롬프트에 위키 규칙 주입 |
+| `contextBudget` | `2500` | 검색 결과 최대 문자 수 |
+| `maxEntries` | `3` | 기본 검색 결과 수 |
+
+---
+
+## 보안 및 프라이버시
+
+- **자동 캡처**: 문제 해결 대화만 캡처, 일반 대화는 무시
+- **비밀 정보 마스킹**: API 키, 토큰, 비밀번호 자동 삭제 후 저장
+- **신뢰 경계**: 검색 결과는 "신뢰할 수 없는 참고 자료"로 표시되며, 내부 컨텍스트에는 `untrusted reference knowledge` 경계가 포함됩니다.
+- **제외 상태**: `rejected`, `superseded`, `needs-clarification`, `private` 항목은 검색 제외
+- **자동 승격 금지**: 모든 승격/통합/삭제는 사용자 승인 필요
+
+### 로컬 상태 디렉터리
+
+플러그인의 로컬 런타임 상태는 기본적으로 `~/.config/opencode/.llmwikimode/` 아래에 저장됩니다. 위키 원문은 `wikiRoot`에 남고, 상태 디렉터리는 OpenCode 통합에 필요한 보조 데이터만 보관합니다.
+
+---
+
+## 기능 로드맵
+
+| 단계 | 기능 | 상태 |
+|------|------|------|
+| Stage 1 | 자동 메모리, 검색, 저장, 승격 | ✅ 완료 |
+| Stage 2 | 에이전트 팀 작업 관리 | ✅ 완료 (deprecated → Simple TODO로 전환) |
+| Stage 3 | 큐레이터 검토 및 제안 | ✅ 완료 |
+| Stage 4 | 그래프 추론 분석 | ✅ 완료 |
+| Phase 1 | Weekly Digest (Librarian) | ✅ 완료 |
+| Phase 1 | Simple TODO (기본 작업 관리) | ✅ 완료 |
+| Phase 1 | 설치 자동화 (`llmwiki init`) | ✅ 완료 |
+| Phase 1 | Search Feedback + Alias | ✅ 완료 (optional) |
+
+---
+
+## 문제 해결
+
+### "위키를 찾을 수 없어요"
+- 위키 폴드가 생성되지 않음 → "위키 폴드 만들어줘"라고 말하세요
+
+### "검색 결과가 안 나와요"
+- 위키에 메모가 없음 → 먼저 몇 개 메모를 저장하세요
+- 그래프가 오래됨 → "위키 그래프 리빌드해줘"라고 말하세요
+
+### "자동 캡처가 안 돼요"
+- `autoMemoryEnabled: false`로 설정됨 → 설정 확인
+- 프라이버시 옵트아웃 문구 감지 → "private", "저장하지 마" 등의 단어가 포함된 경우 스킵
+
+---
+
+## 라이선스
+
+MIT
+
+## 릴리스
+
+패키지 릴리스 자동화는 semantic-release 기준을 따릅니다. 실제 GitHub/npm 배포는 별도 승인 절차 이후에만 진행합니다.