@kybird/llm-wiki 0.2.0

package/lib/wiki-search.js

@@ -0,0 +1,186 @@
+// wiki-search — grep 정확 매칭 + QMD 시맨틱 검색을 항상 병합해 출력한다.
+// 원본: TTSTextViewer/.agents/skills/wiki-search/scripts/search.js
+// 변경점:
+//   - __dirname '../../../../' 4단 종속 제거 → findDocRoot(), findQmd() 사용.
+//   - findstr(Windows 전용) → process.platform 분기 (win32=findstr, else=grep).
+//   - 2026-08-29 (개선계획 0-1): "QMD 성공 시 grep 건너뛰기" 분기 제거. QMD가 유사도로
+//     뭐라도 물어오면 정확 문자열 매칭이 묻히는 구조라 색인이 싱싱할수록 재현율이
+//     떨어졌다(plan.md 5.1(1)). 시맨틱은 대체재가 아니라 보완재 — 둘 다 항상 돌린다.
+//     grep 결과를 먼저 출력한다. 실무 검색어는 에러 메시지 붙여넣기가 대부분이라
+//     정확 매칭이 첫 화면에 와야 한다.
+//   - 2026-08-29 (개선계획 0-2): grep에 순위를 부여했다. 키워드마다 Set에 합치던 것을
+//     파일별 "매칭 키워드 수"로 집계해 내림차순 정렬하고, 파일명만 보여주던 것을
+//     매칭된 줄 스니펫과 함께 출력한다 (plan.md 5.1(2)).
+//   - 2026-08-29 (개선계획 1-6): 수집(collect)과 렌더(render)를 분리. --json이면
+//     {schemaVersion: 1, kind: 'search-results', ...} 봉투로 출력 — 스킬 프롬프트가
+//     사람용 출력 문자열에 깨지지 않게 하는 계약.
+const { execSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+const { findDocRoot, loadConfig } = require('./find-doc-root');
+const { findQmd } = require('./find-qmd');
+
+const MAX_SNIPPETS_PER_FILE = 3;
+const MAX_SNIPPET_LENGTH = 200;
+
+function search(query, options = {}) {
+  if (!query) {
+    console.error('Usage: llm-wiki search "<search keywords>"');
+    process.exit(1);
+  }
+
+  const docRoot = findDocRoot();
+  const wikiPath = path.join(docRoot, 'wiki');
+  const rawPath = path.join(docRoot, 'raw');
+  const config = loadConfig(docRoot);
+
+  const result = {
+    schemaVersion: 1,
+    kind: 'search-results',
+    query,
+    // grep이 정확 매칭의 본체. QMD 여부와 무관하게 항상 채워진다.
+    grep: collectGrepResults(query, wikiPath, rawPath),
+    semantic: collectQmdResults(query, config),
+  };
+
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return result;
+  }
+  renderSearchText(result);
+  return result;
+}
+
+function collectGrepResults(query, wikiPath, rawPath) {
+  // 따옴표는 findstr/grep 인용 규칙을 깨므로 키워드에서 제거.
+  const keywords = query.split(/\s+/)
+    .map(k => k.replace(/"/g, ''))
+    .filter(k => k.length > 1);
+  // 전부 1글자뿐인 극단 쿼리는 원문 하나를 통짜 키워드로.
+  if (keywords.length === 0 && query.trim()) keywords.push(query.trim());
+
+  const found = new Map(); // absPath → { keywords: Set, snippets: Map<lineText, true> }
+  const searchDirs = [wikiPath, rawPath];
+  const isWindows = process.platform === 'win32';
+
+  for (const dir of searchDirs) {
+    if (!fs.existsSync(dir)) continue;
+    for (const kw of keywords) {
+      try {
+        let grepCmd;
+        if (isWindows) {
+          // /C: 통짜 문자열 매칭(정규식 아님) — 에러 메시지의 . : ( 등이 그대로 걸린다.
+          // /M(files-only)을 쓰지 않는다 — 매칭 줄 자체가 스니펫이 된다.
+          grepCmd = `findstr /S /I /C:"${kw}" "${path.join(dir, '*.md')}"`;
+        } else {
+          // -F 고정 문자열(정규식 메타문자 무력화), -n 줄번호, -i 대소문자무시
+          grepCmd = `grep -rniF --include="*.md" -e "${kw}" "${dir}"`;
+        }
+        const output = execSync(grepCmd, { encoding: 'utf8' });
+        for (const line of output.split(/\r?\n/)) {
+          if (!line.trim()) continue;
+          const { file, snippet } = splitGrepLine(line);
+          if (!file) continue;
+          const abs = path.resolve(file);
+          if (!found.has(abs)) found.set(abs, { keywords: new Set(), snippets: new Map() });
+          const entry = found.get(abs);
+          entry.keywords.add(kw);
+          if (snippet && !entry.snippets.has(snippet)) entry.snippets.set(snippet, true);
+        }
+      } catch (e) {
+        // findstr/grep returns exit code 1 if no matches
+      }
+    }
+  }
+
+  // 정렬: 매칭 키워드 수 내림차순 → 스니펫 수 내림차순(밀도) → 경로명(안정화).
+  const files = [...found.entries()]
+    .map(([file, v]) => ({
+      file: file,
+      relativePath: path.relative(process.cwd(), file) || file,
+      title: path.basename(file, '.md'),
+      matchedKeywords: v.keywords.size,
+      totalKeywords: keywords.length,
+      snippets: [...v.snippets.keys()],
+    }))
+    .sort((a, b) =>
+      b.matchedKeywords - a.matchedKeywords ||
+      b.snippets.length - a.snippets.length ||
+      a.file.localeCompare(b.file));
+
+  return { keywords, files };
+}
+
+function collectQmdResults(query, config) {
+  const qmdPath = findQmd();
+  if (!qmdPath) return { available: false, collections: [] };
+
+  // 두 컬렉션 순회: 컴파일된 wiki + raw 로그.
+  const collections = [config.collections.wiki, config.collections.raw];
+  const results = [];
+  for (const coll of collections) {
+    try {
+      const output = execSync(`node "${qmdPath}" search "${query}" -c ${coll}`, { encoding: 'utf8', timeout: 30000 });
+      if (!isQmdEmpty(output)) results.push({ collection: coll, output: output.trim() });
+    } catch (error) {
+      // collection missing or QMD error for this collection — try next
+    }
+  }
+  return { available: true, collections: results };
+}
+
+function renderSearchText(result) {
+  const { query, grep, semantic } = result;
+  console.log(`Keyword search (grep) for: "${query}"`);
+
+  if (grep.files.length === 0) {
+    console.log('No direct matches found.');
+  } else {
+    console.log(`\nDirect matches (${grep.files.length} file(s), ranked by matched keywords):`);
+    for (const f of grep.files) {
+      console.log(`- [[${f.title}]] (${f.relativePath}) — matched ${f.matchedKeywords}/${f.totalKeywords} keywords`);
+      const shown = f.snippets.slice(0, MAX_SNIPPETS_PER_FILE);
+      for (const snippet of shown) {
+        console.log(`    │ ${snippet.length > MAX_SNIPPET_LENGTH ? snippet.slice(0, MAX_SNIPPET_LENGTH) + '…' : snippet}`);
+      }
+      if (f.snippets.length > shown.length) {
+        console.log(`    … (${f.snippets.length - shown.length} more matching line(s))`);
+      }
+    }
+  }
+
+  if (!semantic.available) {
+    console.log('\n(QMD not found — semantic search skipped. Install @tobilu/qmd to enable.)');
+    return;
+  }
+
+  console.log(`\nSemantic search via QMD: ${query}`);
+  if (semantic.collections.length === 0) {
+    console.log('No semantic results.');
+    return;
+  }
+  for (const { collection, output } of semantic.collections) {
+    console.log(`\n--- Collection: ${collection} ---`);
+    console.log(output);
+  }
+}
+
+// QMD가 빈 결과를 반환하는지 확인 (에러가 아닌 "No results found." 케이스 감지)
+function isQmdEmpty(output) {
+  if (!output || !output.trim()) return true;
+  return /^no\s+results\s+found\.\s*$/i.test(output.trim());
+}
+
+// findstr/grep 출력 행에서 경로와 매칭 줄을 분리한다.
+//   findstr:  <경로>.md:<내용>
+//   grep -n:  <경로>.md:<줄번호>:<내용>
+// 경계는 첫 `.md:`로 판정 — 윈도우 절대경로의 드라이브 콜론(`D:`)과 충돌을 피한다.
+function splitGrepLine(line) {
+  const idx = line.indexOf('.md:');
+  if (idx === -1) return { file: null, snippet: null };
+  const file = line.slice(0, idx + 3);
+  const snippet = line.slice(idx + 4).replace(/^\d+:/, ''); // POSIX grep 줄번호 제거
+  return { file, snippet: snippet.trim() };
+}
+
+module.exports = { search };

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@kybird/llm-wiki",
+  "version": "0.2.0",
+  "description": "LLM-friendly knowledge graph + kanban for AI coding agents. Raw daily logs → compiled wiki → merged semantic+grep search, and a card-per-file kanban the work-loop skill consumes unattended. Drop-in for any repo.",
+  "license": "MIT",
+  "author": "kybird",
+  "bin": {
+    "llm-wiki": "bin/llm-wiki.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "skills/",
+    "templates/",
+    "TROUBLESHOOTING.md",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kybird/llm-wiki.git"
+  },
+  "homepage": "https://github.com/kybird/llm-wiki#readme",
+  "bugs": "https://github.com/kybird/llm-wiki/issues",
+  "optionalDependencies": {
+    "@tobilu/qmd": "^2.5.3"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "wiki",
+    "kanban",
+    "llm",
+    "ai-agent",
+    "knowledge-graph",
+    "agentic-memory",
+    "claude-code",
+    "work-loop"
+  ]
+}

package/skills/kanban-plan/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: kanban-plan
+description: Planning loop — turn a plan into board cards the work-loop can consume. Cards are written only via the CLI; decompose with divergence guards, gate what isn't ready.
+skill-version: 2
+---
+# When to use
+
+- When the user plans work: a feature, a refactor, a research question, "이번 주 할 일 정리".
+- When a work session reveals follow-up work — capture it as cards immediately instead of
+  letting it evaporate with the session (plan.md 4.1의 파편화가 이것이다).
+- NOT during an unattended loop session — that runs `work-loop`, which consumes cards.
+
+# Division of labor (plan.md 2.4)
+
+- 기획(this skill) = **분해**: a plan becomes cards.
+- 개발(`work-loop`) = **해소**: pick → done.
+- QA = **수렴 강제**: fake dones get reverted; `board report` shows the ratio.
+- The person watches progress through `llm-wiki board` / `board report` / `board --html`.
+  Plan so that this one screen is enough — 리뷰가 카드 수에 비례하면 무인의 의미가 없다.
+
+# Before creating cards
+
+1. `llm-wiki search "<keywords>"` — the wall may already have an anti-pattern page or an
+   abandoned card with the reason recorded. 폐기 사유는 가장 값비싼 정보다.
+2. `llm-wiki board` — does a card for this already exist? Extend (`card edit`) or replace
+   it (`supersede`); never spawn a near-duplicate. Titles are identifiers (plan.md 3.5):
+   no numbers, no versions in titles.
+
+# Decomposition rules (divergence guards, plan.md 2.3)
+
+- One card = one context = one commit. If you cannot say what the commit would be, it is
+  too big — split it.
+- Children must be **strictly smaller** than the parent. When children replace a parent,
+  `supersede` it — the parent dissolves, it is not marked done.
+- Depth ≤ 3 (plan → subtask → task). Deeper than that means you are writing the work,
+  not planning it.
+- Do not board what is not ready to start:
+  - Time condition → `card new "<t>" --not-before 2026-09-05`. `pick` skips it until then.
+  - Observational condition → create it, then `handoff <t> --question "조건: …"`. It waits
+    in review; anyone who can show the condition holds runs `resume <t> --note "근거"`.
+
+# Question timing — start-of-work questions are the cheap ones
+
+- In a session where the person is present (planning), ask **before** boarding a card:
+  an ambiguous spec answered now costs one question; answered after an unattended loop
+  hit the wall, it costs a parked card and a night of latency.
+- The person is away, or the answer can arrive asynchronously: board the card and park it
+  immediately — `handoff <t> --question "…"` puts it in review with the question; when the
+  answer lands, `resume <t> --note "답: …"` sends it back to todo. handoff is "판정을
+  사람에게 넘기기", not "끝나고 물어보기" — timing follows whoever can answer.
+- An unattended loop session cannot ask before starting (plan.md 2.1 — 승인 대기는
+  오프피크 낭비). There, questions are recorded at the wall and answered in bulk by morning.
+
+# Card quality bar
+
+- **Goal**: one sentence a stranger can act on (`--goal`). No goal, no card.
+- **AC**: 1–4 items, each verifiable by running or looking at something objective
+  (`--ac`, repeat per item). If an AC can only be verified by "읽어보니 되는 것 같다",
+  rewrite it — the QA pass reverts evidence-free dones.
+- **Dependencies**: `--depends "다른 카드 제목"` — real DAG edges only (cycles are rejected).
+- **Notes** (`card edit --note`) are the append-only journal; timestamps are added by the CLI.
+- Every write goes through the CLI. A hand-edited card file is out of contract — 사람은 읽기만.
+
+# While the work runs
+
+- Follow-up discovered mid-task → `card new` right away, then continue. The board is the
+  memory, not the session.
+- Plan changed? `supersede` the stale cards. Direction abandoned? `abandon --reason` —
+  the reason is mandatory and flows into `doc/raw/` as anti-pattern material.
+- Do not start cards yourself in a planning session — leave them in `todo` for the
+  work-loop. 계획과 실행이 같은 세션에 섞이면 파편화가 돌아온다.

package/skills/wiki-compile/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: wiki-compile
+description: Parse raw logs to extract, synthesize, and deprecate project knowledge. Generates high-density grounded wiki pages and maintains the central index.
+skill-version: 2
+---
+# When to use
+- After accumulating raw logs in doc/raw/
+- When establishing project-wide rules or identifying recurring failures
+- Periodically to restructure the knowledge graph based on new evidence
+
+# Action
+
+## Phase 0: Preparation (Automation)
+1. **Identify New Logs**: Run `llm-wiki compile list`. Detection is date **OR** content-hash
+   based (`doc/wiki/compile-state.json`) — same-day appends to an already-compiled log are
+   caught too. The listed logs are a real to-do list for Phases 1–3, not a formality.
+2. **Context Loading**: Read the identified logs and the current `doc/wiki/index.md`.
+
+## Phase 1: High-Density Extraction (LLM)
+1. For each Case, extract:
+   - **Grounding**: Git hash, Confidence score (1-5), Evidence links.
+   - **Analytical Core**: The "Why" (First Principles) and "Trade-offs".
+   - **Taxonomy**: Concepts, Patterns, Anti-patterns.
+2. Merge similar cases, favoring the one with the highest **Confidence** and most recent **Git Hash**.
+3. **Disposition (MANDATORY, per Case)** — classify BEFORE writing any page, and state it in your output:
+   - **New**: no existing page covers this → create a page.
+   - **Update**: extends an existing page → edit that page, append the Case to its Grounding.
+   - **Merge**: duplicates/splits an existing page → fold into it; do not spawn a near-duplicate.
+   - **No material**: the Case is a one-off with no reusable lesson → skip it. Raw log is its archive.
+   A wiki that grows a page per Case diverges; thin pages dilute search. `No material` is a
+   first-class outcome, not a failure.
+
+## Phase 2: Knowledge Promotion & Synthesis (LLM)
+Synthesize extracted data into structured wiki pages. Use the following high-density templates:
+
+**Verbatim rule**: quote error messages character-for-character from the raw log — never
+paraphrase. `llm-wiki lint` back-matches every `### Error` quote against `doc/raw/`; a
+summarized quote is reported as an evidence violation.
+
+### Wiki Template (Concept)
+```markdown
+---
+status: active | deprecated | draft
+version_context: "e.g., Library X x.y"
+tags: [domain, concept]
+aliases: [synonyms]
+created: YYYY-MM-DD
+confidence: [1-5]
+---
+# [Concept Name]
+[1-2 sentence summary]
+## First Principles
+## Details
+## Related
+## Grounding (References)
+```
+
+### Wiki Template (Pattern)
+```markdown
+---
+status: active | deprecated | draft
+version_context: "e.g., Framework X x.y"
+tags: [domain, pattern]
+aliases: [synonyms]
+created: YYYY-MM-DD
+confidence: [1-5]
+---
+# [Pattern Name]
+[1-2 sentence summary]
+## The Rule
+## Why it works
+## Trade-offs
+## Anti-Pattern
+## Related
+```
+
+Anti-pattern pages use `tags: [domain, anti-pattern]` and document the failure mode + prevention checklist.
+
+## Phase 3: Conflict Resolution & Deprecation (LLM)
+1. **Contradiction Detection**: If a new Case contradicts an old wiki page, mark the old one `status: deprecated` and add `superseded_by: [[new-page]]`.
+2. **Merging**: If a new Case extends an old page, update the page and append the new Case to "Grounding (References)".
+
+## Phase 4: Indexing & Health (Automation)
+1. **Rebuild Index**: Run `llm-wiki compile index`. This automatically:
+   - Scans all files in `doc/wiki/` (including loose root files, classified by `tags`).
+   - Rebuilds the tables in `index.md`.
+   - Updates `Statistics` and `Last updated` date.
+   - Syncs the QMD search index (creates wiki + raw collections if missing, re-indexes, refreshes embeddings).
+   - Regenerates `doc/wiki/compile-state.json` (per-file hashes for same-day append detection).
+
+⚠️ **`compile index` is a "compile complete" declaration.** Running only Phase 4 without
+Phases 1–3 seals every raw log up to now as *compiled*. If the state file ever merges
+badly or goes missing, the resolution is trivial: keep either side (or delete it) and run
+`compile index` once — it is regenerated deterministically from the current `doc/raw/`.
+
+---
+
+# QMD (semantic search) notes
+
+`llm-wiki compile index` syncs the QMD search index when `@tobilu/qmd` is installed (optional). Without QMD, the wiki index still rebuilds and `llm-wiki search` falls back to grep.
+
+## GPU vs CPU mode (`QMD_LLAMA_GPU`)
+
+> **Variable name is `QMD_LLAMA_GPU`** — not `NODE_LLAMA_CPP_GPU`. The latter is read by nothing in the codebase and has no effect.
+
+- Default: GPU used automatically when available.
+- To force CPU (e.g., transient CUDA driver issue, VRAM pressure, or NVIDIA GPU asleep):
+  ```bash
+  QMD_LLAMA_GPU=false llm-wiki compile index
+  ```
+- For a permanent override on a problematic machine, set it in your shell profile or a local `.env`.
+
+## Troubleshooting build-time CUDA failures
+
+Detailed CUDA Toolkit / MSVC / node-llama-cpp prebuilt-binary diagnostics (Windows + NVIDIA specific) live in **[TROUBLESHOOTING.md](../TROUBLESHOOTING.md)** in the package root. Consult it only if `compile index` prints `falling back to using Vulkan` or `CUDA error` messages.

package/skills/wiki-lint/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: wiki-lint
+description: Validate knowledge graph integrity, detect logical conflicts, and generate a professional health report with Mermaid visualizations.
+skill-version: 1
+---
+# When to use
+- Before starting a major feature or refactor
+- After a `wiki-compile` run to ensure quality
+- Periodically to prune dead or contradictory knowledge
+
+# Action
+
+## Phase 1: Automated Integrity Check (Automation)
+1. **Run Linter**: Run `llm-wiki lint`.
+2. **Review Output**:
+   - **Broken Links**: List of `[[wikilinks]]` that point to non-existent files.
+   - **Missing Metadata**: Files missing required YAML fields or headers.
+   - **Version Drift**: Discrepancies between the project package manifest (package.json / pubspec.yaml / Cargo.toml / pyproject.toml) and wiki `version_context`.
+
+## Phase 2: Knowledge Health & Staleness (LLM)
+- Identify pages with `created:` dates older than 6 months for review.
+- Flag concepts that may have been superseded by newer entries but lack `status: deprecated`.
+
+## Phase 3: Conflict & Consistency Check (LLM)
+- Detect pages that directly contradict each other (e.g., one says "always use X", another says "avoid X").
+- When a contradiction is found, decide which is current and mark the other `deprecated` with `superseded_by:` pointing to the winner.
+
+## Phase 4: Professional Health Report
+Generate a summary in `doc/wiki/health_report.md` (or output to console):
+
+### Report Template
+```markdown
+# 🩺 Wiki Health Report (YYYY-MM-DD)
+
+## 📊 Knowledge Distribution
+\`\`\`mermaid
+pie title Knowledge Types
+    "Active Concepts" : [count]
+    "Active Patterns" : [count]
+    "Deprecated" : [count]
+    "Drafts" : [count]
+\`\`\`
+
+## ⚠️ Critical Issues
+- **Broken Links**: [List]
+- **Version Drift**: [List]
+- **Conflicts**: [List]
+
+## 🛠️ Auto-Fix Summary
+- [x] Fixed YAML indentation in 3 files
+- [x] Normalized 2 concept titles
+```
+
+## Phase 5: Auto-Fixing
+- Automatically fix common YAML formatting errors.
+- Normalize link casing to match file names.
+- Update `index.md` if any titles were normalized (run `llm-wiki compile index`).

package/skills/wiki-log/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: wiki-log
+description: Record knowledge into raw memory with Karpathy-inspired Agentic Memory format. Captures errors, decisions, and discoveries with high-density grounding.
+skill-version: 1
+---
+# When to use
+- After an error occurs or a bug is fixed
+- After making a design decision or architectural choice
+- After verifying a hypothesis or benchmarking performance
+- When discovering non-obvious behavior (library quirk, platform limitation)
+- When documenting "why" something was done a certain way
+
+# Input
+- type: error | design | verification | discovery (default: error)
+- task: what you tried to do or decided
+- error: (for type=error) error message or incorrect behavior
+- wrong_code: (for type=error) incorrect code that caused the issue
+- fix_code: corrected or final code
+- decision: (for type=design) the decision made and alternatives considered
+- result: (for type=verification) test results, benchmarks, or measurements
+- finding: (for type=discovery) what was discovered
+- environment: key package versions or context
+- is_migration_fix: boolean (true if due to version upgrade or deprecation)
+- git_hash: (optional) current git commit hash for grounding
+- confidence: (1-5) how certain are we about this knowledge
+
+# Action
+1. Determine Date Filename
+- Use current date in format: YYYY-MM-DD.md
+- File path: doc/raw/YYYY-MM-DD.md
+
+2. Concept Drift Protection (MANDATORY)
+- **Search before naming**: Use `llm-wiki search` or `ls doc/wiki/concepts/` to find existing concepts.
+- Reuse existing names to maintain a dense, high-utility knowledge graph.
+- **Collect aliases**: While searching, note every other name the same concept travels under
+  (Korean/English variants, error codes, product shorthand). Record them so compile can put
+  `aliases: [...]` in the wiki page frontmatter — search fails when the writer's word and the
+  searcher's word differ (plan.md 5.1(3)).
+
+3. Verbatim Error Preservation (MANDATORY)
+- The `### Error` section must contain the error message **character-for-character** — copy-paste,
+  never paraphrase or summarize. Later searches paste real error strings; a summarized message
+  deletes exactly the strings they would match.
+
+4. Create Entry — choose format based on type:
+
+### Type: error
+```markdown
+## Case N: [Title]
+
+### Grounding
+- Git Context: `hash:[git_hash]`
+- Evidence: [path/to/artifact or log]
+- Confidence: [1-5]/5
+
+### Error
+[error message or incorrect behavior]
+
+### Environment Context
+- Packages: [environment]
+- Migration Issue: [Yes/No]
+
+### Fix Code
+[corrected code]
+
+### Analysis
+- Root cause: [brief explanation]
+- Why it failed: [First principles analysis]
+- How it was fixed: [explanation]
+
+### Related Knowledge
+- Concepts: [[concept-name]]
+- Patterns: [[pattern-name]]
+- **Anti-Patterns**: [[what-to-avoid]]
+```
+
+### Type: design
+```markdown
+## Case N: [Title]
+
+### Grounding
+- Git Context: `hash:[git_hash]`
+- Confidence: [1-5]/5
+
+### Design Decision
+[what was decided]
+
+### Alternatives Considered
+- Option A: [description] — [why rejected]
+- Option B: [description] — [why rejected]
+- Selected: [why chosen]
+
+### Decision Code
+[code implementing the decision]
+
+### Analysis
+- Context: [situation/constraint]
+- **Trade-offs**: [Memory vs Speed / Cost vs Complexity]
+- Reversibility: [High/Low]
+
+### Related Knowledge
+- Concepts: [[concept-name]]
+- Patterns: [[pattern-name]]
+- **Anti-Patterns**: [[rejected-design-pattern]]
+```
+
+### Type: verification
+```markdown
+## Case N: [Title]
+
+### Grounding
+- Git Context: `hash:[git_hash]`
+- Artifact: [path/to/benchmark_result.json]
+- Confidence: [1-5]/5
+
+### Hypothesis
+[what was being tested]
+
+### Results
+[measurements, benchmarks]
+
+### Analysis
+- Confirmed/Refuted: [result]
+- Key metrics: [numbers]
+- Implications: [project impact]
+
+### Related Knowledge
+- Concepts: [[concept-name]]
+- Patterns: [[pattern-name]]
+```
+
+### Type: discovery
+```markdown
+## Case N: [Title]
+
+### Grounding
+- Git Context: `hash:[git_hash]`
+- Evidence: [logs or data]
+- Confidence: [1-5]/5
+
+### Discovery
+[what was found - non-obvious behavior]
+
+### Analysis
+- Why non-obvious: [Surprise factor]
+- Impact: [how this affects the project]
+- Action taken: [mitigation/leveraging]
+
+### Related Knowledge
+- Concepts: [[concept-name]]
+- Patterns: [[pattern-name]]
+```
+
+# Output
+- File created or updated: doc/raw/YYYY-MM-DD.md
+- Case anchor for direct linking: #case-N
+- **Index Update**: Run `llm-wiki compile index` to make the new case searchable (rebuilds wiki index + syncs QMD search index). If QMD is not installed, the case is still found via grep fallback.

package/skills/wiki-search/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: wiki-search
+description: Retrieve relevant past knowledge. Filters out deprecated practices and follows migration trails.
+skill-version: 1
+---
+# When to use
+- BEFORE writing any code
+- At the start of every task
+
+# Input
+- current task description
+
+# Action
+1. **Search via CLI (Recommended)**:
+   - Run: `llm-wiki search "<task keywords>"`
+   - Always runs BOTH grep exact matching AND QMD semantic search (when installed) and merges
+     them — grep results are ranked by matched-keyword count with line snippets.
+   - Prefer pasting the **verbatim error string** as the query; exact strings are what grep
+     guarantees to find.
+
+2. **Follow Links**:
+   - Use bidirectional links `[[link]]` and tags to navigate related knowledge.
+
+3. **Deprecation Check (CRITICAL)**:
+   - For every page found, check the YAML `status`.
+   - If `status: deprecated`, follow `superseded_by`.
+
+# Output Format
+- Warnings: Include any anti-patterns or recently deprecated methods found.
+- Recommendations: Based ONLY on `status: active` patterns.
+- Related cases: [[case-link]]
+
+# Answer Archiving
+- If this search produced a genuinely useful **synthesized answer** (spanning several pages,
+  the kind a future session will re-derive at real cost), promote it:
+  - Write `doc/wiki/answers/<topic>.md` — frontmatter: `status: active`, `created: YYYY-MM-DD`,
+    `tags: [...]`, `aliases: [...]`, plus the answer body with `[[links]]` back to sources.
+  - Next `llm-wiki compile index` lists it in the Answers section and it becomes searchable.
+- Archive answers, not raw search dumps: a question answered in one page does not need this.