llm-wiki-kit 0.1.6 → 0.1.7

package/README.md

@@ -74,28 +74,21 @@ The installed hooks:
 - capture decision points, debugging findings, changed files, and verification notes
 - allow tool calls to proceed without secret/PII-based hook blocking
 - update `llm-wiki/outputs/questions/YYYY-MM-DD-live-qa.md`
-- promote useful answers into `llm-wiki/wiki/queries/`
+- capture reusable-answer candidates into `llm-wiki/wiki/queries/`
 - promote decision-like turns into `llm-wiki/wiki/decisions/`
+- nudge the active LLM to fold reusable facts into existing wiki pages instead of leaving everything as one-off Q&A
+- automatically refresh managed rules/templates for older projects when the current runtime starts a session
 
 If you need to think about saving every answer manually, the setup has failed.
 
-## User-Facing Commands
+## Operational Commands
 
-```bash
-llm-wiki install --workspace /path/to/project --profile standard
-llm-wiki doctor
-llm-wiki version
-llm-wiki status --workspace /path/to/project
-llm-wiki projects --workspace /path/to/search-root
-llm-wiki update --check --workspace /path/to/project
-llm-wiki update --all --workspace /path/to/search-root
-llm-wiki update --dry-run --workspace /path/to/project
-llm-wiki update --workspace /path/to/project
-llm-wiki context "search phrase" --workspace /path/to/project
-llm-wiki lint --workspace /path/to/project
-llm-wiki consolidate --workspace /path/to/project
-llm-wiki uninstall
-```
+Most users should not need these during daily Claude Code/Codex work. They exist for install, update, diagnostics, and agent-side maintenance.
+
+- Install/update: `llm-wiki install`, `llm-wiki update`, `llm-wiki projects`
+- Diagnostics: `llm-wiki doctor`, `llm-wiki status`, `llm-wiki version`
+- Agent maintenance helpers: `llm-wiki context`, `llm-wiki lint`, `llm-wiki consolidate`
+- Cleanup: `llm-wiki uninstall`
 
 `llm-wiki status` is an offline consistency check. It reports the installed runtime version, hook targets, and whether the current workspace has the current managed templates applied.
 
@@ -103,15 +96,15 @@ llm-wiki uninstall
 
 `llm-wiki update` upgrades the global npm package, reinstalls the hook entries, and patches only managed project files such as the marked `AGENTS.md` policy block and generated `llm-wiki/AGENTS.md`/procedure files. Existing wiki content is not overwritten.
 
-`llm-wiki context "<query>"` prints the same layered context used by hooks: the short `memory.md` excerpt, the `index.md` excerpt, and MiniSearch + wikilink-expanded page hits. Use `--limit 1..50` to bound hits and `--no-expand` to disable one-hop link expansion. Context output is redacted before printing; if MiniSearch is unavailable in a source checkout, the command falls back to substring search.
+`llm-wiki context "<query>"` prints the same layered context used by hooks. It is mainly for debugging what Codex/Claude Code will see; daily use should rely on hook injection.
 
-`llm-wiki lint` checks wiki health: missing core files, invalid frontmatter, broken wikilinks, broken relative Markdown links, unsafe `source_ids`, secret-like content, missing source files, duplicate aliases/titles, stale pages, and orphan candidates. Broken links, unsafe source IDs, and secret-like content are errors; metadata and discoverability gaps are warnings.
+`llm-wiki lint` checks wiki health and detects outdated managed rules from older kit versions. Agents may use it before/after meaningful wiki maintenance.
 
-`llm-wiki consolidate` refreshes only generated marker blocks in `wiki/memory.md` and `wiki/index.md`. Handwritten notes outside those blocks are preserved. Runtime update creates `wiki/memory.md` if missing, but does not overwrite an existing memory page. Default `query`/`context`/`session-log` pages are not promoted into generated maps unless they are explicitly marked `memory_type: semantic` or `procedural` with `importance >= 4`.
+`llm-wiki consolidate` refreshes only generated marker blocks in `wiki/memory.md` and `wiki/index.md`. It is an agent maintenance helper, not a command users should run after every turn.
 
 `llm-wiki projects --workspace /apps` lists project roots that already have `llm-wiki-kit` state and shows the update commands to run. `llm-wiki update --all --workspace /apps` updates the global runtime once, then reapplies managed templates across every discovered project root under `/apps`.
 
-After a plain `npm install -g llm-wiki-kit@latest`, installed hooks point at the same global binary path. The next `SessionStart`/`InstructionsLoaded` hook automatically reapplies safe managed template updates for the active project root. This only patches generated/managed files and does not overwrite wiki content.
+After a plain `npm install -g llm-wiki-kit@latest`, existing hooks keep working when they already point at the global npm package path. The next `SessionStart`/`InstructionsLoaded` hook automatically reapplies safe managed template updates for the active project root. Clearly generated older `llm-wiki/AGENTS.md` and procedure files are refreshed even when old state is missing; user-edited files are not overwritten and are surfaced to the active agent as cleanup work. If hooks point at a source checkout or stale shim, run `llm-wiki post-update --workspace <project>` or `llm-wiki install --workspace <project>` once to reconnect them.
 
 On PCs that use nvm or user-local npm, prefer the non-sudo global install and make sure the `llm-wiki` command resolves to that npm package:
 

package/docs/concepts.md

@@ -16,10 +16,11 @@ The important behavior is a loop:
 
 1. A Claude Code or Codex session starts.
 2. `memory.md`, `index.md`, and relevant wiki context are injected automatically.
