llm-wiki-kit 0.1.5 → 0.1.7

package/src/templates.js

@@ -1,31 +1,216 @@
 import { runtimeVersion } from './version.js';
 
 export function rootAgentsPolicy() {
-  return `\n<!-- llm-wiki-kit:start -->\n## LLM Wiki Policy\n\nThis repository uses llm-wiki-kit as a hook-first living Markdown wiki for Codex and Claude Code.\n\n- This block supersedes older OMX/OMC/\`omx_wiki/\` LLM Wiki instructions for this repository.\n- Treat chat memory as temporary; durable project knowledge belongs in \`llm-wiki/\`.\n- \`llm-wiki/raw/\` stores immutable or redacted source material. Do not edit raw source files.\n- \`llm-wiki/wiki/\` stores LLM-maintained knowledge pages such as decisions, architecture, debugging, context, concepts, and queries.\n- Before non-trivial work, use the injected LLM Wiki context and consult \`llm-wiki/wiki/index.md\` when present.\n- Capture reusable decisions, debugging findings, verification commands, and open questions into the wiki.\n- Preserve useful work context, but do not store raw authentication values such as tokens, passwords, or private keys.\n- Mark inference explicitly and preserve contradictions instead of silently overwriting them.\n\n<!-- llm-wiki-kit:end -->\n`;
+  return `
+<!-- llm-wiki-kit:start -->
+## LLM Wiki Policy
+
+This repository uses llm-wiki-kit as a hook-first living Markdown wiki for Codex and Claude Code.
+
+- This block supersedes older OMX/OMC/\`omx_wiki/\` LLM Wiki instructions for this repository.
+- 평소처럼 Codex 또는 Claude Code를 사용한다. 사용자가 별도 \`llm-wiki\` 명령을 외워서 실행해야 하는 흐름을 만들지 않는다.
+- 채팅 기억은 임시로 본다. 오래 남길 프로젝트 지식은 \`llm-wiki/\` Markdown에 남긴다.
+- \`llm-wiki/raw/\`는 원본 또는 redacted 근거 저장소다. hook envelope append 외에는 원본 capture를 수정하지 않는다.
+- \`llm-wiki/wiki/\`는 agent가 관리하는 지식층이다. 결정, 구조, 디버깅, 개념, 절차, 맥락을 여기에 정리한다.
+- \`llm-wiki/wiki/memory.md\`는 짧은 핵심 기억이다. 긴 설명 대신 현재 상태와 중요한 문서 링크만 유지한다.
+- 새 문서를 만들기 전에 기존 wiki 문서를 먼저 찾아 갱신한다. 반복해서 쓸 사실은 \`outputs/questions/\`에만 두지 말고 적절한 wiki 문서에 합친다.
+- 일회성 작업 기록은 \`llm-wiki/outputs/questions/\`에 보존하고, 재사용 가능한 결론은 \`wiki/architecture/\`, \`wiki/debugging/\`, \`wiki/decisions/\`, \`wiki/concepts/\`, \`procedures/\`에 반영한다.
+- 검증 명령, 근거 파일, 불확실한 점을 함께 남긴다. 추론은 추론이라고 표시하고, 모순은 지우지 말고 Open Questions 또는 Contradictions에 남긴다.
+- 인증값, token, password, private key, \`.env\` 원문은 저장하지 않는다. 필요한 경우 redacted summary만 남긴다.
+
+<!-- llm-wiki-kit:end -->
+`;
 }
 
 export function llmWikiAgents() {
-  return `# LLM Wiki Agent Rules\n\nGenerated by llm-wiki-kit ${runtimeVersion()}.\n\n## Purpose\nMaintain a living Markdown LLM Wiki from immutable source files and redacted Codex/Claude Code session events.\nThese rules supersede older OMX/OMC/\`omx_wiki/\` LLM Wiki rules for this project.\n\n## Directories\n- \`raw/\`: immutable or redacted source material. Never edit original source captures.\n- \`wiki/\`: AI-maintained knowledge pages.\n- \`outputs/\`: live Q&A summaries, reports, and generated briefs.\n- \`procedures/\`: detailed operating rules for ingest, query, lint, and security.\n\n## Core Rules\n- Never modify \`raw/\` source material except to append redacted session envelopes generated by hooks.\n- Do not state unsupported claims as facts.\n- Mark inference explicitly.\n- Add \`source_ids\` or file references for important claims.\n- Update \`wiki/index.md\` and \`wiki/log.md\` whenever new durable knowledge is created.\n- Preserve contradictions in \`Contradictions\` or \`Open Questions\` instead of overwriting them.\n- Preserve useful work context and redact authentication values before writing durable notes.\n\n## Page Format\nUse YAML frontmatter when creating wiki pages:\n\n\`\`\`yaml\n---\ntitle: \"\"\ntype: \"source | concept | entity | decision | architecture | debugging | context | query | session-log | convention\"\nsource_ids: []\nstatus: \"draft | reviewed | stale\"\nlast_updated: \"YYYY-MM-DD\"\nconfidence: \"high | medium | low\"\n---\n\`\`\`\n\n## Operations\n- ingest: read new raw files, create or update wiki pages, then update \`wiki/index.md\` and \`wiki/log.md\`.\n- query: start from \`wiki/index.md\`, read relevant wiki pages, answer with source references, and save reusable answers.\n- lint: find stale pages, orphan pages, broken wiki links, missing sources, duplicate concepts, contradictions, and missing links.\n`;
+  return `# LLM Wiki Agent Rules
+
+Generated by llm-wiki-kit ${runtimeVersion()}.
+
+## Purpose
+Codex와 Claude Code를 평소처럼 사용하는 동안 living Markdown LLM Wiki를 자연스럽게 유지한다.
+사용자가 많은 \`llm-wiki\` 명령을 직접 실행하는 방식이 아니라, agent가 작업 중 필요한 wiki 조회와 정리를 수행하는 것이 기본이다.
+이 규칙은 오래된 OMX/OMC/\`omx_wiki/\` 규칙을 대체한다.
+
+## Directories
+- \`raw/\`: 원본 또는 redacted 근거 저장소. hook이 redacted envelope를 append하는 경우 외에는 원본 capture를 수정하지 않는다.
+- \`wiki/\`: agent가 관리하는 정식 지식 문서. \`wiki/memory.md\`는 hook context에 들어가는 짧은 핵심 기억이다.
+- \`outputs/\`: live Q&A, 보고서, 긴 생성물 저장소. 일회성 기록은 여기에 둔다.
+- \`procedures/\`: ingest, query, lint, security 같은 운영 규칙.
+
+## Core Rules
+- 사용자는 Claude Code/Codex를 평소처럼 사용한다. agent가 필요한 wiki 조회와 정리를 자연스럽게 수행한다.
+- \`raw/\` 원본은 수정하지 않는다. 안전한 hook envelope append만 예외다.
+- 근거 없는 내용을 사실처럼 쓰지 않는다. 추론은 명시한다.
+- 중요한 주장에는 \`source_ids\`, 파일 경로, 검증 명령 중 하나 이상을 남긴다.
+- 오래 남길 내용이 생기면 새 문서부터 만들지 말고 기존 \`wiki/\` 문서를 먼저 찾아 갱신한다.
+- 반복해서 쓸 지식은 \`outputs/questions/\`에만 두지 말고 \`wiki/architecture/\`, \`wiki/debugging/\`, \`wiki/decisions/\`, \`wiki/concepts/\`, \`procedures/\`에 합친다.
+- \`wiki/memory.md\`는 짧게 유지한다. 긴 설명 대신 현재 상태와 중요한 문서 링크를 둔다.
+- 모순은 덮어쓰지 말고 \`Contradictions\` 또는 \`Open Questions\`에 보존한다.
+- 인증값, token, password, private key, \`.env\` 원문은 wiki에 저장하지 않는다.
+
+## Page Format
+Use YAML frontmatter when creating wiki pages:
+
+\`\`\`yaml
+---
+title: ""
+type: "source | concept | entity | decision | architecture | debugging | context | query | session-log | convention"
+source_ids: []
+status: "draft | reviewed | stale | archived"
+last_updated: "YYYY-MM-DD"
+confidence: "high | medium | low"
+memory_type: "semantic | episodic | procedural"
+importance: 1
+last_verified: "YYYY-MM-DD | unknown"
+supersedes: []
+superseded_by: []
+---
+\`\`\`
+
+## Operations
+- ingest: \`wiki/memory.md\`와 \`wiki/index.md\`를 먼저 읽고, 새 근거를 확인한 뒤 기존 wiki 문서를 우선 갱신한다.
+- query: hook이 주입한 context를 우선 사용한다. 수동 명령은 점검용이며 일반 사용 흐름의 필수 단계가 아니다.
+- lint: agent가 필요할 때 wiki 건강 상태를 점검하는 보조 도구다. 사용자가 매번 직접 실행해야 하는 명령이 아니다.
+- consolidate: agent가 \`memory.md\`/\`index.md\` generated block을 안전하게 갱신할 때 쓰는 보조 도구다. 손글씨 영역과 정식 문서 본문은 덮어쓰지 않는다.
+`;
 }
 
 export function indexPage() {
-  return `# LLM Wiki Index\n\nGenerated by llm-wiki-kit.\n\n## Overview\n\nThis is the navigation map for the project living wiki. Keep it short and useful.\n\n## Main Areas\n\n- [Sources](sources/) - source summaries and source IDs.\n- [Concepts](concepts/) - reusable concepts and terminology.\n- [Entities](entities/) - people, systems, modules, vendors, services, and tools.\n- [Decisions](decisions/) - decisions and rationale.\n- [Architecture](architecture/) - system structure and data/control flow.\n- [Debugging](debugging/) - root causes, fixes, verification evidence.\n- [Context](context/) - session continuity and project memory.\n- [Queries](queries/) - durable answers to useful questions.\n\n## Operating Notes\n\n- Start from this index before broad project questions.\n- Read 3-7 relevant pages first; inspect raw sources only when precision matters.\n- Add links using \`[[page-or-topic]]\` when pages become related.\n`;
+  return `# LLM Wiki Index
+
+Generated by llm-wiki-kit.
+
+## Overview
+
+이 파일은 living wiki의 짧은 지도다. 자세한 설명을 길게 쓰기보다, agent가 다음 작업에서 빠르게 찾아갈 entry point를 유지한다.
+
+## Main Areas
+
+- [Memory](memory.md) - 짧은 핵심 기억과 주요 entry point.
+- [Sources](sources/) - source summary와 source id.
+- [Concepts](concepts/) - 재사용 가능한 개념과 용어.
+- [Entities](entities/) - 시스템, 모듈, 도구, 서비스, 주요 객체.
+- [Decisions](decisions/) - 결정과 근거.
+- [Architecture](architecture/) - 구조와 데이터/제어 흐름.
+- [Debugging](debugging/) - 원인, 수정, 검증 evidence.
+- [Context](context/) - 세션 연속성과 프로젝트 맥락.
+- [Queries](queries/) - 재사용 가능한 질문 답변. 일회성 기록은 outputs/questions에 둔다.
+
+## Operating Notes
+
+- 넓은 질문은 memory와 이 index에서 시작한다.
+- 새 문서를 만들기 전에 관련 기존 문서 3-7개를 먼저 확인한다.
+- 오래 쓸 결론은 기존 정식 문서에 합치고, 일회성 기록은 outputs/questions에 둔다.
+- 관련 페이지가 생기면 \`[[page-or-topic]]\` 링크를 추가한다.
+
+<!-- llm-wiki-kit:index-start -->
+## Generated Page Map
+
+Agent가 필요할 때 \`llm-wiki consolidate --workspace <project>\`로 이 generated block을 갱신한다.
+<!-- llm-wiki-kit:index-end -->
+`;
+}
+
+export function memoryPage() {
+  return `---
+title: "LLM Wiki Memory"
+type: "context"
+source_ids: []
+status: "draft"
+last_updated: "unknown"
+confidence: "medium"
+memory_type: "semantic"
+importance: 5
+last_verified: "unknown"
+supersedes: []
+superseded_by: []
+---
+
+# LLM Wiki Memory
+
+짧은 핵심 기억이다. hook context에 들어갈 만큼 작게 유지하고, 긴 설명을 복사하지 말고 깊은 문서로 링크한다.
+
+## Current Focus
+
+- 오래 남길 현재 프로젝트 초점을 여기에 짧게 추가한다.
+
+## Durable Entry Points
+
+- [Index](index.md)
+- [Log](log.md)
+
+<!-- llm-wiki-kit:memory-start -->
+## Generated Memory Map
+
+Agent가 필요할 때 \`llm-wiki consolidate --workspace <project>\`로 이 generated block을 갱신한다.
+<!-- llm-wiki-kit:memory-end -->
+`;
 }
 
 export function logPage() {
-  return `# LLM Wiki Log\n\nAppend-only operating history for this project wiki.\n`;
+  return `# LLM Wiki Log
+
+Append-only operating history for this project wiki.
+`;
 }
 
 export function procedure(name) {
   const procedures = {
-    'ingest.md': `# Ingest Procedure\n\n1. Read \`wiki/index.md\` first.\n2. Inspect new material under \`raw/inbox/\` or \`raw/sources/\`.\n3. Create or update \`wiki/sources/<slug>.md\` for each source.\n4. Update related concept, entity, decision, architecture, debugging, or context pages.\n5. Prefer updating existing pages over creating duplicates.\n6. Add source references and confidence.\n7. Update \`wiki/index.md\` and append to \`wiki/log.md\`.\n`,
-    'query.md': `# Query Procedure\n\n1. Start from \`wiki/index.md\`.\n2. Search \`wiki/\` for relevant pages.\n3. Read the smallest useful set of pages first.\n4. Use raw sources only when exact evidence matters.\n5. Separate verified facts from inference.\n6. Save reusable answers into \`wiki/queries/\` and link them from related pages.\n`,
-    'lint.md': `# Lint Procedure\n\nCheck for stale pages, orphan pages, broken wiki links, missing sources, duplicate concepts, unsupported claims, and unresolved contradictions. Prefer producing a review report before automatic edits.\n`,
-    'security.md': `# Security Procedure\n\n- Preserve useful work context for the local project wiki.\n- Do not block reads or tool calls only because they look sensitive.\n- Redact authentication values such as tokens, passwords, and private keys before writing hook payloads or summaries.\n- Full raw transcript capture is disabled by default and must be explicitly enabled by project policy.\n`,
+    'ingest.md': `# Ingest Procedure
+
+1. \`wiki/memory.md\`와 \`wiki/index.md\`를 먼저 읽는다.
+2. 새 근거가 있으면 \`raw/inbox/\` 또는 \`raw/sources/\`를 확인한다.
+3. source별 요약이 필요하면 \`wiki/sources/<slug>.md\`를 만들거나 갱신한다.
+4. 새 문서부터 만들지 말고 관련 concept/entity/decision/architecture/debugging/context 문서를 먼저 찾아 갱신한다.
+5. 중복 문서를 만들지 않는다. 같은 사실이 이미 있으면 기존 문서에 합친다.
+6. 중요한 주장에는 source reference, confidence, memory type, importance, verification status를 남긴다.
+7. durable entry point가 바뀌면 \`wiki/memory.md\`를 짧게 갱신하거나 agent가 \`llm-wiki consolidate\`를 사용한다.
+8. 의미 있는 변화는 \`wiki/log.md\`에 짧게 남긴다.
+`,
+    'query.md': `# Query Procedure
+
+1. hook이 주입한 context를 먼저 사용한다. 수동으로 확인할 때만 \`llm-wiki context "<query>"\`를 쓴다.
+2. \`wiki/memory.md\`와 \`wiki/index.md\`에서 시작한다.
+3. 관련 \`wiki/\` 문서를 최소한으로 읽는다.
+4. 정확한 근거가 필요할 때만 raw source를 확인한다.
+5. 검증된 사실과 추론을 분리한다.
+6. 일회성 답변은 \`outputs/questions/\`에 남기고, 재사용 가능한 답변은 기존 \`wiki/queries/\` 또는 관련 정식 문서에 연결한다.
+7. 반복해서 쓸 결론은 \`wiki/architecture/\`, \`wiki/debugging/\`, \`wiki/decisions/\`, \`wiki/concepts/\`, \`procedures/\`에 합친다.
+`,
+    'lint.md': `# Lint Procedure
+
+\`llm-wiki lint --workspace <project>\`는 agent가 필요할 때 쓰는 wiki 건강 점검 도구다. 사용자가 매번 실행해야 하는 명령이 아니다.
+
+점검 대상: stale page, orphan page, broken wiki/Markdown link, unsafe source id, secret-like content, missing source, duplicate concept/title, unsupported claim, unresolved contradiction, outdated managed rule.
+
+자동 수정은 확실히 kit가 관리하는 영역에만 적용한다. 사용자 편집 가능성이 있는 문서는 덮어쓰지 말고 다음 작업 context에 정리 필요성을 올린다.
+`,
+    'security.md': `# Security Procedure
+
+- 로컬 프로젝트 wiki에 유용한 작업 맥락은 보존한다.
+- 입력이 민감해 보인다는 이유만으로 read/tool call을 막지 않는다.
+- token, password, bearer credential, private key, \`.env\` 원문 같은 인증값은 hook payload, summary, context pack, wiki page에 저장하기 전에 redaction한다.
+- 민감정보가 wiki에 들어갔을 가능성이 있으면 agent가 \`llm-wiki lint --workspace <project>\`를 사용해 점검한다.
+- full raw transcript capture는 기본 비활성이다. 프로젝트가 명시적으로 opt-in하고 redaction 경로가 있을 때만 허용한다.
+`,
   };
   return procedures[name] || '';
 }
 
 export function gitignore() {
-  return `# llm-wiki-kit safety defaults\nraw/sessions/*.jsonl\nraw/sessions/*.ndjson\nraw/private/\nraw_private/\nsecrets/\n*.key\n*.pem\n*.p12\n*.pfx\n.env\n.env.*\n.cache/\n`;
+  return `# llm-wiki-kit safety defaults
+raw/sessions/*.jsonl
+raw/sessions/*.ndjson
+raw/private/
+raw_private/
+secrets/
+*.key
+*.pem
+*.p12
+*.pfx
+.env
+.env.*
+.cache/
+`;
 }

