oh-my-llmwikimode 1.0.0

package/docs/INSTALLATION.md

@@ -0,0 +1,228 @@
+# LLM Wiki Installation Guide
+
+This guide sets up `oh-my-llmwikimode` for OpenCode with a local wiki at `~/Documents/llm-wiki`.
+
+The installer only writes inside your user profile. It does not need administrator privileges, does not install global packages, and does not start OpenCode for you. Restart OpenCode after changing `opencode.json`.
+
+## Local checkout CLI commands
+
+This repository is usually tested from a local checkout before npm publication. In that mode, do not use `npx llmwiki --help`; it can fail if `llmwiki` is not published in the npm registry yet.
+
+Use the package-local command instead:
+
+```sh
+npm --prefix plugins/oh-my-llmwikimode exec -- llmwiki --help
+```
+
+For other CLI examples in this guide, replace `npx llmwiki <args>` with `npm --prefix plugins/oh-my-llmwikimode exec -- llmwiki <args>` when working from the workspace root.
+
+## Prerequisites
+
+- Node.js 18 or newer.
+- OpenCode installed and able to read `opencode.json`.
+- The `oh-my-llmwikimode` package available through npm, a local checkout, or your team's package source.
+- A writable user config directory:
+  - Windows: `%USERPROFILE%\.config\opencode\opencode.json`
+  - macOS/Linux: `~/.config/opencode/opencode.json`
+
+Default plugin config:
+
+```json
+{
+  "plugin": [
+    ["oh-my-llmwikimode", {
+      "wikiRoot": "~/Documents/llm-wiki",
+      "autoMemoryEnabled": true,
+      "autoSearchEnabled": true
+    }]
+  ]
+}
+```
+
+## Method 1: AI Prompt + `llmwiki init` (Recommended)
+
+The fastest way to install is to ask an AI assistant (OpenCode, Claude, etc.) to set it up for you.
+
+### AI-facing installation prompt
+
+Copy and paste this prompt into your AI assistant:
+
+```
+Install the oh-my-llmwikimode OpenCode plugin for me. Steps:
+
+1. Run: npx llmwiki init --wiki-root ~/Documents/llm-wiki
+2. The init command creates the wiki directory structure and writes a plugin snippet to:
+   ~/Documents/llm-wiki/.system/opencode.plugin-snippet.json
+3. Read that snippet file.
+4. Merge the snippet into my OpenCode config at:
+   - Windows: %USERPROFILE%\.config\opencode\opencode.json
+   - macOS/Linux: ~/.config/opencode/opencode.json
+5. If opencode.json already has an oh-my-llmwikimode entry, update it. If not, add it to the "plugin" array.
+6. Back up opencode.json before modifying.
+7. Tell me to restart OpenCode.
+
+Do NOT overwrite existing plugin entries. Preserve the rest of the config.
+```
+
+### What `llmwiki init` does
+
+```sh
+npx llmwiki init --wiki-root ~/Documents/llm-wiki
+```
+
+The command writes:
+
+```text
+~/Documents/llm-wiki/.system/opencode.plugin-snippet.json
+```
+
+It creates these folders if they do not exist: `inbox/`, `problems/`, `editorial/lessons/`, `raw/`, `.system/`.
+
+Copy the generated snippet into your OpenCode config if you prefer a no-surprises setup, or let the AI do it.
+
+## Method 2: Manual steps
+
+### Windows
+
+Create the wiki folders:
+
+```powershell
+$wiki = Join-Path $HOME "Documents\llm-wiki"
+New-Item -ItemType Directory -Force -Path $wiki | Out-Null
+New-Item -ItemType Directory -Force -Path (Join-Path $wiki "inbox") | Out-Null
+New-Item -ItemType Directory -Force -Path (Join-Path $wiki "problems") | Out-Null
+New-Item -ItemType Directory -Force -Path (Join-Path $wiki "editorial\lessons") | Out-Null
+New-Item -ItemType Directory -Force -Path (Join-Path $wiki "raw") | Out-Null
+New-Item -ItemType Directory -Force -Path (Join-Path $wiki ".system") | Out-Null
+```
+
+Back up your config before editing:
+
+```powershell
+$config = Join-Path $HOME ".config\opencode\opencode.json"
+Copy-Item $config "$config.bak" -ErrorAction SilentlyContinue
+notepad $config
+```
+
+Merge this plugin entry into the top-level `plugin` array:
+
+```json
+["oh-my-llmwikimode", {
+  "wikiRoot": "~/Documents/llm-wiki",
+  "autoMemoryEnabled": true,
+  "autoSearchEnabled": true
+}]
+```
+
+If `plugin` does not exist yet, use the full default config shown in the prerequisites.
+
+### macOS/Linux
+
+Create the wiki folders:
+
+```sh
+mkdir -p ~/Documents/llm-wiki/inbox
+mkdir -p ~/Documents/llm-wiki/problems
+mkdir -p ~/Documents/llm-wiki/editorial/lessons
+mkdir -p ~/Documents/llm-wiki/raw
+mkdir -p ~/Documents/llm-wiki/.system
+```
+
+Create or edit OpenCode config:
+
+```sh
+mkdir -p ~/.config/opencode
+test -f ~/.config/opencode/opencode.json && cp ~/.config/opencode/opencode.json ~/.config/opencode/opencode.json.bak
+${EDITOR:-vi} ~/.config/opencode/opencode.json
+```
+
+Use the default config block from the prerequisites section, or merge this entry into an existing `plugin` array:
+
+```json
+["oh-my-llmwikimode", {
+  "wikiRoot": "~/Documents/llm-wiki",
+  "autoMemoryEnabled": true,
+  "autoSearchEnabled": true
+}]
+```
+
+## Method 3: PowerShell installer script (advanced)
+
+For automated or scripted setups, a PowerShell installer is available in the package checkout:
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\install-llmwiki.ps1
+```
+
+Custom wiki root:
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\install-llmwiki.ps1 -WikiRoot "~/Documents/llm-wiki"
+```
+
+What the script does:
+
+1. Detects the OpenCode config directory under your user profile.
+2. Creates `~/Documents/llm-wiki` if it does not exist.
+3. Creates these folders: `inbox/`, `problems/`, `editorial/lessons/`, `raw/`, `.system/`.
+4. Reads `opencode.json`, or creates a new config object when the file does not exist.
+5. Prompts before modifying an existing `opencode.json` and writes a timestamped backup first.
+6. Adds or updates the `oh-my-llmwikimode` plugin entry.
+7. Prints next steps. Restart OpenCode manually.
+
+## Verification
+
+1. Restart OpenCode.
+2. In OpenCode, ask:
+
+   ```text
+   내 위키 상태 확인해줘
+   ```
+
+3. Optional CLI checks:
+
+   ```sh
+   npx llmwiki init --wiki-root ~/Documents/llm-wiki --json
+   npx llmwiki lint --wiki-root ~/Documents/llm-wiki
+   ```
+
+Expected result: OpenCode recognizes the plugin config, and the local wiki folders exist under `~/Documents/llm-wiki`.
+
+## Troubleshooting
+
+### PowerShell says script execution is disabled
+
+Use the one-command bypass for this script only:
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\install-llmwiki.ps1
+```
+
+### Existing `opencode.json` is invalid JSON
+
+The installer stops before writing changes. Fix the JSON first, then rerun the installer. Your existing file is not overwritten.
+
+### Plugin entry is duplicated
+
+Keep one `oh-my-llmwikimode` entry in the top-level `plugin` array. The installer updates an existing matching entry when it can parse the config.
+
+### OpenCode does not load the plugin
+
+- Confirm the package name is `oh-my-llmwikimode`.
+- Confirm `opencode.json` is in `%USERPROFILE%\.config\opencode\` on Windows or `~/.config/opencode/` on macOS/Linux.
+- Restart OpenCode after editing config.
+- Run `npx llmwiki init --wiki-root ~/Documents/llm-wiki --json` and confirm the snippet uses the same `wikiRoot`.
+
+### Wiki folders were created in the wrong place
+
+Run init again with an explicit path:
+
+```sh
+npx llmwiki init --wiki-root /absolute/path/to/llm-wiki
+```
+
+Then update `wikiRoot` in `opencode.json` to the same path.
+
+### Permission errors
+
+Choose a directory inside your user profile, such as `~/Documents/llm-wiki`. Do not use system directories that require administrator privileges.

package/docs/SCOPE_LOCK.md

@@ -0,0 +1,79 @@
+# Scope Lock: oh-my-llmwikimode Identity and Prototype Policy
+
+> **Status**: Active | **Version**: 1.0.0 | **Locked**: 2026-05-02
+>
+> 이 문서는 oh-my-llmwikimode 시스템의 canonical 이름, 경로, 정책을 고정합니다.
+> 계획 문서: `.sisyphus/plans/oh-my-llmwikimode-ralph-hardening.md`
+
+---
+
+## Canonical Names (유일하게 사용할 이름)
+
+| 대상 | Canonical 값 | 비고 |
+|------|-------------|------|
+| **npm package name** | `oh-my-llmwikimode` | registry에 배포될 이름 |
+| **plugin ID** | `oh-my-llmwikimode` | OpenCode `opencode.json` plugin 배열에 사용 |
+| **display / log prefix** | `oh-my-llmwikimode` | 콘솔 로그, UI 표시 |
+| **GitHub repo** | `oh-my-llmwikimode` | repo slug |
+| **state directory** | `~/.config/opencode/.llmwikimode/` | 런타임 상태/로그 저장 |
+| **wiki root default** | `~/Documents/llm-wiki` | 사용자 wiki 저장소 기본 위치 |
+| **display term** | "LLM Wiki" | 사용자에게 보여줄 설명용 용어 (package/plugin ID와 구분) |
+
+---
+
+## Legacy / Non-Canonical Names (사용 금지)
+
+다음 이름들은 **legacy, prototype, 또는 잘못된 참조**입니다. 새 코드/문서/설정에서 canonical 이름으로 사용하지 마세요.
+
+- `opencode-plugin-llm-wiki` — 초기 prototype package 이름
+- `opencode-plugin-wikiloop` — 초기 계획서에서 사용했던 plugin 이름
+- `.omw` — 임의로 만든 state directory 이름 (OMO + Wiki의 줄임말이나 canonical이 아님)
+- `wikiloop` — slash command alias로는 사용 가능하나 plugin ID로 사용 금지
+
+이름들은 **마이그레이션 문서나 이력 섹션**에서만 참조할 수 있습니다.
+
+---
+
+## Prototype Policy (root-level prototype cleanup)
+
+### Retired prototype artifacts
+다음 파일들은 **2026-05-02에 만들어진 premature prototype**이었고, production package와 혼동되지 않도록 정리되었습니다:
+
+- `package.json` (root) — `name: opencode-plugin-llm-wiki`
+- `.github/workflows/ci-cd.yml` (root) — 수동 release 기반, semantic-release 없음
+- `package-lock.json` (root) — root prototype dependency lock
+- `src/server.js` (root) — archived to `.archive/root-prototype-20260502/src/server.js`
+- `test/run-tests.js` (root) — archived to `.archive/root-prototype-20260502/test/run-tests.js`
+
+Root `README.md` and `RALPH.md` now point to the canonical package under `plugins/oh-my-llmwikimode/`.
+`.ralph/bootstrap.*` and `.ralph/check.*` now run package-local commands for the canonical package.
+
+### 정책
+1. **root workspace는 publishable npm package가 아닙니다**.
+2. **새로운 production package는 `plugins/oh-my-llmwikimode/` 아래에만 둡니다**.
+3. **root-level package metadata나 release workflow를 다시 만들지 않습니다**.
+4. **모든 새 구현/문서/테스트는 `plugins/oh-my-llmwikimode/` 안에서만 작성**합니다.
+5. **GitHub/npm/OpenCode registration은 사용자 승인 후 별도 단계에서 진행**합니다.
+
+---
+
+## Support Matrix
+
+| 항목 | 버전/범위 |
+|------|----------|
+| OpenCode SDK | `@opencode-ai/plugin` ^1.14.0 |
+| Node.js | >= 18.0.0 |
+| OS | Windows, macOS, Linux |
+| Path style | POSIX preferred; Windows paths normalized via `path` module |
+
+---
+
+## Decision Log
+
+| 날짜 | 결정 | 이유 |
+|------|------|------|
+| 2026-05-02 | `oh-my-llmwikimode`로 이름 고정 | 사용자 명시 요청; oh-my-ralph, oh-my-openagent 패밀리와 일관 |
+| 2026-05-02 | package root를 `plugins/oh-my-llmwikimode/`로 분리 | root workspace에 관련 없는 파일이 많아 npm pack 안전성 확보 |
+| 2026-05-02 | `.llmwikimode`를 state dir로 고정 | `.omw`는 의미 불명확; canonical name에서 직접 유래 |
+| 2026-05-02 | prototype은 삭제하지 않고 reference로 유지 | 향후 migration guide나 audit trace에 활용 가능 |
+| 2026-05-02 | root prototype source/test를 `.archive/root-prototype-20260502/`로 이동 | 활성 루트에 결함 있는 spike 코드가 남아 future publish/register를 혼동시키지 않도록 함 |

package/docs/STAGE1_GUIDE.md

@@ -0,0 +1,265 @@
+# Stage 1 Guide: LLM Wiki Knowledge Workbench
+
+**버전**: v2 Stage 1
+**대상**: oh-my-llmwikimode 런타임 플러그인 + oh-my-llmwiki-pack VSIX 확장
+
+---
+
+## Stage 1 개요
+
+Stage 1은 LLM Wiki를 로컬 지식 작업대(Knowledge Workbench)로 만드는 단계입니다. 핵심 원칙은 "자동 수집, 사람이 검토"입니다.
+
+### Stage 1이 제공하는 것
+
+| 기능 | 설명 |
+|------|------|
+| 자동 후보 캡처 | 대화에서 문제 패턴을 감지해 `inbox/`에 candidate로 저장 |
+| 수동 저장 | `wiki_store`로 원하는 내용을 직접 저장 |
+| 검색 | `wiki_search`로 로컬 위키에서 관련 항목 찾기 |
+| 승격/거절 | `wiki_promote`로 lesson으로 승격, 또는 `rejected`로 처리 |
+| CLI 명령어 | `llmwiki lint`, `query`, `ingest`, `rebuild` |
+| 결정론적 그래프 | `.system/graph.json`과 `.system/browser-data.json` 자동 생성 |
+| 비밀 자동 가리기 | API 키, 비밀번호 패턴을 저장 전에 가림 |
+| VS Code 브라우저 | Knowledge Workbench, 그래프 뷰, Git sync |
+
+### Stage 1에서 없는 것
+
+아래 기능은 구현되지 않았습니다. 문서 어디에서도 "지원한다"고 적지 마세요.
+
+- 사람 검토 없는 lesson 전환 기능
+- 명시 승인 없는 원격 업로드 / 커밋
+- Obsidian 연동 / 양방향 동기화
+- MCP 서버
+- SQLite 그래프 데이터베이스
+- 원격 벡터 검색
+- Hermes 실행 환경
+- 자율 에이전트 팀 디스패치
+- 실행형 Tool Pack
+
+---
+
+## 워크플로 단계별 설명
+
+### 1. 자동 후보 생성
+
+OpenCode 대화에서 아래 키워드가 포함된 메시지를 별낸면, 플러그인이 문제 패턴으로 감지합니다.
+
+```text
+bug, error, failure, crash, exception, broken, not working, fails, issue, problem
+버그, 오류, 실패, 문제, 에러, 오작동
+```
+
+감지되면 `inbox/`에 Markdown 파일이 자동 생성됩니다. 파일 형태:
+
+```markdown
+---
+title: (자동 추출된 제목)
+status: candidate
+source: chat.message
+tags:
+  - auto-captured
+  - problem
+---
+
+(캡처된 내용)
+```
+
+**조용한 모드 정책**: 정상적인 자동 저장은 콘솔에 출력되지 않습니다. 실제 오류(파일 쓰기 실패 등)만 표시됩니다. 저장/걸�promise기록은 위키 루트의 `.system/auto-memory-audit.jsonl`에서 확인할 수 있습니다.
+
+자동 저장이 걸�promise는 경우:
+- `autoMemoryEnabled`가 `false`
+- 메시지에 "do not store", "저장하지 마" 포함
+- 메시지 크기가 안전 한도 초과
+- 프롬프트 인젝션 패턴 감지
+- 명시적 "저장해줘" 요청 (에이전트가 `wiki_store`로 처리)
+- 남부 오케스트레이션 프롬프트 (`[analyze-mode]`, `OMO_INTERNAL_INITIATOR` 등)
+
+### 2. VS Code / Antigravity에서 검토
+
+VS Code에 `oh-my-llmwiki-pack` 확장을 설치하면 Knowledge Workbench가 열립니다.
+
+```text
+Ctrl+Shift+P → "LLM Wiki: Open Knowledge Workbench"
+```
+
+Workbench에서 볼 수 있는 것:
+- 후보 항목 목록
+- 중복 경고
+- 그래프 연결 정보
+- 항목 내용 미리보기
+
+### 3. 승격 또는 거절
+
+검토 후 두 가지 선택이 있습니다:
+
+**승격** (lesson으로):
+```text
+wiki_promote inbox/2026-05-07-...-항목이름.md
+```
+파일이 `editorial/lessons/`로 이동하고 `status: lesson`이 됩니다.
+
+**거절**:
+항목의 frontmatter에서 `status: candidate`를 `status: rejected`로 바꿉니다. 거절된 항목은 검색 결과에서 제외됩니다.
+
+### 4. 그래프 / 브라우저 보기
+
+`.system/` 아래 파생 파일은 `llmwiki rebuild`로 재생성하거나 프로모션/거절 시 자동 갱신됩니다.
+
+```text
+.system/
+├── index.json          # 검색용 키워드 인덱스
+├── graph.json          # 항목 간 연결 그래프
+└── browser-data.json   # VS Code 브라우저 렌더링 데이터
+```
+
+VS Code에서 그래프 보기:
+```text
+Ctrl+Shift+P → "LLM Wiki: Open Knowledge Graph"
+```
+
+그래프는 위키링크(`[[다른 항목]]`)와 태그 기반으로 항목을 연결합니다. `rejected`, `superseded`, `private`, `needs-clarification` 상태는 그래프에서 제외됩니다.
+
+그래프는 결정론적입니다. 같은 내용에서 항상 같은 그래프가 생성됩니다. 필요하면 `llmwiki rebuild`로 언제든 재생성할 수 있습니다.
+
+### 5. 수동 Git sync
+
+변경사항은 자동으로 커밋되거나 push되지 않습니다. 직접 커밋해야 합니다.
+
+VS Code에서:
+```text
+Ctrl+Shift+P → "LLM Wiki: Manual Git Sync" → "Stage & Commit"
+```
+
+또는 터미널에서:
+```bash
+cd ~/Documents/llm-wiki
+git add -A
+git commit -m "update wiki entries"
+# push는 선택
+git push
+```
+
+---
+
+## CLI 명령어 상세
+
+모든 명령어는 패키지 루트(`plugins/oh-my-llmwikimode/`)에서 실행합니다.
+
+### `llmwiki lint`
+
+항목의 스키마, 수명주기, 개인정보, 중복을 검사합니다.
+
+```bash
+npx llmwiki lint
+```
+
+검사 항목:
+- frontmatter 필수 필드 (`title`, `status`, `source`)
+- 올바른 상태값 (`candidate`, `lesson`, `rejected`, `superseded`, `needs-clarification`, `private`)
+- 민감정보 노출 여부
+- 같은 제목의 중복 항목
+
+자동 수정은 하지 않습니다. 경고만 출력합니다.
+
+### `llmwiki query`
+
+로컬 위키를 키워드로 검색합니다. 1홉 관련 항목과 관계 레이블을 포함합니다.
+
+```bash
+npx llmwiki query "docker compose error"
+```
+
+### `llmwiki ingest`
+
+로컬 파일을 candidate로 `inbox/`에 가져옵니다.
+
+```bash
+npx llmwiki ingest /path/to/file.md
+```
+
+가져오기 전 비밀번호 자동 가리기, 안전하지 않은 경로 차단이 적용됩니다.
+
+### `llmwiki rebuild`
+
+`.system/index.json`, `.system/graph.json`, `.system/browser-data.json`을 처음부터 다시 만듭니다.
+
+```bash
+npx llmwiki rebuild
+```
+
+결정론적이므로 언제든 안전하게 실행할 수 있습니다.
+
+---
+
+## 문제 해결
+
+### 플러그인이 로드되지 않을 때
+
+1. OpenCode를 재시작합니다.
+2. 콘솔에서 `[oh-my-llmwikimode] init:` 메시지를 확인합니다.
+3. `opencode.json`의 `plugin` 배열에 플러그인이 등록되어 있는지 확인합니다.
+4. npm 공개 전이라면 로컬 경로가 올바른지 확인합니다.
+
+### 검색 결과가 없을 때
+
+1. `~/Documents/llm-wiki/inbox/`에 파일이 있는지 확인합니다.
+2. 항목의 frontmatter에 `title` 필드가 있는지 확인합니다.
+3. 상태가 `rejected`, `superseded`, `needs-clarification`이면 검색에서 제외됩니다.
+4. 더 구체적인 키워드로 다시 검색합니다.
+5. `llmwiki rebuild`로 인덱스를 재생성합니다.
+
+### 자동 메모리가 동작하지 않을 때
+
+1. `autoMemoryEnabled`가 `true`인지 확인합니다.
+2. 메시지에 문제 키워드가 포함되어 있는지 확인합니다.
+3. "저장해줘" 같은 명시적 요청은 자동 캡처를 걸�promise니다 (정상 동작).
+4. 위키 루트의 `.system/auto-memory-audit.jsonl` 디버그 로그를 확인합니다.
+
+### 그래프에 항목이 보이지 않을 때
+
+1. 항목 상태가 `rejected`, `superseded`, `private`, `needs-clarification`이 아닌지 확인합니다.
+2. `llmwiki rebuild`로 재생성합니다.
+3. `wiki_search`를 한 번 실행해 인덱스를 갱신합니다.
+
+### 중복 항목이 많을 때
+
+같은 문제를 여러 번 말하면 중복 항목이 생길 수 있습니다. `inbox/`를 확인하고 불필요한 항목은 `status: rejected`로 바꾸거나 삭제합니다. 완전한 중복 병합은 아직 지원하지 않습니다.
+
+---
+
+## Post-MVP 로드맵 참고
+
+아래는 Stage 1 이후의 계획입니다. 현재 동작하지 않습니다.
+
+| 단계 | 이름 | 핵심 내용 |
+|------|------|-----------|
+| **Stage 2** | Agent Team Workbench | 역할 기반 워커, 오케스트레이터 모드, 작업 큐, 능력 게이트, wiki 기반 공유 메모리 |
+| **Stage 3** | Hermes-like Conversational Growth | 검토된 스킬 추출, 메모리 큐레이션, 중요도/최신성/신뢰도 점수 |
+| **Stage 4** | Personal/Team AI OS | 통합 대시보드, 그래프 추론, 안전한 동기화, 팀 협업 |
+
+Post-MVP 후보 기능 (Stage 1에 해당하지 않음):
+- Obsidian 연동 / 양방향 동기화
+- MCP 서버 인터페이스
+- SQLite 그래프 데이터베이스
+- 원격 벡터 검색
+- 사람 검토 없는 lesson 전환 / 명시 승인 없는 원격 업로드
+- 실행형 Tool Pack
+- 공개 마켓플레이스
+
+자세한 내용은 [4-stage roadmap memo](../../.sisyphus/drafts/llmwiki-4-stage-roadmap-memo.md)를 참고하세요.
+
+---
+
+## 관련 문서
+
+| 문서 | 위치 |
+|------|------|
+| 플러그인 README | [`README.md`](../README.md) |
+| 사용자 가이드 (한국어) | [`docs/user-guide-ko.md`](user-guide-ko.md) |
+| 사용자 테스트 가이드 | [`../../docs/LLMWIKI_USER_TEST_GUIDE.md`](../../docs/LLMWIKI_USER_TEST_GUIDE.md) |
+| Scope Lock | [`docs/SCOPE_LOCK.md`](SCOPE_LOCK.md) |
+| 4단계 로드맵 메모 | [`../../.sisyphus/drafts/llmwiki-4-stage-roadmap-memo.md`](../../../.sisyphus/drafts/llmwiki-4-stage-roadmap-memo.md) |
+
+---
+
+*이 가이드는 LLM Wiki v2 Stage 1 Knowledge Workbench의 개념, 워크플로, 문제 해결을 설명합니다.*