@kybird/llm-wiki 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kybird
+
+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,168 @@
+# llm-wiki
+
+An **LLM-friendly knowledge graph + kanban board** for AI coding agents. Capture errors, decisions, and discoveries as raw daily logs, then compile them into a searchable wiki of concepts, patterns, and anti-patterns that agents consult before writing code. A file-based kanban (`doc/kanban/`) turns the same repo into an unattended work queue.
+
+Inspired by [Karpathy's Agentic Memory](https://github.com/karpathy/llm.c) ideas — designed so the *next* agent session doesn't repeat the *last* agent's mistakes.
+
+## Why
+
+AI coding agents (Claude Code, Cursor, ZCode, Gemini CLI, …) forget everything between sessions. A project wiki that they actually read — grounded in git hashes, real error strings, and real failure cases — turns one-off debugging pain into durable, reusable knowledge. The kanban adds a convergence loop: cards are picked, resolved, parked for human judgment, or abandoned *with a reason* that feeds back into the wiki as anti-pattern material.
+
+The skills (`wiki-search`, `wiki-log`, `wiki-compile`, `wiki-lint`, `kanban-plan`, `work-loop`) are **LLM prompts**: the intelligence lives in the agent's context, not in a server. The CLI is just the plumbing. Planning sessions turn plans into cards (`kanban-plan`); unattended loop sessions resolve them (`work-loop`).
+
+## Install
+
+```bash
+npm install -g @kybird/llm-wiki   # installs the `llm-wiki` command
+# or run without installing:
+npx @kybird/llm-wiki init
+```
+
+## Quickstart (in any repo)
+
+```bash
+cd my-project
+llm-wiki init          # scaffolds doc/ (wiki + kanban), copies skills + hooks + scripts
+
+# Enable git hooks (run once per clone):
+git config core.hooksPath githooks
+
+# (Optional) QMD adds semantic search on top of grep — grep alone works without it:
+npm install @tobilu/qmd
+```
+
+Then tell your AI agent (via its instructions file — `CLAUDE.md` / `AGENTS.md` / etc.):
+- **Before any task**: run `llm-wiki search "<task keywords>"` and read matching `status: active` pages.
+- **After fixing a bug / making a design decision**: use the `wiki-log` skill to record a Case in `doc/raw/YYYY-MM-DD.md`.
+- **Periodically**: use `wiki-compile` to promote raw cases into `doc/wiki/` pages.
+
+That's it. The agent does the rest.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `llm-wiki init [--check]` | Scaffold `doc/` (wiki + kanban), copy skills + hooks + scripts. Marker-aware — re-running updates copies and preserves your edits. `--check` reports without writing |
+| `llm-wiki search "<query>"` | Grep exact matching + QMD semantic search, **always merged**; ranked by matched-keyword count with line snippets |
+| `llm-wiki compile list` | Show raw logs not yet compiled — header date **or** content hash (`compile-state.json`), so same-day appends are caught too |
+| `llm-wiki compile index` | Rebuild `doc/wiki/index.md` (with aliases and answers), regenerate `compile-state.json`, and sync the QMD index. **This is a "compile complete" declaration** — run it after the wiki-compile skill's phases, not instead of them |
+| `llm-wiki lint` | Broken links, **evidence back-matching** (hash refs & `### Error` quotes must exist verbatim in `doc/raw/`), uncompiled concepts, metadata, staleness |
+| `llm-wiki board` / `board report` | Derived kanban view / dashboard (done:abandoned ratio, trend, QA reverts, waiting queue) |
+| `llm-wiki board video` | Replay `activity.jsonl` into a board timelapse MP4 (requires the `video/` Remotion project; CPU render, no GPU) |
+| `llm-wiki card new/show/edit` | Create and edit cards — the CLI is the only writer (sentinel-safe sections) |
+| `llm-wiki pick --claim <name>` | Atomically claim the next eligible card (lock, WIP limit, dependencies, claim expiry) |
+| `llm-wiki handoff <title> --question "…"` | Park a card for human judgment and release the claim |
+| `llm-wiki done <title> --result "…"` | Complete a card — Result is required |
+| `llm-wiki supersede <title> --by a,b` | Replace a card by children; the parent dissolves into `superseded/` |
+| `llm-wiki abandon <title> --reason "…"` | Discard — reason required, and auto-logged to `doc/raw/` as anti-pattern material |
+| `llm-wiki reopen <title> --why "…"` | QA: revert a fake-done card back to doing |
+
+`search`, `lint`, `compile list|index`, `board`, `pick` accept `--json` (a `{schemaVersion: 1, kind: …}` envelope for scripts and skills).
+
+## What `init` creates
+
+```
+your-repo/
+├── doc/
+│   ├── raw/               # daily logs (YYYY-MM-DD.md) — wiki-log writes here
+│   ├── wiki/              # compiled knowledge
+│   │   ├── index.md       # auto-rebuilt by `compile index`
+│   │   └── concepts/ patterns/ antipatterns/ answers/
+│   └── kanban/            # card-per-file kanban
+│       ├── board.yml      # statuses, WIP limit, claim timeout
+│       ├── cards/         # active: todo / doing / review (frontmatter status)
+│       ├── done/ superseded/ abandoned/   # termination = the folder
+│       └── activity.jsonl # append-only audit log (10k line cap)
+├── .agents/skills/        # canonical skills (ZCode, Cursor, …)
+├── .claude/skills/        # mirror for Claude Code
+├── scripts/               # doc/skill sync scripts (marker-protected copies)
+└── githooks/pre-commit    # CLAUDE.md drift guard + skill mirror + uncompiled-log nudge
+```
+
+## Updating
+
+The skills, hooks, and scripts copied into your repo are **marker-protected copies**. Updating is two commands:
+
+```bash
+npm update -g llm-wiki    # refresh the global CLI
+llm-wiki init --check     # what would change? (ok / stale / user-modified / missing)
+llm-wiki init             # apply — stale copies update, your edits survive
+```
+
+The contract: a copy keeps its version marker (`skill-version:` in skills, `llm-wiki-template-version:` in hooks and scripts) only while it is unmodified. **To customize a copy, delete its marker line** — `init` then treats it as yours and never overwrites it. Repos that keep their own canonical hook can skip the copy entirely: set `"hooksPath": "templates/githooks"` in `llm-wiki.config.json`.
+
+## Configuration (optional)
+
+Create `llm-wiki.config.json` in your repo root:
+
+```json
+{
+  "projectName": "my-project",
+  "collections": {
+    "wiki": "my-project-wiki",
+    "raw": "my-project-wiki-raw"
+  },
+  "hooksPath": "templates/githooks"
+}
+```
+
+- `projectName` — appears in the `index.md` header (omitted if unset).
+- `collections` — QMD collection names (defaults derive from your repo's folder name; unique names matter — colliding names silently cross-contaminate search across projects).
+- `hooksPath` — set it and `init` won't create a `githooks/` copy; your repo uses that path directly (for repos that vendor their own hook source).
+
+You can also set `LLM_WIKI_ROOT=/path/to/doc-parent` to point at a `doc/` outside the repo.
+
+## How the knowledge flows
+
+```
+agent fixes a bug
+      │
+      ▼  wiki-log skill
+doc/raw/2026-07-24.md   (Case: grounding + error + fix + analysis)
+      │
+      ▼  wiki-compile skill (LLM extracts & synthesizes)
+doc/wiki/patterns/foo.md   doc/wiki/antipatterns/bar.md
+      │
+      ▼  llm-wiki compile index
+doc/wiki/index.md   + QMD embeddings
+      │
+      ▼  next agent session
+llm-wiki search "foo"   →  reads the pattern, avoids repeating the mistake
+```
+
+Raw logs are the source of truth; compiled wiki pages are derived. The `status:` field (`active` / `deprecated` / `superseded`) lets knowledge evolve without losing history.
+
+## Agent-docs & skill sync (bonus)
+
+`init` also installs a `pre-commit` hook that keeps your agent-instruction files in sync:
+
+- Edit `CLAUDE.md` (canonical) → `agents.md`, `GEMINI.md` auto-mirror on commit.
+- Edit `.agents/skills/` (canonical) → `.claude/skills/` auto-mirrors.
+- Editing a copy directly is rejected with a clear message.
+
+This lets you target multiple agent CLIs from one canonical source. If you don't want it, simply skip `git config core.hooksPath githooks`. Package-level updates of the copied skills/hooks/scripts follow the marker contract — see [Updating](#updating).
+
+## QMD / semantic search
+
+[`@tobilu/qmd`](https://github.com/tobi/qmd) provides local vector embeddings (no network) for semantic search. It's an **optional** dependency:
+
+- Installed → `llm-wiki search` merges QMD semantic results on top of the grep results.
+- Absent → grep-only; exact matching still fully works (ranked by matched keywords, with line snippets).
+
+Grep always runs — semantic search is a supplement, never a replacement. First use downloads a ~300 MB embedding model to `~/.cache/qmd/models/`. For CUDA/build issues, see [TROUBLESHOOTING.md](TROUBLESHOOTING.md).
+
+## Development (this repo)
+
+This repo dogfoods itself:
+
+```bash
+npm link          # global `llm-wiki` runs this working tree
+llm-wiki init     # syncs skills + scripts into this repo (marker-aware)
+git config core.hooksPath templates/githooks
+```
+
+`llm-wiki.config.json` here declares `"hooksPath": "templates/githooks"`, so `init` never creates a `githooks/` copy — the active hook *is* the canonical template. See [doc/improvement-plan.md](doc/improvement-plan.md) for the roadmap state and [doc/plan.md](doc/plan.md) for the design record.
+
+## License
+
+MIT

package/TROUBLESHOOTING.md

@@ -0,0 +1,103 @@
+# Troubleshooting: QMD / node-llama-cpp build-time CUDA failures
+
+> This document covers Windows + NVIDIA-specific diagnostics for the optional `@tobilu/qmd` dependency (used by `llm-wiki compile index` for semantic search embeddings). If `compile index` prints `falling back to using Vulkan` or a `CUDA error`, consult this.
+>
+> QMD is **optional**. Without it, `llm-wiki search` falls back to grep and the wiki index still rebuilds correctly.
+
+## Runtime CUDA OOM vs build-time compile failure
+
+These are two different failure modes:
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `CUDA error: out of memory` at runtime | Transient driver/VRAM state, GPU asleep | `QMD_LLAMA_GPU=false` for that run |
+| `error STL1002: Unexpected compiler version, expected CUDA 12.4+` | MSVC + CUDA Toolkit mismatch at build time | Upgrade CUDA Toolkit (see below) |
+
+## Variable name reminder
+
+Use **`QMD_LLAMA_GPU`** to force CPU. Do **not** use `NODE_LLAMA_CPP_GPU` — it is read by nothing in the qmd codebase and has no effect.
+
+## node-llama-cpp v3.x prebuilt binary resolution
+
+node-llama-cpp v3.x ships prebuilt binaries as npm `optionalDependencies`. `getLlama({build: "autoAttempt"})` priority:
+
+1. **Prebuilt binary load** — `node_modules/@node-llama-cpp/<platform>/bins/.../llama-addon.node`. No MSBuild needed; only matching CUDA runtime DLLs required.
+2. **Source build** (CMake/MSBuild) — reached only if (1) fails.
+3. **Other backend fallback** (Vulkan, CPU).
+
+**Most common real-world failure**: multiple CUDA versions coexisting → prebuilt DLL conflict. Example: CUDA 11.8 + 13.x coexist → `win-x64-cuda` prebuilt fails to load → falls to source build → exposes `.targets` problems.
+
+**Fix (restore prebuilt path)**: keep only one CUDA version installed. Then prebuilt loads cleanly and source build is never attempted.
+
+## Required CUDA version for prebuilt binaries
+
+The prebuilt ggml-cuda DLL imports a specific `cublas64_XX.dll`. Check which one your installed prebuilt expects:
+
+```powershell
+$dll = "node_modules\@node-llama-cpp\win-x64-cuda\bins\win-x64-cuda\ggml-cuda.dll"
+$bytes = [System.IO.File]::ReadAllBytes($dll)
+$ascii = [System.Text.Encoding]::ASCII.GetString($bytes)
+[regex]::Matches($ascii, "cublas64_\w+\.dll") | ForEach-Object { $_.Value } | Sort-Object -Unique
+# cublas64_13.dll → CUDA 13.x required
+# cublas64_12.dll → CUDA 12.x required
+```
+
+Install the matching CUDA Toolkit. The NVIDIA driver's `nvidia-smi` "CUDA Version" shows the max runtime the driver supports natively; if the Toolkit exceeds it, Forward Compatibility kicks in and some prebuilts break there too.
+
+## MSVC / CUDA Toolkit version matrix
+
+MSVC's `yvals_core.h` static assertion enforces a minimum CUDA version at compile time:
+
+| MSVC version | Required CUDA minimum |
+|---|---|
+| 14.39 and below | CUDA 11.x allowed |
+| 14.40–14.43 | CUDA 12.0+ recommended |
+| **14.44+** | **CUDA 12.4+ required** |
+
+VS 2022 auto-updates push MSVC forward, so if you don't upgrade CUDA Toolkit alongside it, build-time compatibility violations occur. **Unrelated to GPU hardware/driver state.**
+
+## VS BuildCustomizations (.targets) conflict
+
+> If CUDA Toolkit is upgraded but the build still invokes an old `nvcc.exe`, suspect this.
+
+**Symptom**: After installing CUDA 13.x, CMake logs `Found CUDAToolkit: ...v13.3` correctly, but MSBuild still calls `v11.8\bin\nvcc.exe` during compilation → same `error STL1002`.
+
+**Root cause**: stale CUDA `.targets` files in VS 2022 BuildCustomizations:
+
+```
+C:\Program Files\Microsoft Visual Studio\2022\<Edition>\MSBuild\Microsoft\VC\v170\BuildCustomizations\
+├── CUDA 11.8.props   ← stale
+├── CUDA 11.8.targets ← stale (hardcodes old nvcc path)
+└── CUDA 11.8.xml     ← stale
+```
+
+MSBuild loads `.targets` regardless of CMake's CUDA detection. Environment variables (`CUDACXX`, `CMAKE_CUDA_COMPILER`, `CUDA_PATH`) cannot override it.
+
+**Trigger**: unchecking "Visual Studio Integration" during CUDA Toolkit upgrade leaves the old `.targets` in place.
+
+**Fix** (admin PowerShell):
+
+```powershell
+$dir = "C:\Program Files\Microsoft Visual Studio\2022\<Edition>\MSBuild\Microsoft\VC\v170\BuildCustomizations"
+Remove-Item "$dir\CUDA 11.8.props" -Force
+Remove-Item "$dir\CUDA 11.8.targets" -Force
+Remove-Item "$dir\CUDA 11.8.xml" -Force
+```
+
+Or: Control Panel → uninstall "NVIDIA CUDA Visual Studio Integration 11.8".
+
+Removing `.targets` does **not** delete the CUDA 11.8 toolkit itself — other projects can still use the v11.8 path explicitly. Side-by-side coexistence is preserved.
+
+## Detection priority
+
+1. Look for `falling back to using Vulkan` in `compile index` output → prebuilt DLL conflict (stage 1 failed).
+2. Check for `error STL1002` or `expected CUDA 12.4 or newer` in the same output → MSVC/CUDA mismatch.
+3. Compare `nvcc --version` against the VS 2022 MSVC version (`cl.exe` 19.44+ needs CUDA 12.4+).
+4. Final result `✓ Done!` means embedding succeeded (functionally OK, only performance degraded).
+
+## Anti-patterns (do not do)
+
+- ❌ `NODE_LLAMA_CPP_GPU=false` — read by nothing; ineffective.
+- ❌ "GPU failed so force CPU" for a **build-time** compiler mismatch — runtime env var can't fix a compile error.
+- ❌ "Leave Vulkan fallback, it works" — ~16× slower than GPU; costly if you compile frequently.
+- ❌ "CUDA 11.8 is stable, keep it" — VS 2022 auto-update forces MSVC up, making 11.8 unsustainable.

package/bin/llm-wiki.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+// llm-wiki — LLM-friendly knowledge graph CLI for AI coding agents.
+// 서브커맨드: search, compile, lint, init.
+// 스킬(SKILL.md)이 이 명령을 호출한다. 에이전트 CLI(Claude/ZCode/Cursor) 무관.
+const { search } = require('../lib/wiki-search');
+const { compile } = require('../lib/wiki-compile');
+const { lint } = require('../lib/wiki-lint');
+const { init } = require('../lib/init');
+const kanbanCmd = require('../lib/kanban-cmd');
+
+function printUsage() {
+  console.log(`llm-wiki — LLM-friendly knowledge graph + kanban for AI coding agents
+
+Usage:
+  llm-wiki search "<query>"          Semantic+grep merged search over wiki + raw logs
+  llm-wiki compile list              Show raw logs modified since last compile
+  llm-wiki compile index             Rebuild wiki index.md + sync QMD search index
+  llm-wiki lint                      Validate wiki integrity (links, metadata, evidence)
+  llm-wiki init [--check]            Scaffold doc/ + skills/ + hooks (--check: report only)
+
+Kanban (cards are files; CLI is the only writer):
+  llm-wiki board [--html] [--json]   Derived board view (columns, WIP, queue) / static HTML
+  llm-wiki board report              Dashboard (done:abandoned ratio, trend, reverts)
+  llm-wiki board video               Timelapse of board activity → MP4 (needs video/ project)
+  llm-wiki card new "<title>"        Create card (--goal, --ac, --depends)
+  llm-wiki card show <title>         Print card file
+  llm-wiki card edit <title>         Sentinel-safe edits (--goal/--ac/--add-ac/--check-ac/--note/--plan)
+  llm-wiki pick --claim <name>       Atomically claim the next eligible card (locks, WIP, deps)
+  llm-wiki handoff <title> --question "…"   Park for human judgment, release claim
+  llm-wiki done <title> --result "…"        Complete (Result required)
+  llm-wiki supersede <title> --by a,b       Replace by children (parent dissolves)
+  llm-wiki abandon <title> --reason "…"     Discard (reason required, never deleted)
+  llm-wiki reopen <title> --why "…"         QA: revert a fake-done card to doing
+  llm-wiki resume <title> [--note "…"]      Return a review (parked) card to todo
+
+Optional:
+  npm i @tobilu/qmd                  Enable semantic search (falls back to grep if absent)
+  --json                             Machine-readable output: {schemaVersion: 1, kind: ...}
+                                     (search, lint, compile list|index)
+  LLM_WIKI_ROOT=/path                Override doc/ root location
+  llm-wiki.config.json               { "projectName": "...", "collections": {...},
+                                       "hooksPath": "templates/githooks" }`);
+}
+
+const [, , subcommand, ...rest] = process.argv;
+// --json/--html은 어느 위치에 와도 플래그로 뽑아낸다 (검색어 문자열에서 제외).
+const jsonRequested = rest.includes('--json');
+const htmlRequested = rest.includes('--html');
+const args = rest.filter(a => a !== '--json' && a !== '--html');
+
+switch (subcommand) {
+  case 'search':
+    search(args.join(' '), { json: jsonRequested });
+    break;
+  case 'compile':
+    compile(args[0], { json: jsonRequested }); // 'list' | 'index'
+    break;
+  case 'lint':
+    lint({ json: jsonRequested });
+    break;
+  case 'init':
+    init({ check: args.includes('--check') });
+    break;
+  case 'board':
+    if (args[0] === 'report') kanbanCmd.boardReport({ json: jsonRequested });
+    else if (args[0] === 'video') kanbanCmd.boardVideo({ rest: args });
+    else kanbanCmd.boardView({ rest: args, json: jsonRequested, html: htmlRequested });
+    break;
+  case 'card':
+    kanbanCmd.dispatchCard(args);
+    break;
+  case 'pick':
+    kanbanCmd.pick({ rest: args, json: jsonRequested });
+    break;
+  case 'handoff':
+    kanbanCmd.handoff({ rest: args });
+    break;
+  case 'done':
+    kanbanCmd.doneCard({ rest: args });
+    break;
+  case 'supersede':
+    kanbanCmd.supersede({ rest: args });
+    break;
+  case 'abandon':
+    kanbanCmd.abandon({ rest: args });
+    break;
+  case 'reopen':
+    kanbanCmd.reopen({ rest: args });
+    break;
+  case 'resume':
+    kanbanCmd.resume({ rest: args });
+    break;
+  case '--help':
+  case '-h':
+  case undefined:
+    printUsage();
+    break;
+  default:
+    console.error(`Unknown command: ${subcommand}`);
+    printUsage();
+    process.exit(1);
+}

package/lib/find-doc-root.js

@@ -0,0 +1,93 @@
+// cwd 기반 doc/ 루트 자동 탐색.
+// llm-wiki는 어느 리포에서 실행되든 동작해야 하므로, 스크립트 자신의 위치(__dirname)
+// 에 의존하지 않고 cwd에서 위로 올라가며 `doc/wiki`를 찾는다.
+//
+// 탐색 우선순위:
+//   1. LLM_WIKI_ROOT 환경변수 (명시적 오버라이드)
+//   2. cwd에서 위로 올라가며 doc/wiki 디렉토리가 있는 첫 조상
+//   3. cwd/doc (init 전이라 없어도 호출 가능하도록 폴백)
+const fs = require('fs');
+const path = require('path');
+
+function findDocRoot(startDir) {
+  // 1) 환경변수 오버라이드
+  if (process.env.LLM_WIKI_ROOT) {
+    return path.resolve(process.env.LLM_WIKI_ROOT);
+  }
+
+  // 2) cwd에서 위로 올라가며 doc/wiki 탐색
+  let dir = path.resolve(startDir || process.cwd());
+  for (let i = 0; i < 20; i++) {
+    const candidate = path.join(dir, 'doc', 'wiki');
+    if (fs.existsSync(candidate) && fs.statSync(candidate).isDirectory()) {
+      return path.join(dir, 'doc');
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break; // 파일시스템 루트 도달
+    dir = parent;
+  }
+
+  // 3) 폴백: cwd/doc (init 전 상태에서도 호출 허용)
+  return path.join(process.cwd(), 'doc');
+}
+
+// 리포 폴더명을 QMD 컬렉션 이름으로 안전하게 변환.
+// 소문자화 + 영숫자 외 문자는 '-'로 치환 + 연속 '-' 축약 + 양끝 '-' 제거.
+// 빈 문자열이 되면(폴더명이 특수문자뿐인 극단적 케이스) 'project'로 폴백.
+function sanitizeCollectionName(name) {
+  const cleaned = String(name || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  return cleaned || 'project';
+}
+
+// docRoot(`<repo>/doc`)에서 리포 폴더명을 뽑아 기본 컬렉션 이름을 만든다.
+// ⚠️ 과거에는 'ttswiki'/'ttswiki-raw'로 하드코딩돼 있었다 — "path-agnostic, drop-in for
+// any repo"라는 이 도구의 목표와 달리, 두 프로젝트가 기본값 그대로 init하면 전역 QMD 설정
+// (~/.config/qmd/index.yml)에서 컬렉션 이름이 충돌해 서로의 로그가 뒤섞여 검색되는 사고가
+// 났다(증상이 조용함 — 에러 없이 "0 new"만 찍히고 엉뚱한 프로젝트 결과가 나옴). 리포 폴더명
+// 기반으로 기본값을 만들면 충돌 확률이 크게 줄어든다.
+function defaultCollectionNames(docRoot) {
+  const repoRoot = docRoot ? path.dirname(path.resolve(docRoot)) : process.cwd();
+  const base = sanitizeCollectionName(path.basename(repoRoot));
+  return { wiki: `${base}-wiki`, raw: `${base}-wiki-raw` };
+}
+
+// 설정 파일 로드 (선택). cwd 또는 docRoot의 llm-wiki.config.json.
+// 반환: { projectName, collections: { wiki, raw }, hooksPath } 병합 결과 (기본값 포함).
+// hooksPath: 설정하면 init이 githooks/ 사본을 만들지 않고 그 경로를 그대로 쓴다
+// (레포가 templates/ 등 정본을 직접 참조하는 경우 — drift 원천 제거).
+function loadConfig(docRoot) {
+  const defaults = {
+    projectName: null, // null이면 index.md 헤더에 프로젝트명 생략
+    collections: defaultCollectionNames(docRoot),
+    hooksPath: null,
+  };
+
+  const candidates = [
+    path.join(process.cwd(), 'llm-wiki.config.json'),
+    docRoot ? path.join(docRoot, '..', 'llm-wiki.config.json') : null,
+  ].filter(Boolean);
+
+  for (const p of candidates) {
+    if (fs.existsSync(p)) {
+      try {
+        const user = JSON.parse(fs.readFileSync(p, 'utf8'));
+        return {
+          projectName: user.projectName !== undefined ? user.projectName : defaults.projectName,
+          collections: {
+            wiki: (user.collections && user.collections.wiki) || defaults.collections.wiki,
+            raw: (user.collections && user.collections.raw) || defaults.collections.raw,
+          },
+          hooksPath: user.hooksPath !== undefined ? user.hooksPath : defaults.hooksPath,
+        };
+      } catch (e) {
+        // 깨진 config는 무시하고 기본값 사용 (사용자에게 에러 띄우지 않음)
+      }
+    }
+  }
+  return defaults;
+}
+
+module.exports = { findDocRoot, loadConfig, sanitizeCollectionName, defaultCollectionNames };

package/lib/find-qmd.js

@@ -0,0 +1,52 @@
+// @tobilu/qmd CLI 진입점 탐색.
+// qmd는 optional dependency이므로 설치 위치가 다양할 수 있다.
+//   1. 이 패키지의 node_modules (optionalDependencies로 설치된 경우)
+//   2. cwd의 node_modules (타겟 리포가 별도로 npm i @tobilu/qmd 한 경우)
+//   3. 글로벌 npm root (npm i -g @tobilu/qmd 한 경우)
+//   4. 환경변수 QMD_CLI_PATH (명시적 오버라이드)
+//
+// 어느 곳에서도 찾지 못하면 null 반환 → 호출측에서 grep fallback으로 강하.
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const QMD_CLI_REL = 'dist/cli/qmd.js';
+
+function findQmd() {
+  // 1) 환경변수 명시 오버라이드
+  if (process.env.QMD_CLI_PATH && fs.existsSync(process.env.QMD_CLI_PATH)) {
+    return process.env.QMD_CLI_PATH;
+  }
+
+  const candidates = [];
+
+  // 2) 이 패키지 자신의 의존성 트리에서 resolve.
+  //    qmd package.json이 exports로 서브패스를 제한하므로 './package.json' 직접 resolve는
+  //    ERR_PACKAGE_PATH_NOT_EXPORTED 실패. main 진입점(dist/index.js)을 resolve한 뒤
+  //    패키지 루트로 역추적한다 — main은 exports에 노출되어 있으므로 안전.
+  try {
+    const mainPath = require.resolve('@tobilu/qmd');
+    // main은 <pkgRoot>/dist/index.js 형태 → <pkgRoot>를 얻으려 dist/의 부모.
+    candidates.push(path.join(path.dirname(path.dirname(mainPath)), QMD_CLI_REL));
+  } catch (e) {
+    // optional이므로 없을 수 있음 — 정상
+  }
+
+  // 3) cwd의 node_modules
+  candidates.push(path.join(process.cwd(), 'node_modules/@tobilu/qmd', QMD_CLI_REL));
+
+  // 4) 글로벌 npm root
+  try {
+    const globalRoot = execSync('npm root -g', { encoding: 'utf8', stdio: ['pipe', 'pipe', 'ignore'] }).trim();
+    candidates.push(path.join(globalRoot, '@tobilu/qmd', QMD_CLI_REL));
+  } catch (e) {
+    // npm을 사용할 수 없는 환경
+  }
+
+  for (const p of candidates) {
+    if (p && fs.existsSync(p)) return p;
+  }
+  return null;
+}
+
+module.exports = { findQmd };