package/src/update.js

@@ -1,6 +1,7 @@
 import { spawnSync } from 'child_process';
-import { resolve } from 'path';
-import { appendWikiLog, bootstrapProject } from './project.js';
+import { join, resolve } from 'path';
+import { exists } from './fs-utils.js';
+import { appendWikiLog } from './project.js';
 import { install } from './install.js';
 import { applyProjectTemplateUpdate, inspectProjectState } from './project-state.js';
 import { knownProjectRoots } from './projects.js';
@@ -34,10 +35,37 @@ function assertCommandOk(result, label) {
   throw new Error(`${label} failed: ${detail}`);
 }
 
+async function hasProjectWiki(projectRoot) {
+  return exists(join(projectRoot, 'llm-wiki', 'wiki'));
+}
+
 export function parseRegistryVersion(output) {
   return String(output || '').trim().split(/\s+/).at(-1) || '';
 }
 
+export function compareVersions(a, b) {
+  const parse = (value) => {
+    const [core, prerelease = ''] = String(value || '').trim().replace(/^v/, '').split('-', 2);
+    return {
+      nums: core.split('.').slice(0, 3).map((part) => {
+        const parsed = Number.parseInt(part, 10);
+        return Number.isFinite(parsed) ? parsed : 0;
+      }),
+      prerelease,
+    };
+  };
+  const left = parse(a);
+  const right = parse(b);
+  for (let i = 0; i < 3; i += 1) {
+    const diff = (left.nums[i] || 0) - (right.nums[i] || 0);
+    if (diff !== 0) return diff > 0 ? 1 : -1;
+  }
+  if (left.prerelease && !right.prerelease) return -1;
+  if (!left.prerelease && right.prerelease) return 1;
+  if (left.prerelease === right.prerelease) return 0;
+  return left.prerelease > right.prerelease ? 1 : -1;
+}
+
 export async function checkForUpdate(options = {}) {
   const target = options.to || 'latest';
   const installedVersion = runtimeVersion();
@@ -50,7 +78,7 @@ export async function checkForUpdate(options = {}) {
     installedVersion,
     latestVersion,
     target,
-    updateAvailable: latestVersion !== installedVersion,
+    updateAvailable: compareVersions(latestVersion, installedVersion) > 0,
   };
 }
 