-3. The user works normally.
+3. The user works normally; no extra command loop is required.
 4. Hooks gather redacted prompt/tool/result summaries.
 5. At stop/session end, useful knowledge is written back to Markdown.
 6. Future sessions start from the improved wiki instead of relying on long chat history.
+7. When reusable knowledge appears, the active Claude Code/Codex agent folds it into existing durable wiki pages instead of leaving everything as one-off Q&A.
 
 The kit is a template/runtime repository. It must not centralize project wiki contents.
 
@@ -27,6 +28,8 @@ Runtime updates and project knowledge are separate:
 
 - npm updates replace the runtime package and hook targets.
 - project patching updates only managed policy blocks and generated procedure files.
+- old generated `llm-wiki/AGENTS.md` and procedure files are refreshed automatically when they are clearly kit-generated, even if old project state is missing.
+- user-edited files are preserved and surfaced to the agent as cleanup work.
 - `memory.md` is created when missing, then treated as project-owned content.
 - curated wiki pages remain project-owned content and are not overwritten by runtime updates.
 
@@ -35,5 +38,5 @@ The maintenance loop is intentionally layered:
 - `memory.md`: short hot index for current durable facts.
 - `index.md`: broad navigation map.
 - MiniSearch + wikilinks: retrieval over the rest of `wiki/**/*.md`, with substring fallback when MiniSearch is not installed in a source checkout.
-- `lint`: finds broken links, stale pages, duplicates, and metadata gaps.
-- `consolidate`: refreshes generated blocks in `memory.md` and `index.md` while preserving handwritten notes and keeping default query/context/session pages out of the durable generated maps.
+- `lint`: finds broken links, stale pages, duplicates, metadata gaps, secret-like content, and outdated managed rules.
+- `consolidate`: agent helper that refreshes generated blocks in `memory.md` and `index.md` while preserving handwritten notes and keeping default query/context/session pages out of the durable generated maps.

package/docs/operations.md

@@ -66,7 +66,9 @@ llm-wiki install --workspace /apps --profile standard
 
 Do not delete a project `llm-wiki/` tree to reinstall the runtime. `llm-wiki uninstall` removes hook entries only; project knowledge is intentionally left intact.
 
-## Status And Updates
+## Maintainer And Agent Reference
+
+Daily work should happen through Claude Code/Codex. These commands are for maintainer checks, troubleshooting, and agent-side maintenance.
 
 ```bash
 llm-wiki version
@@ -102,11 +104,13 @@ llm-wiki consolidate --workspace /path/to/project
 
 `update --all --workspace <search-root>` performs the npm runtime update once, then reapplies managed templates to every discovered project root under the search root.
 
-After a plain `npm install -g llm-wiki-kit@latest`, existing hooks keep pointing at the global package path. On the next `SessionStart` or `InstructionsLoaded`, the runtime automatically reapplies safe managed template updates for the active project root.
+After a plain `npm install -g llm-wiki-kit@latest`, existing hooks keep working when they already point at the global npm package path. On the next `SessionStart` or `InstructionsLoaded`, the runtime automatically reapplies safe managed template updates for the active project root. If hooks point at a source checkout or stale shim, run `llm-wiki post-update --workspace <project>` or `llm-wiki install --workspace <project>` once to reconnect them.
 
 ## Context And Wiki Maintenance
 
-`llm-wiki context "<query>"` is the manual form of hook context injection. It reads:
+Daily use should be Claude Code/Codex first. The user should not need to run a chain of `llm-wiki` commands while working. Hooks inject the context automatically, and the active agent is expected to update durable wiki pages when reusable project knowledge appears.
+
+`llm-wiki context "<query>"` is the manual debug form of hook context injection. It reads:
 
 - `llm-wiki/wiki/memory.md` as the short hot index
 - `llm-wiki/wiki/index.md` as the navigation map
@@ -114,7 +118,7 @@ After a plain `npm install -g llm-wiki-kit@latest`, existing hooks keep pointing
 - one-hop wikilink neighbors for the strongest matches
 - redacted output fields for query text, memory/index/log excerpts, hit paths, titles, snippets, matched terms, and link expansion metadata
 
-Use it when you want to inspect what the next agent turn should see:
+Use it only when you want to inspect what the next agent turn should see:
 
 ```bash
 llm-wiki context "auth architecture" --workspace /path/to/project
@@ -133,6 +137,7 @@ llm-wiki context "auth architecture" --workspace /path/to/project --limit 8 --no
 - secret-like content patterns such as tokens, password assignments, bearer credentials, and private keys
 - duplicate aliases or titles
 - stale pages and orphan candidates
+- outdated managed rules/templates from earlier `llm-wiki-kit` versions
 
 Broken links, invalid source IDs, and secret-like content are errors and return exit code 1. Metadata and discoverability gaps are warnings.
 
@@ -146,7 +151,9 @@ Broken links, invalid source IDs, and secret-like content are errors and return
 - appends a log entry when files change
 - supports `--dry-run`
 
-Run `consolidate` after meaningful wiki growth, not after every small turn.
+Agents may run `consolidate` after meaningful wiki growth. Users should not need to run it after every turn.
+
+When a new runtime sees an older project, `SessionStart`/`InstructionsLoaded` automatically reapplies safe managed template updates. Files that are clearly generated by older kit versions are refreshed. Files that look user-edited are preserved and surfaced to the active agent as cleanup context instead of being overwritten.
 
 ## Updating User-Local Or nvm Installs
 

