llm-wiki-kit 0.2.1 → 0.2.2

package/README.md

@@ -104,6 +104,8 @@ Most users should not need these during daily Claude Code/Codex work. They exist
 
 `llm-wiki update` upgrades the global npm package when npm has a newer target, reinstalls the hook entries, and reapplies safe managed template updates across known project roots. If the installed runtime already satisfies the registry target, it skips `npm install -g` and still runs post-update maintenance. Use `--current-only` when you intentionally want to update only the supplied workspace. Existing wiki content is not overwritten.
 
+Installed npm runtimes also perform a cached update notice check from hooks while the user works. This does not install anything automatically. When a newer npm release is detected, the injected hook context tells the active agent to mention the available update and offer `llm-wiki update --workspace <project-or-search-root>`. Set `LLM_WIKI_KIT_UPDATE_NOTICE=0` only when diagnosing or suppressing that reminder.
+
 `llm-wiki post-update --workspace <project>` reapplies the current runtime's hook entries and safe managed template updates without running `npm install -g`. Use `post-update --all --workspace <search-root>` to reapply templates across discovered project roots.
 
 `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. By default, episodic `wiki/queries/` pages are excluded from search unless they were promoted with `memory_type: semantic` or `procedural` and `importance >= 4`; use `--include-episodic` only when debugging old automatic query records.

package/docs/integrations/claude-code.md

@@ -40,11 +40,12 @@ when no project `CLAUDE.md` exists. Existing `CLAUDE.md` files are not overwritt
 
 The hook records redacted turn summaries but does not deny tool calls only because an input looks sensitive. Hook payloads are stored as small redacted event envelopes rather than full transcripts, and context output is redacted field by field before it is returned to Claude Code.
 
-At `SessionStart`/`InstructionsLoaded`, the hook first attempts a safe managed-template refresh, recovers stale turn state into `outputs/maintenance/queue.md`, then injects `llm-wiki/wiki/memory.md`, `llm-wiki/wiki/index.md`, recent log context, operating rules, a one-item maintenance summary when needed, and any maintenance note for outdated or customized managed rules. At `UserPromptSubmit`, it recovers stale turn state, searches wiki pages with MiniSearch or substring fallback, expands one-hop wikilinks, redacts context fields, and injects the smallest useful context set. Maintenance reminders are shown only when the prompt is wiki/maintenance related or matches a queue topic.
+At `SessionStart`/`InstructionsLoaded`, the hook first attempts a safe managed-template refresh, recovers stale turn state into `outputs/maintenance/queue.md`, performs a cached npm update notice check for npm installs, then injects `llm-wiki/wiki/memory.md`, `llm-wiki/wiki/index.md`, recent log context, operating rules, a one-item maintenance summary when needed, any update notice, and any maintenance note for outdated or customized managed rules. At `UserPromptSubmit`, it recovers stale turn state, searches wiki pages with MiniSearch or substring fallback, expands one-hop wikilinks, redacts context fields, performs the same cached update notice check, and injects the smallest useful context set. Maintenance reminders are shown only when the prompt is wiki/maintenance related or matches a queue topic.
 
 `PostToolUse` and `PostToolBatch` record redacted tool summaries in the same turn buffer. `PreCompact` records a compaction note, and `PostCompact` records the note and returns fresh wiki context. In the default `answer-first` mode, `SubagentStop` does not create live Q&A, query, decision, or maintenance files. `Stop` and `SessionEnd` append live Q&A only for meaningful work turns and do not auto-create `wiki/queries/` or `wiki/decisions/`. If the user explicitly asked to record or document durable knowledge and no durable wiki update is detected, `Stop`/`SessionEnd` queue a pending maintenance item for agent review. `Stop` and `SessionEnd` then clear the per-session turn buffer; `SubagentStop` does not.
 
 Set `LLM_WIKI_KIT_AUTO_PROJECT_UPDATE=0` only while diagnosing automatic managed-template refresh behavior.
+Set `LLM_WIKI_KIT_UPDATE_NOTICE=0` only while suppressing the cached npm update reminder.
 Set `LLM_WIKI_KIT_CAPTURE_MODE=legacy-eager` only as deprecated compatibility mode for the old eager query/decision capture behavior.
 
 After installation or update, run:

package/docs/integrations/codex.md

@@ -29,8 +29,8 @@ Handled events:
 
 Expected behavior:
 
-- `SessionStart` first attempts a safe managed-template refresh, recovers stale turn state into `outputs/maintenance/queue.md`, then injects `llm-wiki/wiki/memory.md`, `llm-wiki/wiki/index.md`, recent log context, operating rules, a one-item maintenance summary when needed, and any maintenance note for outdated or customized managed rules.
-- `UserPromptSubmit` recovers stale turn state, searches project wiki pages with MiniSearch or substring fallback, expands one-hop wikilinks, redacts context fields, and injects the smallest useful context set. Maintenance reminders are shown only when the prompt is wiki/maintenance related or matches a queue topic.
+- `SessionStart` first attempts a safe managed-template refresh, recovers stale turn state into `outputs/maintenance/queue.md`, performs a cached npm update notice check for npm installs, then injects `llm-wiki/wiki/memory.md`, `llm-wiki/wiki/index.md`, recent log context, operating rules, a one-item maintenance summary when needed, any update notice, and any maintenance note for outdated or customized managed rules.
+- `UserPromptSubmit` recovers stale turn state, searches project wiki pages with MiniSearch or substring fallback, expands one-hop wikilinks, redacts context fields, performs the same cached update notice check, and injects the smallest useful context set. Maintenance reminders are shown only when the prompt is wiki/maintenance related or matches a queue topic.
 - `PreToolUse` records redacted tool summaries without blocking tool calls.
 - `PostToolUse` records redacted tool summaries in a turn buffer.
 - `PreCompact` records a compaction note; `PostCompact` records the note and returns fresh wiki context.
@@ -41,6 +41,7 @@ Expected behavior:
 Hook payloads are stored as small redacted event envelopes rather than full transcripts. Context output is also redacted field by field before it is returned to Codex.
 
 Set `LLM_WIKI_KIT_AUTO_PROJECT_UPDATE=0` only while diagnosing automatic managed-template refresh behavior.
+Set `LLM_WIKI_KIT_UPDATE_NOTICE=0` only while suppressing the cached npm update reminder.
 Set `LLM_WIKI_KIT_CAPTURE_MODE=legacy-eager` only as deprecated compatibility mode for the old eager query/decision capture behavior.
 
 Run these after install:

package/docs/manual.md

@@ -149,6 +149,8 @@ llm-wiki update --workspace /path/to/project --dry-run
 
 `update`는 source checkout에서 self-update하지 않는다. source checkout 개발 중에는 npm package나 local tarball로 global install한 뒤 update behavior를 테스트한다.
 
+global npm runtime으로 설치된 경우 hook은 사용 흐름 중 cached update notice check를 수행한다. 자동 설치는 하지 않는다. 새 npm release가 감지되면 hook context가 active agent에게 “업데이트 가능”을 짧게 알리고 `llm-wiki update --workspace <project-or-search-root>` 실행을 제안하게 한다. `LLM_WIKI_KIT_UPDATE_NOTICE=0`으로 이 reminder만 끌 수 있다.
+
 ### `llm-wiki post-update`
 
 npm install 없이 현재 runtime으로 hook entries와 managed project templates를 다시 적용한다.

package/docs/operations.md

@@ -101,6 +101,8 @@ llm-wiki maintenance --workspace /path/to/project
 
 `update --check [--to <version-or-tag>]` is online and asks npm for the target version. It reports `update available` only when that registry target is newer than the installed version, so it does not suggest downgrades.
 
+Installed npm runtimes also run a cached hook-side update notice check while the user works. It never installs automatically. If npm has a newer release, `SessionStart`/`InstructionsLoaded`/`UserPromptSubmit` context tells the active agent to mention the available update and offer `llm-wiki update --workspace <project-or-search-root>`. Set `LLM_WIKI_KIT_UPDATE_NOTICE=0` to suppress this reminder while diagnosing.
+
 `projects --workspace <search-root>` lists discovered project roots that have `llm-wiki/.kit-state.json` or an older `llm-wiki/wiki/index.md`, reports whether their managed templates are current, and prints the update commands for the search root.
 
 `update` applies changes explicitly only when the user runs it:

package/package.json

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

package/src/cli.js

@@ -279,6 +279,7 @@ function formatUpdate(value) {
       `- installed: ${value.installedVersion}`,
       `- latest: ${value.latestVersion}`,
       `- update available: ${value.updateAvailable ? 'yes' : 'no'}`,
+      ...(value.updateAvailable ? [`- recommended action: ${commandForProject('update', value.workspace)}`] : []),
       `- project applied runtime: ${value.project?.lastRuntimeVersionApplied || 'unknown'}`,
     ].join('\n');
   }
@@ -295,6 +296,7 @@ function formatUpdate(value) {
       `- installed: ${value.installedVersion}`,
       `- latest: ${value.latestVersion}`,
       `- update available: ${value.updateAvailable ? 'yes' : 'no'}`,
+      ...(value.updateAvailable ? [`- recommended action: ${commandForProject('update', value.workspace)}`] : []),
       `- scope: ${value.scope || 'current'}`,
       ...(projects.length > 0 ? [`- projects checked: ${projects.length}`] : []),
       `- project template changes: ${changed}`,

package/src/hook.js

@@ -6,6 +6,7 @@ import { applyProjectTemplateUpdate, inspectProjectState } from './project-state
 import { recordProject } from './projects.js';
 import { summarizeForStorage } from './redaction.js';
 import { buildEntryFromState, clearTurnState, rememberQuestion, rememberTool } from './state.js';
+import { updateNoticeContext } from './update-notice.js';
 import { relative } from 'path';
 
 async function readStdinJson() {
@@ -42,6 +43,13 @@ function contextOutput(eventName, context) {
   };
 }
 
+async function hookContext(projectRoot, eventName, context, payload) {
+  const notice = await updateNoticeContext(projectRoot, eventName, {
+    session: payload.session_id || payload.sessionId,
+  });
+  return [context, notice].filter(Boolean).join('\n\n');
+}
+
 async function handleLegacyEagerStop(projectRoot, eventName, payload, entry) {
   if (entry.question !== '(not captured)' || entry.result !== '(not captured)') {
     const liveQaPath = await appendLiveQa(projectRoot, entry);
@@ -111,7 +119,7 @@ export async function handleHook(provider, explicitEvent) {
   }
 
   if (eventName === 'SessionStart' || eventName === 'InstructionsLoaded') {
-    const context = await buildContextBrief(projectRoot, 'SessionStart');
+    const context = await hookContext(projectRoot, eventName, await buildContextBrief(projectRoot, 'SessionStart'), payload);
     return contextOutput(eventName, context);
   }
 
@@ -119,7 +127,12 @@ export async function handleHook(provider, explicitEvent) {
     const prompt = promptText(payload);
     await rememberQuestion(projectRoot, payload, prompt);
     const guidance = formatDurableCaptureGuidance(prompt);
-    const context = [await buildContextBrief(projectRoot, eventName, prompt), guidance].filter(Boolean).join('\n\n');
+    const context = await hookContext(
+      projectRoot,
+      eventName,
+      [await buildContextBrief(projectRoot, eventName, prompt), guidance].filter(Boolean).join('\n\n'),
+      payload
+    );
     return contextOutput(eventName, context);
   }
 

package/src/update-notice.js

@@ -0,0 +1,120 @@
+import { spawnSync } from 'child_process';
+import { join, resolve } from 'path';
+import { cacheHome, readJson, writeJson } from './fs-utils.js';
+import { commandForProject } from './projects.js';
+import { compareVersions, parseRegistryVersion } from './update.js';
+import { detectInstallSource, packageName, runtimeVersion } from './version.js';
+
+const NOTICE_SCHEMA_VERSION = 1;
+const DEFAULT_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const DEFAULT_TIMEOUT_MS = 3000;
+
+function noticeCachePath() {
+  return join(cacheHome(), 'llm-wiki-kit', 'update-notice.json');
+}
+
+function npmCommand() {
+  return process.env.LLM_WIKI_KIT_NPM || 'npm';
+}
+
+function numberEnv(name, fallback) {
+  const raw = process.env[name];
+  if (!raw) return fallback;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : fallback;
+}
+
+function intervalMs() {
+  if (process.env.LLM_WIKI_KIT_UPDATE_NOTICE_INTERVAL_MS) {
+    return numberEnv('LLM_WIKI_KIT_UPDATE_NOTICE_INTERVAL_MS', DEFAULT_INTERVAL_MS);
+  }
+  return numberEnv('LLM_WIKI_KIT_UPDATE_NOTICE_INTERVAL_HOURS', 24) * 60 * 60 * 1000;
+}
+
+function timeoutMs() {
+  return numberEnv('LLM_WIKI_KIT_UPDATE_NOTICE_TIMEOUT_MS', DEFAULT_TIMEOUT_MS);
+}
+
+function noticeEnabled() {
+  if (process.env.LLM_WIKI_KIT_UPDATE_NOTICE === '0') return false;
+  if (detectInstallSource() === 'source' && process.env.LLM_WIKI_KIT_UPDATE_NOTICE_ALLOW_SOURCE !== '1') {
+    return false;
+  }
+  return true;
+}
+
+function freshEnough(record, now = Date.now()) {
+  const checkedAt = Date.parse(record?.checkedAt || '');
+  return Number.isFinite(checkedAt) && now - checkedAt < intervalMs();
+}
+
+function cacheMatches(record, target, installedVersion) {
+  return record?.schemaVersion === NOTICE_SCHEMA_VERSION &&
+    record.target === target &&
+    record.installedVersion === installedVersion;
+}
+
+function trimDetail(value) {
+  return String(value || '').trim().slice(0, 500);
+}
+
+function checkRegistry(target) {
+  const result = spawnSync(npmCommand(), ['view', `${packageName()}@${target}`, 'version'], {
+    encoding: 'utf8',
+    timeout: timeoutMs(),
+  });
+  if (result.status !== 0 || result.error) {
+    return {
+      latestVersion: null,
+      updateAvailable: false,
+      error: trimDetail(result.stderr) || trimDetail(result.stdout) || result.error?.message || 'unknown npm registry check error',
+    };
+  }
+  const latestVersion = parseRegistryVersion(result.stdout);
+  return {
+    latestVersion,
+    updateAvailable: compareVersions(latestVersion, runtimeVersion()) > 0,
+    error: null,
+  };
+}
+
+export async function checkUpdateNotice(options = {}) {
+  if (!noticeEnabled()) return null;
+  const target = options.to || process.env.LLM_WIKI_KIT_UPDATE_NOTICE_TARGET || 'latest';
+  const installedVersion = runtimeVersion();
+  const cachePath = noticeCachePath();
+  const cached = await readJson(cachePath, null);
+  if (!options.force && cacheMatches(cached, target, installedVersion) && freshEnough(cached)) {
+    return cached;
+  }
+
+  const checkedAt = new Date().toISOString();
+  const registry = checkRegistry(target);
+  const record = {
+    schemaVersion: NOTICE_SCHEMA_VERSION,
+    checkedAt,
+    target,
+    installedVersion,
+    ...registry,
+  };
+  await writeJson(cachePath, record).catch(() => {});
+  return record;
+}
+
+export async function updateNoticeContext(projectRoot, eventName, options = {}) {
+  if (!['SessionStart', 'InstructionsLoaded', 'UserPromptSubmit'].includes(eventName)) return '';
+  const notice = await checkUpdateNotice(options).catch(() => null);
+  if (!notice?.updateAvailable) return '';
+
+  const workspace = resolve(projectRoot || process.cwd());
+  const updateCommand = commandForProject('update', workspace);
+  return [
+    'LLM Wiki update notice:',
+    `- Installed llm-wiki-kit: ${notice.installedVersion}`,
+    `- Latest npm release: ${notice.latestVersion}`,
+    `- A newer llm-wiki-kit release was detected automatically while the user was using the hooks.`,
+    `- Briefly tell the user an update is available and offer to run: \`${updateCommand}\``,
+    '- If the user wants every known project root updated, use the broader search root in the same command, for example `--workspace /apps`.',
+    '- Do not install automatically unless the user asks for the update.',
+  ].join('\n');
+}