@@ -60,6 +88,7 @@ export async function postUpdate(options = {}) {
     ...options,
     workspace,
     replaceHooks: true,
+    noProject: true,
   });
 
   if (options.all) {
@@ -69,7 +98,7 @@ export async function postUpdate(options = {}) {
       const projectResult = options.noProject
         ? null
         : await applyProjectTemplateUpdate(projectRoot);
-      if (!options.noProject) {
+      if (!options.noProject && await hasProjectWiki(projectRoot)) {
         await appendWikiLog(projectRoot, `llm-wiki-kit post-update applied runtime ${runtimeVersion()}; changed templates: ${projectResult.changed.length}`);
       }
       projects.push({
@@ -89,7 +118,7 @@ export async function postUpdate(options = {}) {
     ? null
     : await applyProjectTemplateUpdate(workspace);
 
-  if (!options.noProject) {
+  if (!options.noProject && await hasProjectWiki(workspace)) {
     await appendWikiLog(workspace, `llm-wiki-kit post-update applied runtime ${runtimeVersion()}; changed templates: ${projectResult.changed.length}`);
   }
 

package/src/wiki-lint.js

@@ -0,0 +1,281 @@
+import { readdir } from 'fs/promises';
+import { dirname, isAbsolute, join, parse, relative, resolve, sep } from 'path';
+import { exists, readText } from './fs-utils.js';
+import { inspectProjectState } from './project-state.js';
+import { hasSecretLikeText } from './redaction.js';
+import {
+  buildAliasMap,
+  buildWikiGraph,
+  collectWikiPages,
+  normalizeTarget,
+  resolveWikiLink,
+  wikiRoot,
+} from './wiki-model.js';
+
+const VALID_TYPES = new Set([
+  'source',
+  'concept',
+  'entity',
+  'decision',
+  'architecture',
+  'debugging',
+  'context',
+  'query',
+  'session-log',
+  'convention',
+]);
+const VALID_STATUS = new Set(['draft', 'reviewed', 'stale', 'archived']);
+const VALID_CONFIDENCE = new Set(['high', 'medium', 'low']);
+const VALID_MEMORY_TYPES = new Set(['semantic', 'episodic', 'procedural']);
+const CORE_PAGES = new Set(['wiki/index.md', 'wiki/log.md', 'wiki/memory.md']);
+
+function issue(severity, code, path, message) {
+  return { severity, code, path, message };
+}
+
+function isDateLike(value) {
+  return value === 'unknown' || /^\d{4}-\d{2}-\d{2}$/.test(String(value || ''));
+}
+
+function relativeMarkdownTarget(page, link) {
+  return resolve(dirname(page.absolutePath), link.path);
+}
+
+function isOutsideProject(projectRoot, absolutePath) {
+  const root = resolve(projectRoot);
+  const target = resolve(absolutePath);
+  const rel = relative(root, target);
+  return rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel);
+}
+
+function invalidSourceId(sourceId) {
+  const id = String(sourceId || '').trim().replace(/\\/g, '/');
+  if (!id) return true;
+  if (id.startsWith('/') || /^[a-z][a-z0-9+.-]*:/i.test(id)) return true;
+  return id.split('/').includes('..');
+}
+
+function sourceCandidates(projectRoot, sourceId) {
+  const id = String(sourceId || '').trim();
+  if (!id) return [];
+  const rawSources = join(projectRoot, 'llm-wiki', 'raw', 'sources');
+  const rawInbox = join(projectRoot, 'llm-wiki', 'raw', 'inbox');
+  const wikiSources = join(projectRoot, 'llm-wiki', 'wiki', 'sources');
+  const candidates = [
+    join(rawSources, id),
+    join(rawSources, `${id}.md`),
+    join(rawSources, `${id}.txt`),
+    join(rawInbox, id),
+    join(rawInbox, `${id}.md`),
+    join(wikiSources, id),
+    join(wikiSources, `${id}.md`),
+  ];
+  if (id.includes('/') || id.includes('\\')) {
+    candidates.push(join(projectRoot, id));
+    candidates.push(join(projectRoot, 'llm-wiki', id));
+  }
+  return candidates.map((candidate) => resolve(candidate))
+    .filter((candidate) => !isOutsideProject(projectRoot, candidate));
+}
+
+async function sourceExists(projectRoot, sourceId) {
+  for (const candidate of sourceCandidates(projectRoot, sourceId)) {
+    if (await pathExistsNormalized(candidate)) return true;
+  }
+  return false;
+}
+
+function titleKey(page) {
+  return normalizeTarget(page.title);
+}
+
+function isOrphanCandidate(page) {
+  if (CORE_PAGES.has(page.rel)) return false;
+  if (page.rel.startsWith('wiki/queries/')) return false;
+  if (page.rel.startsWith('wiki/context/')) return false;
+  return true;
+}
+
+async function pathExistsNormalized(absolutePath) {
+  if (await exists(absolutePath)) return true;
+  const target = resolve(absolutePath);
+  const parsed = parse(target);
+  const segments = target.slice(parsed.root.length).split(sep).filter(Boolean);
+  let current = parsed.root || sep;
+  for (const segment of segments) {
+    let entries = [];
+    try {
+      entries = await readdir(current);
+    } catch {
+      return false;
+    }
+    const match = entries.find((entry) => entry.normalize('NFC') === segment.normalize('NFC'));
+    if (!match) return false;
+    current = join(current, match);
+  }
+  return true;
+}
+
+export async function runLint(projectRoot, options = {}) {
+  const issues = [];
+  const root = wikiRoot(projectRoot);
+  if (!(await exists(root))) {
+    issues.push(issue('error', 'missing-wiki', 'llm-wiki/wiki', 'wiki directory does not exist'));
+    return lintResult(projectRoot, [], issues);
+  }
+
+  const pages = await collectWikiPages(projectRoot, {
+    maxFiles: options.maxFiles || 1000,
+    maxChars: options.maxChars || 75000,
+  });
+  const byRel = new Map(pages.map((page) => [page.rel, page]));
+  const aliasMap = buildAliasMap(pages);
+  const graph = buildWikiGraph(pages);
+
+  for (const rel of ['wiki/index.md', 'wiki/log.md', 'wiki/memory.md']) {
+    if (!byRel.has(rel)) {
+      issues.push(issue(rel === 'wiki/memory.md' ? 'warning' : 'error', 'missing-core-page', rel, 'core wiki page is missing'));
+    }
+  }
+
+  for (const [alias, matches] of aliasMap.entries()) {
+    if (matches.length > 1 && alias.length > 0) {
+      issues.push(issue('warning', 'duplicate-alias', matches.join(', '), `alias "${alias}" maps to multiple pages`));
+    }
+  }
+
+  const titles = new Map();
+  for (const page of pages) {
+    const key = titleKey(page);
+    if (!key) continue;
+    if (!titles.has(key)) titles.set(key, []);
+    titles.get(key).push(page.rel);
+  }
+  for (const [key, matches] of titles.entries()) {
+    if (matches.length > 1) {
+      issues.push(issue('warning', 'duplicate-title', matches.join(', '), `title "${key}" appears on multiple pages`));
+    }
+  }
+
+  for (const page of pages) {
+    if (hasSecretLikeText(page.content)) {
+      issues.push(issue('error', 'secret-like-content', page.rel, 'page contains token, credential, private-key, or secret-like text'));
+    }
+
+    if (!CORE_PAGES.has(page.rel) && !page.hasFrontmatter) {
+      issues.push(issue('warning', 'missing-frontmatter', page.rel, 'curated wiki page should have YAML frontmatter'));
+      continue;
+    }
+
+    if (page.hasFrontmatter) {
+      if (!page.type) issues.push(issue('warning', 'missing-type', page.rel, 'frontmatter is missing type'));
+      if (page.type && !VALID_TYPES.has(page.type)) issues.push(issue('error', 'invalid-type', page.rel, `invalid type: ${page.type}`));
+      if (!page.status) issues.push(issue('warning', 'missing-status', page.rel, 'frontmatter is missing status'));
+      if (page.status && !VALID_STATUS.has(page.status)) issues.push(issue('error', 'invalid-status', page.rel, `invalid status: ${page.status}`));
+      if (!page.confidence) issues.push(issue('warning', 'missing-confidence', page.rel, 'frontmatter is missing confidence'));
+      if (page.confidence && !VALID_CONFIDENCE.has(page.confidence)) issues.push(issue('error', 'invalid-confidence', page.rel, `invalid confidence: ${page.confidence}`));
+      if (page.frontmatter.memory_type && !VALID_MEMORY_TYPES.has(page.frontmatter.memory_type)) {
+        issues.push(issue('error', 'invalid-memory-type', page.rel, `invalid memory_type: ${page.frontmatter.memory_type}`));
+      }
+      if (page.frontmatter.importance !== undefined) {
+        const importance = Number(page.frontmatter.importance);
+        if (!Number.isInteger(importance) || importance < 1 || importance > 5) {
+          issues.push(issue('error', 'invalid-importance', page.rel, 'importance must be an integer from 1 to 5'));
+        }
+      }
+      if (page.frontmatter.last_updated && !isDateLike(page.frontmatter.last_updated)) {
+        issues.push(issue('warning', 'invalid-last-updated', page.rel, `last_updated should be YYYY-MM-DD or unknown: ${page.frontmatter.last_updated}`));
+      }
+      if (page.frontmatter.last_verified && !isDateLike(page.frontmatter.last_verified)) {
+        issues.push(issue('warning', 'invalid-last-verified', page.rel, `last_verified should be YYYY-MM-DD or unknown: ${page.frontmatter.last_verified}`));
+      }
+      if (page.status === 'stale') {
+        issues.push(issue('warning', 'stale-page', page.rel, 'page is marked stale'));
+      }
+    }
+
+    for (const link of page.wikilinks) {
+      const resolved = resolveWikiLink(aliasMap, link.raw, page);
+      const matches = aliasMap.get(normalizeTarget(link.target)) || [];
+      if (!resolved && matches.length === 0) {
+        issues.push(issue('error', 'broken-wikilink', page.rel, `unresolved wikilink: [[${link.raw}]]`));
+      } else if (!resolved && matches.length > 1) {
+        issues.push(issue('error', 'ambiguous-wikilink', page.rel, `ambiguous wikilink: [[${link.raw}]] -> ${matches.join(', ')}`));
+      }
+    }
+
+    for (const link of page.markdownLinks) {
+      const target = relativeMarkdownTarget(page, link);
+      if (isOutsideProject(projectRoot, target)) {
+        issues.push(issue('warning', 'outside-project-link', page.rel, `markdown link points outside project: ${link.raw}`));
+      } else if (!(await pathExistsNormalized(target))) {
+        issues.push(issue('error', 'broken-markdown-link', page.rel, `missing markdown link target: ${link.raw}`));
+      }
+    }
+
+    for (const sourceId of page.sourceIds) {
+      if (invalidSourceId(sourceId)) {
+        issues.push(issue('error', 'invalid-source-id', page.rel, 'source_id points outside the project or uses unsupported syntax'));
+        continue;
+      }
+      if (!(await sourceExists(projectRoot, sourceId))) {
+        issues.push(issue('warning', 'missing-source', page.rel, `source_id has no matching raw/wiki source file: ${sourceId}`));
+      }
+    }
+  }
+
+  const memoryText = await readText(join(projectRoot, 'llm-wiki', 'wiki', 'memory.md'), '');
+  if (Buffer.byteLength(memoryText, 'utf8') > 25000) {
+    issues.push(issue('warning', 'memory-too-large', 'wiki/memory.md', 'memory.md is larger than the hook excerpt budget'));
+  }
+  for (const page of pages.filter(isOrphanCandidate)) {
+    const backlinks = graph.backlinks.get(page.rel);
+    if (!backlinks || backlinks.size === 0) {
+      issues.push(issue('warning', 'orphan-page', page.rel, 'page is not linked from memory/index and has no backlinks'));
+    }
+  }
+
+  const projectState = await inspectProjectState(projectRoot).catch(() => null);
+  for (const file of projectState?.managedFiles || []) {
+    if (file.needsAttention) {
+      issues.push(issue('warning', 'outdated-managed-rule', file.path, 'previous llm-wiki-kit rule file appears customized; preserve user text and align it with current natural-use rules'));
+    } else if (!file.current && file.patchable) {
+      issues.push(issue('warning', 'outdated-managed-template', file.path, 'managed llm-wiki-kit rule/template can be automatically updated on the next hook or post-update run'));
+    }
+  }
+
+  return lintResult(projectRoot, pages, issues);
+}
+
+function lintResult(projectRoot, pages, issues) {
+  const errorCount = issues.filter((item) => item.severity === 'error').length;
+  const warningCount = issues.filter((item) => item.severity === 'warning').length;
+  return {
+    workspace: projectRoot,
+    ok: errorCount === 0,
+    pages: pages.length,
+    issueCount: issues.length,
+    errorCount,
+    warningCount,
+    issues,
+  };
+}
+
+export function formatLintResult(result) {
+  const lines = [
+    'llm-wiki lint',
+    `- workspace: ${result.workspace}`,
+    `- pages: ${result.pages}`,
+    `- errors: ${result.errorCount}`,
+    `- warnings: ${result.warningCount}`,
+  ];
+  if (result.issues.length === 0) {
+    lines.push('- result: ok');
+    return lines.join('\n');
+  }
+  lines.push('', 'Issues:');
+  for (const item of result.issues) {
+    lines.push(`- ${item.severity} ${item.code} ${item.path}: ${item.message}`);
+  }
+  return lines.join('\n');
+}