package/docs/research/baseline.md

@@ -18,3 +18,5 @@ Important conclusions:
 - Obsidian, Graphify, MCP, and RAG can be useful extensions, but v1 must work with plain Markdown and hooks.
 - Retrieval should combine lexical search with explicit Markdown links before adding heavier external infrastructure.
 - Consolidation should be conservative: update generated blocks and navigation surfaces, but preserve human/agent-written page bodies.
+- Separate LLM API integration is not required for the current design. Claude Code and Codex already provide the reasoning/writing layer; the kit should supply context, durable files, guardrails, and safe automatic project-rule updates.
+- Heavy layers such as embeddings, graph databases, MCP tools, and hierarchical summary systems are future considerations only when project wikis become too large for the plain Markdown + hook workflow.

package/docs/research/future-large-scale.md

@@ -0,0 +1,27 @@
+# Future Large-Scale Considerations
+
+These items are not part of the current implementation plan.
+
+The current product direction is plain Markdown plus Codex/Claude Code hooks:
+
+- inject the smallest useful wiki context automatically
+- let the active LLM update durable Markdown during normal work
+- keep generated/template updates safe for older projects
+- preserve raw/wiki separation and redaction rules
+
+Consider heavier infrastructure only when real project wikis become large enough that this model fails in practice.
+
+Deferred options:
+
+- embeddings for semantic retrieval
+- graph database storage
+- MCP tools for direct wiki operations
+- GraphRAG/RAPTOR-style hierarchical summaries
+- external LLM API calls for automatic summarization
+
+Reasons to defer:
+
+- They add setup, cost, data-retention, and failure modes.
+- Codex and Claude Code already provide the LLM reasoning layer.
+- The immediate failure mode is wiki hygiene and old-template drift, not lack of model capacity.
+- Plain Markdown remains inspectable, portable, and easy to repair.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-wiki-kit",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Hook-first living LLM Wiki runtime for Codex and Claude Code.",
   "type": "module",
   "files": [

package/src/cli.js

@@ -223,6 +223,8 @@ async function listProjects(options) {
 
 function formatStatus(value) {
   const project = value.project || {};
+  const autoUpdateCount = (project.managedFiles || []).filter((file) => !file.current && file.patchable).length;
+  const attentionCount = (project.managedFiles || []).filter((file) => file.needsAttention).length;
   return [
     'llm-wiki-kit status',
     `- version: ${value.runtimeVersion}`,
@@ -235,6 +237,8 @@ function formatStatus(value) {
     `- claude hook: ${value.claudeInstalled ? 'current' : 'missing/outdated'}`,
     `- project applied runtime: ${project.lastRuntimeVersionApplied || 'unknown'}`,
     `- project templates current: ${project.managedFilesCurrent ? 'yes' : 'no'}`,
+    `- project auto-updateable rules: ${autoUpdateCount}`,
+    `- project rules needing agent cleanup: ${attentionCount}`,
   ].join('\n');
 }
 

package/src/hook.js

@@ -3,7 +3,8 @@ import { bootstrapProject, appendContextNote, appendLiveQa, appendSessionEnvelop
 import { applyProjectTemplateUpdate, inspectProjectState } from './project-state.js';
 import { recordProject } from './projects.js';
 import { summarizeForStorage } from './redaction.js';
-import { buildEntryFromState, rememberQuestion, rememberTool } from './state.js';
+import { buildEntryFromState, clearTurnState, rememberQuestion, rememberTool } from './state.js';
+import { relative } from 'path';
 
 async function readStdinJson() {
   const chunks = [];
@@ -45,7 +46,9 @@ async function autoUpdateManagedProject(projectRoot, eventName) {
   const state = await inspectProjectState(projectRoot);
   if (state.runtimeUpToDateWithProject && state.managedFilesCurrent) return;
   const result = await applyProjectTemplateUpdate(projectRoot);
-  await appendWikiLog(projectRoot, `llm-wiki-kit auto-update applied runtime ${result.runtimeVersion}; changed templates: ${result.changed.length}; skipped templates: ${result.skipped.length}`);
+  if (result.changed.length > 0) {
+    await appendWikiLog(projectRoot, `llm-wiki-kit auto-update applied runtime ${result.runtimeVersion}; changed templates: ${result.changed.length}; skipped templates: ${result.skipped.length}`);
+  }
 }
 
 export async function handleHook(provider, explicitEvent) {
@@ -96,7 +99,10 @@ export async function handleHook(provider, explicitEvent) {
       await appendLiveQa(projectRoot, entry);
       const queryPath = await writeQueryPage(projectRoot, entry);
       const decisionPath = await writeDecisionPage(projectRoot, entry);
-      await appendWikiLog(projectRoot, `captured ${eventName}${queryPath ? `; query=${queryPath}` : ''}${decisionPath ? `; decision=${decisionPath}` : ''}`);
+      await appendWikiLog(projectRoot, `captured ${eventName}${queryPath ? `; query=${relative(projectRoot, queryPath)}` : ''}${decisionPath ? `; decision=${relative(projectRoot, decisionPath)}` : ''}`);
+    }
+    if (eventName === 'Stop' || eventName === 'SessionEnd') {
+      await clearTurnState(projectRoot, payload).catch(() => {});
     }
     return {};
   }

package/src/project-state.js

@@ -27,6 +27,14 @@ function templateDescriptors() {
       path: join('llm-wiki', 'AGENTS.md'),
       content: llmWikiAgents(),
       mode: 'generated-file',
+      legacyContents: legacyLlmWikiAgentsContents(),
+      legacySignals: [
+        /^# LLM Wiki Agent Rules/m,
+        /Generated by llm-wiki-kit/m,
+        /## Purpose/m,
+        /## Core Rules/m,
+        /## Operations/m,
+      ],
     },
     {
       id: 'wiki-memory',
@@ -39,10 +47,179 @@ function templateDescriptors() {
       path: join('llm-wiki', 'procedures', name),
       content: procedure(name),
       mode: 'generated-file',
+      legacyContents: legacyProcedureContents(name),
+      legacySignals: legacyProcedureSignals(name),
     })),
   ];
 }
 
+function legacyLlmWikiAgentsContents() {
+  return [
+    `# LLM Wiki Agent Rules
+
+Generated by llm-wiki-kit <version>.
+
+## Purpose
+Maintain a living Markdown LLM Wiki from immutable source files and redacted Codex/Claude Code session events.
+These rules supersede older OMX/OMC/\`omx_wiki/\` LLM Wiki rules for this project.
+
+## Directories
+- \`raw/\`: immutable or redacted source material. Never edit original source captures.
+- \`wiki/\`: AI-maintained knowledge pages.
+- \`outputs/\`: live Q&A summaries, reports, and generated briefs.
+- \`procedures/\`: detailed operating rules for ingest, query, lint, and security.
+
+## Core Rules
+- Never modify \`raw/\` source material except to append redacted session envelopes generated by hooks.
+- Do not state unsupported claims as facts.
+- Mark inference explicitly.
+- Add \`source_ids\` or file references for important claims.
+- Update \`wiki/index.md\` and \`wiki/log.md\` whenever new durable knowledge is created.
+- Preserve contradictions in \`Contradictions\` or \`Open Questions\` instead of overwriting them.
+- Preserve useful work context and redact authentication values before writing durable notes.
+
+## 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"
+last_updated: "YYYY-MM-DD"
+confidence: "high | medium | low"
+---
+\`\`\`
+
+## Operations
+- ingest: read new raw files, create or update wiki pages, then update \`wiki/index.md\` and \`wiki/log.md\`.
+- query: start from \`wiki/index.md\`, read relevant wiki pages, answer with source references, and save reusable answers.
+- lint: find stale pages, orphan pages, broken wiki links, missing sources, duplicate concepts, contradictions, and missing links.`,
+    `# LLM Wiki Agent Rules
+
+Generated by llm-wiki-kit <version>.
+
+## Purpose
+Maintain a living Markdown LLM Wiki from immutable source files and redacted Codex/Claude Code session events.
+These rules supersede older OMX/OMC/\`omx_wiki/\` LLM Wiki rules for this project.
+
+## Directories
+- \`raw/\`: immutable or redacted source material. Never edit original source captures.
+- \`wiki/\`: AI-maintained knowledge pages. \`wiki/memory.md\` is the short hot index injected into hook context.
+- \`outputs/\`: live Q&A summaries, reports, and generated briefs.
+- \`procedures/\`: detailed operating rules for ingest, query, lint, and security.
+
+## Core Rules
+- Never modify \`raw/\` source material except to append redacted session envelopes generated by hooks.
+- Do not state unsupported claims as facts.
+- Mark inference explicitly.
+- Add \`source_ids\` or file references for important claims.
+- Update \`wiki/memory.md\`, \`wiki/index.md\`, and \`wiki/log.md\` whenever new durable knowledge changes the active project map.
+- Preserve contradictions in \`Contradictions\` or \`Open Questions\` instead of overwriting them.
+- Preserve useful work context and redact authentication values before writing durable notes.
+
+## 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"
+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: read \`wiki/memory.md\` and \`wiki/index.md\`, ingest new raw files, create or update wiki pages, then update the active map and \`wiki/log.md\`.
+- query: start from \`llm-wiki context "<query>"\` or \`wiki/memory.md\`, read relevant wiki pages, answer with source references, and save reusable answers.
+- lint: run \`llm-wiki lint --workspace <project>\` to find stale pages, orphan pages, broken wiki/Markdown links, unsafe source IDs, secret-like content, missing sources, duplicate concepts, contradictions, and missing links.
+- consolidate: run \`llm-wiki consolidate --workspace <project>\` after meaningful wiki growth to refresh generated memory/index blocks without overwriting hand-written notes. Default query/context/session-log pages are excluded unless explicitly durable.`,
+  ];
+}
+
+function legacyProcedureContents(name) {
+  const early = {
+    'ingest.md': `# Ingest Procedure
+
+1. Read \`wiki/index.md\` first.
+2. Inspect new material under \`raw/inbox/\` or \`raw/sources/\`.
+3. Create or update \`wiki/sources/<slug>.md\` for each source.
+4. Update related concept, entity, decision, architecture, debugging, or context pages.
+5. Prefer updating existing pages over creating duplicates.
+6. Add source references and confidence.
+7. Update \`wiki/index.md\` and append to \`wiki/log.md\`.`,
+    'query.md': `# Query Procedure
+
+1. Start from \`wiki/index.md\`.
+2. Search \`wiki/\` for relevant pages.
+3. Read the smallest useful set of pages first.
+4. Use raw sources only when exact evidence matters.
+5. Separate verified facts from inference.
+6. Save reusable answers into \`wiki/queries/\` and link them from related pages.`,
+    'lint.md': `# Lint Procedure
+
+Check 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.`,
+    'security.md': `# Security Procedure
+
+- Never store credentials, tokens, private keys, \`.env\` contents, customer identifiers, or private personal data.
+- Redact before writing hook payloads or summaries.
+- Full raw transcript capture is disabled by default and must be explicitly enabled by project policy.
+- If a file or prompt looks secret-bearing, do not persist it and ask for confirmation before reading further.`,
+  };
+  const layered = {
+    'ingest.md': `# Ingest Procedure
+
+1. Read \`wiki/memory.md\` and \`wiki/index.md\` first.
+2. Inspect new material under \`raw/inbox/\` or \`raw/sources/\`.
+3. Create or update \`wiki/sources/<slug>.md\` for each source.
+4. Update related concept, entity, decision, architecture, debugging, or context pages.
+5. Prefer updating existing pages over creating duplicates.
+6. Add source references, confidence, memory type, importance, and verification status.
+7. Update \`wiki/memory.md\` or run \`llm-wiki consolidate\` when durable entry points change.
+8. Update \`wiki/index.md\` and append to \`wiki/log.md\`.`,
+    'query.md': `# Query Procedure
+
+1. Start from \`llm-wiki context "<query>"\` or read \`wiki/memory.md\` and \`wiki/index.md\`.
+2. Use \`--limit\` or \`--no-expand\` when you need a narrower context pack.
+3. Search \`wiki/\` for relevant pages.
+4. Read the smallest useful set of pages first.
+5. Use raw sources only when exact evidence matters.
+6. Separate verified facts from inference.
+7. Save reusable answers into \`wiki/queries/\` and link them from related pages.`,
+    'lint.md': `# Lint Procedure
+
+Run \`llm-wiki lint --workspace <project>\` to check for stale pages, orphan pages, broken wiki/Markdown links, unsafe source IDs, secret-like content, missing sources, duplicate concepts, unsupported claims, and unresolved contradictions. Prefer producing a review report before automatic edits.`,
+    'security.md': `# Security Procedure
+
+- Preserve useful work context for the local project wiki.
+- Do not block reads or tool calls only because they look sensitive.
+- Redact authentication values such as tokens, passwords, bearer credentials, and private keys before writing hook payloads, summaries, or context packs.
+- Run \`llm-wiki lint --workspace <project>\` when sensitive material might have entered wiki pages; secret-like content is reported as an error.
+- Full raw transcript capture is disabled by default and must be explicitly enabled by project policy.`,
+  };
+  return [early[name], layered[name]].filter(Boolean);
+}
+
+function legacyProcedureSignals(name) {
+  const common = [/^# .+ Procedure/m];
+  const byName = {
+    'ingest.md': [/^# Ingest Procedure/m, /wiki\/memory\.md/, /raw\/inbox|raw\/sources/],
+    'query.md': [/^# Query Procedure/m, /llm-wiki context/, /Save reusable answers|reusable answers/],
+    'lint.md': [/^# Lint Procedure/m, /llm-wiki lint/, /stale pages|orphan pages/],
+    'security.md': [/^# Security Procedure/m, /Redact authentication values|token|private keys/, /raw transcript capture/],
+  };
+  return byName[name] || common;
+}
+
 function emptyState() {
   return {
     schemaVersion: PROJECT_STATE_SCHEMA_VERSION,
@@ -79,18 +256,24 @@ export async function writeProjectState(projectRoot, state) {
 }
 
 function replaceMarkedBlock(current, replacement) {
+  if (markerStatus(current) !== 'complete') return null;
   const start = current.indexOf(ROOT_POLICY_START);
   const end = current.indexOf(ROOT_POLICY_END);
-  if (start === -1 || end === -1 || end < start) return null;
   const afterEnd = end + ROOT_POLICY_END.length;
   return `${current.slice(0, start)}${replacement.trimStart().trimEnd()}${current.slice(afterEnd)}`;
 }
 
+function markerCount(current, marker) {
+  return current.split(marker).length - 1;
+}
+
 function markerStatus(current) {
   const start = current.indexOf(ROOT_POLICY_START);
   const end = current.indexOf(ROOT_POLICY_END);
-  if (start === -1 && end === -1) return 'missing';
-  if (start === -1 || end === -1 || end < start) return 'malformed';
+  const starts = markerCount(current, ROOT_POLICY_START);
+  const ends = markerCount(current, ROOT_POLICY_END);
+  if (starts === 0 && ends === 0) return 'missing';
+  if (starts !== 1 || ends !== 1 || end < start) return 'malformed';
   return 'complete';
 }
 
@@ -108,10 +291,39 @@ function isKnownGeneratedContent(text, descriptor) {
   return templateHash(text) === templateHash(descriptor.content);
 }
 
+function normalizeGeneratedText(text) {
+  return String(text || '')
+    .replace(/\r\n/g, '\n')
+    .replace(/Generated by llm-wiki-kit [^\n]+/g, 'Generated by llm-wiki-kit <version>.')
+    .trim();
+}
+
+function isLegacyGeneratedContent(text, descriptor) {
+  if (descriptor.mode !== 'generated-file') return false;
+  if (!Array.isArray(descriptor.legacyContents) || descriptor.legacyContents.length === 0) return false;
+  const normalized = normalizeGeneratedText(text);
+  return descriptor.legacyContents.some((content) => normalizeGeneratedText(content) === normalized);
+}
+
+function hasLegacyGeneratedSignal(text, descriptor) {
+  if (!Array.isArray(descriptor.legacySignals) || descriptor.legacySignals.length === 0) return false;
+  return descriptor.legacySignals.every((pattern) => pattern.test(text));
+}
+
+function hasKitManagedSignal(text, descriptor) {
+  if (descriptor.mode === 'marker') return markerStatus(text) !== 'missing';
+  if (descriptor.mode === 'generated-file') {
+    return isLegacyGeneratedContent(text, descriptor) || hasLegacyGeneratedSignal(text, descriptor) || /Generated by llm-wiki-kit/.test(text);
+  }
+  return false;
+}
+
 function canPatchDescriptor(state, descriptor, currentText, fileExists = true) {
   if (descriptor.mode === 'create-only') return !fileExists;
   if (descriptor.mode === 'marker') return replaceMarkedBlock(currentText, descriptor.content) !== null;
-  return isRecordedManaged(state, descriptor, currentText) || isKnownGeneratedContent(currentText, descriptor);
+  return isRecordedManaged(state, descriptor, currentText) ||
+    isKnownGeneratedContent(currentText, descriptor) ||
+    isLegacyGeneratedContent(currentText, descriptor);
 }
 
 function desiredTextForDescriptor(descriptor, currentText, fileExists = true) {
@@ -125,6 +337,10 @@ async function createOnlyParentExists(projectRoot, descriptor) {
   return exists(dirname(join(projectRoot, descriptor.path)));
 }
 
+async function descriptorParentExists(projectRoot, descriptor) {
+  return exists(dirname(join(projectRoot, descriptor.path)));
+}
+
 export async function inspectProjectState(projectRoot) {
   const state = await readProjectState(projectRoot);
   const runtime = runtimeVersion();
@@ -139,10 +355,16 @@ export async function inspectProjectState(projectRoot) {
     const currentHash = fileExists ? templateHash(currentText) : null;
     const recorded = state.managedTemplates[descriptor.id] || null;
     const markerState = descriptor.mode === 'marker' && fileExists ? markerStatus(currentText) : null;
-    const parentExists = await createOnlyParentExists(projectRoot, descriptor);
+    const parentExists = await descriptorParentExists(projectRoot, descriptor);
     const patchable = descriptor.mode === 'create-only' && !fileExists && !parentExists
       ? false
-      : (markerState === 'malformed' || canPatchDescriptor(state, descriptor, currentText, fileExists));
+      : (!fileExists && descriptor.mode === 'generated-file'
+        ? parentExists
+        : (markerState === 'malformed' ? false : canPatchDescriptor(state, descriptor, currentText, fileExists)));
+    const needsAttention = (fileExists || recorded) &&
+      !patchable &&
+      currentText !== (desiredText || '') &&
+      (fileExists ? hasKitManagedSignal(currentText, descriptor) : descriptor.mode !== 'create-only');
     const current = descriptor.mode === 'create-only'
       ? fileExists
       : fileExists && desiredText !== null && currentHash === templateHash(desiredText);
@@ -153,11 +375,12 @@ export async function inspectProjectState(projectRoot) {
       exists: fileExists,
       patchable,
       current,
+      needsAttention,
       currentHash,
       desiredHash,
       recordedHash: recorded?.hash || null,
       recordedVersion: recorded?.version || null,
-      reason: markerState === 'malformed' ? 'malformed-marker' : null,
+      reason: markerState === 'malformed' ? 'malformed-marker' : (!fileExists ? 'missing' : null),
     });
   }
 
@@ -167,11 +390,31 @@ export async function inspectProjectState(projectRoot) {
     schemaVersion: state.schemaVersion,
     lastRuntimeVersionApplied: state.lastRuntimeVersionApplied,
     runtimeUpToDateWithProject: state.lastRuntimeVersionApplied === runtime,
-    managedFilesCurrent: files.every((file) => file.current || !file.patchable),
+    managedFilesCurrent: files.every((file) => file.current || (!file.patchable && !file.needsAttention)),
     managedFiles: files,
   };
 }
 
+export function formatProjectMaintenanceContext(inspection) {
+  const files = inspection?.managedFiles || [];
+  const attention = files.filter((file) => file.needsAttention);
+  const outdated = files.filter((file) => !file.current && file.patchable);
+  if (attention.length === 0 && outdated.length === 0) return '';
+
+  const lines = [
+    'LLM Wiki maintenance note:',
+    '- 이전 버전의 llm-wiki-kit 규칙/문서가 남아 있을 수 있다.',
+    '- 확실히 kit가 관리하는 영역은 자동 갱신된다. 사용자 편집 가능성이 있는 문서는 덮어쓰지 말고 기존 내용을 보존한 채 현재 규칙에 맞게 자연스럽게 정리한다.',
+  ];
+  if (outdated.length > 0) {
+    lines.push(`- 자동 갱신 대상: ${outdated.map((file) => file.path).join(', ')}`);
+  }
+  if (attention.length > 0) {
+    lines.push(`- agent 확인 필요: ${attention.map((file) => file.path).join(', ')}`);
+  }
+  return lines.join('\n');
+}
+
 export async function recordManagedTemplates(projectRoot) {
   const state = await readProjectState(projectRoot);
   const runtime = runtimeVersion();
@@ -211,7 +454,7 @@ export async function applyProjectTemplateUpdate(projectRoot, options = {}) {
     const absolutePath = join(projectRoot, descriptor.path);
     if (!(await exists(absolutePath))) {
       if (descriptor.mode === 'create-only') {
-        if (!(await createOnlyParentExists(projectRoot, descriptor))) {
+        if (!(await descriptorParentExists(projectRoot, descriptor))) {
           skipped.push({ id: descriptor.id, path: descriptor.path, reason: 'missing-wiki' });
           continue;
         }
@@ -227,6 +470,19 @@ export async function applyProjectTemplateUpdate(projectRoot, options = {}) {
         };
         continue;
       }
+      if (descriptor.mode === 'generated-file' && await descriptorParentExists(projectRoot, descriptor)) {
+        if (!options.dryRun) {
+          await ensureDir(dirname(absolutePath));
+          await writeText(absolutePath, descriptor.content, 'utf8');
+        }
+        changed.push({ id: descriptor.id, path: descriptor.path });
+        state.managedTemplates[descriptor.id] = {
+          path: descriptor.path,
+          version: runtime,
+          hash: templateHash(descriptor.content),
+        };
+        continue;
+      }
       skipped.push({ id: descriptor.id, path: descriptor.path, reason: 'missing' });
       continue;
     }

package/src/project.js

@@ -11,7 +11,7 @@ import {
 import { LLM_WIKI_DIRS } from './constants.js';
 import { normalizeForStorage, redactText, summarizeForStorage } from './redaction.js';
 import { gitignore, indexPage, llmWikiAgents, logPage, memoryPage, procedure, rootAgentsPolicy } from './templates.js';
-import { recordManagedTemplates } from './project-state.js';
+import { formatProjectMaintenanceContext, inspectProjectState, recordManagedTemplates } from './project-state.js';
 import { buildContextPack, formatContextPack, searchWiki as searchWikiWithIndex } from './wiki-search.js';
 
 export async function bootstrapProject(projectRoot, options = {}) {
@@ -117,7 +117,7 @@ export async function appendLiveQa(projectRoot, entry) {
     entry.verification || '(not captured)',
     '',
     '### Follow-up',
-    entry.followUp || '(none captured)',
+    entry.followUp || '다음 작업에서 이 turn의 reusable fact가 있으면 기존 wiki 문서에 합치고, 일회성 기록은 이 Q&A에만 보존한다.',
     '',
   ].join('\n');
   await appendText(path, redactText(block, 12000));
@@ -163,5 +163,8 @@ export async function buildContextBrief(projectRoot, eventName, query = '') {
     includeLog: eventName === 'SessionStart',
     limit: 5,
   });
-  return formatContextPack(pack);
+  const maintenance = await inspectProjectState(projectRoot)
+    .then(formatProjectMaintenanceContext)
+    .catch(() => '');
+  return [formatContextPack(pack), maintenance].filter(Boolean).join('\n\n');
 }

package/src/state.js

@@ -1,4 +1,5 @@
 import { join } from 'path';
+import { unlink } from 'fs/promises';
 import { kitDataDir, readJson, sha256, writeJson } from './fs-utils.js';
 import { summarizeForStorage } from './redaction.js';
 
@@ -33,6 +34,10 @@ export async function writeTurnState(projectRoot, payload, state) {
   await writeJson(statePath(projectRoot, payload), state);
 }
 
+export async function clearTurnState(projectRoot, payload) {
+  await unlink(statePath(projectRoot, payload)).catch(() => {});
+}
+
 export async function rememberQuestion(projectRoot, payload, prompt) {
   const state = await readTurnState(projectRoot, payload);
   const clean = summarizeForStorage(prompt, 3000);

package/src/templates.js

@@ -1,7 +1,25 @@
 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- \`llm-wiki/wiki/memory.md\` is the short hot index for the most reusable current facts; keep it concise and link to deeper pages.\n- Before non-trivial work, use the injected LLM Wiki context and consult \`llm-wiki/wiki/memory.md\` and \`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() {
@@ -10,23 +28,26 @@ export function llmWikiAgents() {
 Generated by llm-wiki-kit ${runtimeVersion()}.
 
 ## Purpose
-Maintain a living Markdown LLM Wiki from immutable source files and redacted Codex/Claude Code session events.
-These rules supersede older OMX/OMC/\`omx_wiki/\` LLM Wiki rules for this project.
+Codex와 Claude Code를 평소처럼 사용하는 동안 living Markdown LLM Wiki를 자연스럽게 유지한다.
+사용자가 많은 \`llm-wiki\` 명령을 직접 실행하는 방식이 아니라, agent가 작업 중 필요한 wiki 조회와 정리를 수행하는 것이 기본이다.
+이 규칙은 오래된 OMX/OMC/\`omx_wiki/\` 규칙을 대체한다.
 
 ## Directories
-- \`raw/\`: immutable or redacted source material. Never edit original source captures.
-- \`wiki/\`: AI-maintained knowledge pages. \`wiki/memory.md\` is the short hot index injected into hook context.
-- \`outputs/\`: live Q&A summaries, reports, and generated briefs.
-- \`procedures/\`: detailed operating rules for ingest, query, lint, and security.
+- \`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
-- Never modify \`raw/\` source material except to append redacted session envelopes generated by hooks.
-- Do not state unsupported claims as facts.
-- Mark inference explicitly.
-- Add \`source_ids\` or file references for important claims.
-- Update \`wiki/memory.md\`, \`wiki/index.md\`, and \`wiki/log.md\` whenever new durable knowledge changes the active project map.
-- Preserve contradictions in \`Contradictions\` or \`Open Questions\` instead of overwriting them.
-- Preserve useful work context and redact authentication values before writing durable notes.
+- 사용자는 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:
@@ -36,7 +57,7 @@ Use YAML frontmatter when creating wiki pages:
 title: ""
 type: "source | concept | entity | decision | architecture | debugging | context | query | session-log | convention"
 source_ids: []
-status: "draft | reviewed | stale"
+status: "draft | reviewed | stale | archived"
 last_updated: "YYYY-MM-DD"
 confidence: "high | medium | low"
 memory_type: "semantic | episodic | procedural"
@@ -48,15 +69,47 @@ superseded_by: []
 \`\`\`
 
 ## Operations
-- ingest: read \`wiki/memory.md\` and \`wiki/index.md\`, ingest new raw files, create or update wiki pages, then update the active map and \`wiki/log.md\`.
-- query: start from \`llm-wiki context "<query>"\` or \`wiki/memory.md\`, read relevant wiki pages, answer with source references, and save reusable answers.
-- lint: run \`llm-wiki lint --workspace <project>\` to find stale pages, orphan pages, broken wiki/Markdown links, unsafe source IDs, secret-like content, missing sources, duplicate concepts, contradictions, and missing links.
-- consolidate: run \`llm-wiki consolidate --workspace <project>\` after meaningful wiki growth to refresh generated memory/index blocks without overwriting hand-written notes. Default query/context/session-log pages are excluded unless explicitly durable.
+- 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- [Memory](memory.md) - short hot index and durable entry points.\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 memory and 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\n<!-- llm-wiki-kit:index-start -->\n## Generated Page Map\n\nRun \`llm-wiki consolidate --workspace <project>\` to refresh this generated block.\n<!-- llm-wiki-kit:index-end -->\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() {
@@ -76,11 +129,11 @@ superseded_by: []
 
 # LLM Wiki Memory
 
-Short hot index for project memory. Keep this page compact enough for hook context. Link to deeper pages instead of copying long notes.
+짧은 핵심 기억이다. hook context에 들어갈 만큼 작게 유지하고, 긴 설명을 복사하지 말고 깊은 문서로 링크한다.
 
 ## Current Focus
 
-- Add the current project focus here when it becomes durable.
+- 오래 남길 현재 프로젝트 초점을 여기에 짧게 추가한다.
 
 ## Durable Entry Points
 
@@ -90,25 +143,74 @@ Short hot index for project memory. Keep this page compact enough for hook conte
 <!-- llm-wiki-kit:memory-start -->
 ## Generated Memory Map
 
-Run \`llm-wiki consolidate --workspace <project>\` to refresh this generated block.
+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/memory.md\` and \`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, confidence, memory type, importance, and verification status.\n7. Update \`wiki/memory.md\` or run \`llm-wiki consolidate\` when durable entry points change.\n8. Update \`wiki/index.md\` and append to \`wiki/log.md\`.\n`,
-    'query.md': `# Query Procedure\n\n1. Start from \`llm-wiki context \"<query>\"\` or read \`wiki/memory.md\` and \`wiki/index.md\`.\n2. Use \`--limit\` or \`--no-expand\` when you need a narrower context pack.\n3. Search \`wiki/\` for relevant pages.\n4. Read the smallest useful set of pages first.\n5. Use raw sources only when exact evidence matters.\n6. Separate verified facts from inference.\n7. Save reusable answers into \`wiki/queries/\` and link them from related pages.\n`,
-    'lint.md': `# Lint Procedure\n\nRun \`llm-wiki lint --workspace <project>\` to check for stale pages, orphan pages, broken wiki/Markdown links, unsafe source IDs, secret-like content, 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, bearer credentials, and private keys before writing hook payloads, summaries, or context packs.\n- Run \`llm-wiki lint --workspace <project>\` when sensitive material might have entered wiki pages; secret-like content is reported as an error.\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

@@ -43,6 +43,29 @@ 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();
@@ -55,7 +78,7 @@ export async function checkForUpdate(options = {}) {
     installedVersion,
     latestVersion,
     target,
-    updateAvailable: latestVersion !== installedVersion,
+    updateAvailable: compareVersions(latestVersion, installedVersion) > 0,
   };
 }
 

package/src/wiki-lint.js

@@ -1,6 +1,7 @@
 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,
@@ -23,7 +24,7 @@ const VALID_TYPES = new Set([
   'session-log',
   'convention',
 ]);
-const VALID_STATUS = new Set(['draft', 'reviewed', 'stale']);
+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']);
@@ -234,6 +235,15 @@ export async function runLint(projectRoot, options = {}) {
     }
   }
 
+  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);
 }
 

package/src/wiki-search.js

@@ -216,6 +216,9 @@ export function formatContextPack(pack) {
     '- Treat chat memory as temporary; update project Markdown when knowledge should persist.',
     '- Preserve raw/wiki separation. Do not store secrets, tokens, .env contents, private keys, or personal/customer identifiers.',
     '- Prefer updating existing wiki pages over creating duplicate pages.',
+    '- Claude Code/Codex를 평소처럼 사용한다. 사용자가 별도 명령을 실행하지 않아도 agent가 필요한 wiki 조회와 정리를 수행한다.',
+    '- 오래 쓸 지식은 outputs/questions에만 두지 말고 기존 wiki/architecture, wiki/debugging, wiki/decisions, wiki/concepts, procedures 문서에 합친다.',
+    '- wiki/memory.md는 짧은 핵심 기억으로 유지하고, 긴 설명 대신 관련 정식 문서 링크를 둔다.',
   ];
   if (pack.query) {
     lines.push(`- query: "${pack.query}"`);