llm-wiki-kit 0.1.4 → 0.1.6

package/README.md

@@ -47,6 +47,7 @@ llm-wiki/
 ├── raw/
 ├── wiki/
 │   ├── index.md
+│   ├── memory.md
 │   ├── log.md
 │   ├── sources/
 │   ├── concepts/
@@ -60,7 +61,7 @@ llm-wiki/
 └── procedures/
 ```
 
-`raw/` is the immutable or redacted evidence layer. `wiki/` is the LLM-maintained knowledge layer. `outputs/` stores live Q&A and requested reports. `.kit-state.json` records which runtime version last applied managed templates to the project. Text written by the kit is normalized to NFC so Korean filenames and content stay composed.
+`raw/` is the immutable or redacted evidence layer. `wiki/` is the LLM-maintained knowledge layer. `wiki/memory.md` is the short hot index injected into hook context before deeper search results. `outputs/` stores live Q&A and requested reports. `.kit-state.json` records which runtime version last applied managed templates to the project. Text written by the kit is normalized to NFC so Korean filenames and content stay composed.
 
 ## Normal Use
 
@@ -68,7 +69,7 @@ Use Claude Code or Codex normally.
 
 The installed hooks:
 
-- inject relevant wiki context at session start and prompt submit time
+- inject `wiki/memory.md`, `wiki/index.md`, and relevant wiki context at session start and prompt submit time
 - record redacted turn summaries
 - capture decision points, debugging findings, changed files, and verification notes
 - allow tool calls to proceed without secret/PII-based hook blocking
@@ -83,12 +84,16 @@ If you need to think about saving every answer manually, the setup has failed.
 ```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
 ```
 
@@ -98,10 +103,34 @@ 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 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 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 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.
 
+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:
+
+```bash
+npm install -g llm-wiki-kit@latest --registry=https://registry.npmjs.org/ --prefer-online
+which -a llm-wiki
+readlink -f "$(command -v llm-wiki)"
+llm-wiki version
+llm-wiki status
+```
+
+If `which -a llm-wiki` shows a stale `~/.local/bin/llm-wiki` before the nvm/npm global binary, remove only that file, not the whole `~/.local/bin` directory:
+
+```bash
+rm -f "$HOME/.local/bin/llm-wiki"
+hash -r
+llm-wiki version
+```
+
 Real `update --check` and `update` require the package to exist in the npm registry. Before publication, use local tarball installs for smoke testing and fake npm in automated tests.
 
 The hook subcommands are internal runtime targets:
@@ -126,6 +155,7 @@ Source checkout installs are supported for development:
 ```bash
 git clone <your-git-url>/llm-wiki-kit.git /apps/llm-wiki-kit
 cd /apps/llm-wiki-kit
+npm install
 ./install.sh --workspace /apps --profile standard
 node --test
 ```

package/docs/concepts.md

@@ -8,17 +8,18 @@ raw sources -> wiki -> schema/rules
 
 - `raw/` is evidence. It is immutable unless a hook appends a redacted event envelope.
 - `wiki/` is the living Markdown knowledge layer maintained by the agent.
+- `wiki/memory.md` is the compact hot index that keeps the most reusable current facts close to the context window.
 - `AGENTS.md`, `CLAUDE.md`, and `procedures/` are the schema/rules layer.
 - `.kit-state.json` records which managed rules/templates were applied by which runtime version.
 
 The important behavior is a loop:
 
 1. A Claude Code or Codex session starts.
-2. Relevant wiki context is injected automatically.
+2. `memory.md`, `index.md`, and relevant wiki context are injected automatically.
 3. The user works normally.
 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.
+6. Future sessions start from the improved wiki instead of relying on long chat history.
 
 The kit is a template/runtime repository. It must not centralize project wiki contents.
 
@@ -26,4 +27,13 @@ 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.
+- `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.
+
+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.

package/docs/integrations/claude-code.md

@@ -40,6 +40,8 @@ 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.
 
+At `SessionStart`/`InstructionsLoaded`, the hook injects `llm-wiki/wiki/memory.md`, `llm-wiki/wiki/index.md`, recent log context, and operating rules. At `UserPromptSubmit`, it searches wiki pages with MiniSearch or substring fallback, expands one-hop wikilinks, redacts context fields, and injects the smallest useful context set.
+
 After installation or update, run:
 
 ```bash

package/docs/integrations/codex.md

@@ -29,8 +29,8 @@ Handled events:
 
 Expected behavior:
 
-- `SessionStart` injects `llm-wiki/wiki/index.md`, recent log context, and operating rules.
-- `UserPromptSubmit` searches project wiki pages and injects the smallest useful context set.
+- `SessionStart` injects `llm-wiki/wiki/memory.md`, `llm-wiki/wiki/index.md`, recent log context, and operating rules.
+- `UserPromptSubmit` searches project wiki pages with MiniSearch or substring fallback, expands one-hop wikilinks, redacts context fields, and injects the smallest useful context set.
 - `PreToolUse` records redacted tool summaries without blocking tool calls.
 - `PostToolUse` records redacted tool summaries in a turn buffer.
 - `Stop` writes live Q&A and durable wiki pages.

package/docs/operations.md

@@ -47,9 +47,12 @@ The installer:
 - bootstraps the workspace `llm-wiki/`
 - records managed template state in `llm-wiki/.kit-state.json`
 
+Use `llm-wiki install --no-project` only when you want hook/bin installation without bootstrapping the current workspace as a project.
+
 Source checkout installs are still useful for development:
 
 ```bash
+npm install
 ./install.sh --workspace /apps --profile standard
 ```
 
@@ -66,12 +69,16 @@ Do not delete a project `llm-wiki/` tree to reinstall the runtime. `llm-wiki uni
 ## Status And Updates
 
 ```bash
+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
 ```
 
 `status` is offline and answers whether the local installation is internally consistent:
@@ -97,12 +104,94 @@ llm-wiki update --workspace /path/to/project
 
 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.
 
+## Context And Wiki Maintenance
+
+`llm-wiki context "<query>"` is the manual 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
+- MiniSearch results from `llm-wiki/wiki/**/*.md`, with substring fallback when MiniSearch is unavailable
+- 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:
+
+```bash
+llm-wiki context "auth architecture" --workspace /path/to/project
+llm-wiki context "auth architecture" --workspace /path/to/project --json
+llm-wiki context "auth architecture" --workspace /path/to/project --limit 8 --no-expand
+```
+
+`llm-wiki lint` checks Markdown wiki health without modifying files:
+
+- missing `index.md`, `log.md`, or `memory.md`
+- missing or invalid frontmatter
+- broken or ambiguous `[[wikilinks]]`
+- broken relative Markdown links, including non-Markdown local files
+- invalid path-escaping or protocol-style `source_ids`
+- missing source files referenced by valid `source_ids`
+- secret-like content patterns such as tokens, password assignments, bearer credentials, and private keys
+- duplicate aliases or titles
+- stale pages and orphan candidates
+
+Broken links, invalid source IDs, and secret-like content are errors and return exit code 1. Metadata and discoverability gaps are warnings.
+
+`llm-wiki consolidate` performs conservative generated-block maintenance:
+
+- refreshes the generated block inside `wiki/memory.md`
+- refreshes the generated block inside `wiki/index.md`
+- excludes default `query`, `context`, and `session-log` pages from generated maps unless they are explicitly durable (`memory_type: semantic` or `procedural`, `importance >= 4`)
+- skips malformed generated marker blocks instead of overwriting them
+- preserves handwritten content outside marker blocks
+- appends a log entry when files change
+- supports `--dry-run`
+
+Run `consolidate` after meaningful wiki growth, not after every small turn.
+
+## Updating User-Local Or nvm Installs
+
+When Node is managed by nvm, update as the normal user instead of using `sudo`. `sudo npm install -g` writes to root's npm environment and may also fail behind a proxy/TLS-inspection network.
+
+```bash
+npm install -g llm-wiki-kit@latest --registry=https://registry.npmjs.org/ --prefer-online
+llm-wiki version
+llm-wiki status --workspace /path/to/project
+```
+
+If `npm install -g` reports success but `llm-wiki` still prints old help output, inspect the command resolution:
+
+```bash
+which -a llm-wiki
+readlink -f "$(command -v llm-wiki)"
+npm root -g
+node "$(npm root -g)/llm-wiki-kit/bin/llm-wiki.js" version
+```
+
+When `which -a llm-wiki` shows `~/.local/bin/llm-wiki` before the nvm global binary, remove only that stale command file:
+
+```bash
+rm -f "$HOME/.local/bin/llm-wiki"
+hash -r
+llm-wiki version
+```
+
+Do not delete the whole `~/.local/bin` directory. It may contain unrelated user tools.
+
+Use package-name-only uninstall syntax:
+
+```bash
+npm uninstall -g llm-wiki-kit
+```
+
+`npm uninstall -g llm-wiki-kit@latest` is not the right form and does not remove source checkouts or stale manually-created shims.
+
 Managed project files are conservative:
 
 - root `AGENTS.md` is patched only inside the `llm-wiki-kit` marker block
-- `llm-wiki/AGENTS.md` is replaced only when it is generated by the kit
-- generated procedures are replaced only when their recorded hash still matches or their content is a known generated template
-- `llm-wiki/wiki/index.md` and existing wiki pages are not overwritten
+- `llm-wiki/AGENTS.md` is replaced only when its recorded hash still matches or the whole file exactly matches the current generated template
+- generated procedures are replaced only when their recorded hash still matches or the whole file exactly matches the current generated template
+- `llm-wiki/wiki/memory.md` is created if missing but never overwritten by template update once it exists
+- `llm-wiki/wiki/index.md` and existing wiki pages are not overwritten by runtime update; `llm-wiki consolidate` updates only its generated marker block
 
 Real registry checks require `llm-wiki-kit` to be published to npm. Before publication, `llm-wiki update --check` returns npm 404. Use fake npm in tests or local tarball install for server smoke checks.
 

package/docs/research/baseline.md

@@ -10,9 +10,11 @@ Important conclusions:
 - The durable pattern is `raw sources -> wiki -> schema`.
 - `raw/` and `wiki/` must not be mixed.
 - `index.md` should be a small navigation surface.
+- `memory.md` should be an even smaller hot index for the facts most likely to matter in the next turn.
 - `log.md` should be append-only.
 - Good answers should be written back into the wiki instead of remaining in chat history.
 - Duplicate and stale pages are major failure modes.
 - Full automation without human review is risky for large imports or high-stakes decisions.
 - 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.

package/docs/security.md

@@ -11,4 +11,6 @@ Before writing durable summaries, the runtime redacts authentication values such
 - private key blocks
 - bearer credentials
 
+Manual and hook context output also runs through redaction before returning excerpts or search hits. `llm-wiki lint` reports remaining secret-like wiki content as an error so it can be removed or rewritten before it becomes reusable project memory.
+
 Hook payloads are stored as small event envelopes, not full raw transcripts. Full transcript capture is intentionally not implemented as a default. If a project needs it, add a project-local policy and a redaction path first.

package/docs/troubleshooting.md

@@ -71,6 +71,54 @@ sudo npm install -g llm-wiki-kit@latest
 
 If the proxy performs TLS inspection, install the organization's CA and set `cafile` instead of disabling TLS verification. As a temporary diagnostic only, `sudo npm config set strict-ssl false` can confirm that the failure is CA-related, but do not keep that setting in production.
 
+## npm install -g Succeeds But llm-wiki Is Still Old
+
+If `npm install -g llm-wiki-kit@latest` succeeds but `llm-wiki --help` does not show newer commands such as `projects`, `context`, `lint`, or `consolidate`, the shell is probably executing an older source checkout or stale shim before the npm global binary.
+
+Confirm what is actually running:
+
+```bash
+which -a llm-wiki
+readlink -f "$(command -v llm-wiki)"
+npm ls -g llm-wiki-kit --depth=0
+npm root -g
+node "$(npm root -g)/llm-wiki-kit/bin/llm-wiki.js" version
+```
+
+If the direct `node "$(npm root -g)/llm-wiki-kit/bin/llm-wiki.js" version` command prints the latest version but plain `llm-wiki` is old, fix `PATH` or replace the stale shim:
+
+```bash
+mkdir -p "$HOME/.local/bin"
+ln -sfn "$(npm root -g)/llm-wiki-kit/bin/llm-wiki.js" "$HOME/.local/bin/llm-wiki"
+export PATH="$HOME/.local/bin:$PATH"
+hash -r
+llm-wiki status
+```
+
+If `readlink -f "$(command -v llm-wiki)"` points at a repository checkout such as `/mnt/d/dev_proj/llm-wiki-kit/bin/llm-wiki.js`, `npm install -g` is not updating that checkout. Either switch the shim to the npm package as above, or update the checkout itself with `git pull` and run it intentionally as source.
+
+If `which -a llm-wiki` shows both `~/.local/bin/llm-wiki` and an nvm path such as `~/.nvm/versions/node/v20.20.2/bin/llm-wiki`, the `~/.local/bin` entry usually wins because it appears earlier on `PATH`. If the `~/.local/bin/llm-wiki` file is stale, remove only that file and let the nvm npm global command take over:
+
+```bash
+rm -f "$HOME/.local/bin/llm-wiki"
+hash -r
+which -a llm-wiki
+readlink -f "$(command -v llm-wiki)"
+llm-wiki version
+llm-wiki status
+```
+
+Do not remove the entire `~/.local/bin` directory; it may contain unrelated commands. If the nvm command is missing after removing the stale file, reinstall the package in the active nvm Node version:
+
+```bash
+npm uninstall -g llm-wiki-kit
+npm install -g llm-wiki-kit@latest --registry=https://registry.npmjs.org/ --prefer-online
+hash -r
+llm-wiki version
+```
+
+Use `npm uninstall -g llm-wiki-kit` with the package name only. `npm uninstall -g llm-wiki-kit@latest` is not the correct uninstall syntax and does not remove source checkouts or manually-created command shims.
+
 ## npm install -g Fails With EACCES
 
 If npm tries to write under `/usr` and fails with `EACCES`, use sudo when the server policy allows system-wide global packages:
@@ -127,7 +175,14 @@ The hook does not block tool calls only because inputs look sensitive. Durable s
 Run a manual review:
 
 ```bash
+llm-wiki lint --workspace /path/to/project
 rg -n "title:|aliases:|source_ids:" llm-wiki/wiki
 ```
 
 Prefer merging duplicates into existing pages and preserving contradictions in an `Open Questions` section.
+
+After merging or adding durable pages, refresh generated navigation blocks:
+
+```bash
+llm-wiki consolidate --workspace /path/to/project
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-wiki-kit",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Hook-first living LLM Wiki runtime for Codex and Claude Code.",
   "type": "module",
   "files": [
@@ -20,6 +20,9 @@
     "doctor": "node bin/llm-wiki.js doctor",
     "status": "node bin/llm-wiki.js status"
   },
+  "dependencies": {
+    "minisearch": "^7.2.0"
+  },
   "engines": {
     "node": ">=20"
   },

package/src/cli.js

@@ -1,4 +1,5 @@
 import { resolve } from 'path';
+import { formatConsolidateResult, runConsolidate } from './consolidate.js';
 import { handleHook } from './hook.js';
 import { install, status, uninstall } from './install.js';
 import { bootstrapProject } from './project.js';
@@ -7,18 +8,28 @@ import { commandForProject, knownProjectRoots } from './projects.js';
 import { formatDoctor, runDoctor } from './doctor.js';
 import { migrate } from './migrate.js';
 import { postUpdate, update } from './update.js';
+import { buildContextPack, formatContextPack } from './wiki-search.js';
+import { formatLintResult, runLint } from './wiki-lint.js';
 
 function parseOptions(args) {
   const options = {};
   const rest = [];
+  const optionValue = (name, index) => {
+    const value = args[index + 1];
+    if (!value || value.startsWith('--')) throw new Error(`${name} requires a value`);
+    return value;
+  };
   for (let i = 0; i < args.length; i += 1) {
     const arg = args[i];
     if (arg === '--workspace' || arg === '--cwd') {
-      options.workspace = args[++i];
+      options.workspace = optionValue(arg, i);
+      i += 1;
     } else if (arg === '--profile') {
-      options.profile = args[++i];
+      options.profile = optionValue(arg, i);
+      i += 1;
     } else if (arg === '--to') {
-      options.to = args[++i];
+      options.to = optionValue(arg, i);
+      i += 1;
     } else if (arg === '--no-codex') {
       options.codex = false;
     } else if (arg === '--no-claude') {
@@ -29,6 +40,16 @@ function parseOptions(args) {
       options.check = true;
     } else if (arg === '--dry-run') {
       options.dryRun = true;
+    } else if (arg === '--limit') {
+      const value = optionValue(arg, i);
+      const limit = Number(value);
+      if (!Number.isInteger(limit) || limit < 1 || limit > 50) {
+        throw new Error('--limit must be an integer from 1 to 50');
+      }
+      options.limit = limit;
+      i += 1;
+    } else if (arg === '--no-expand') {
+      options.expand = false;
     } else if (arg === '--replace-hooks') {
       options.replaceHooks = true;
     } else if (arg === '--all') {
@@ -71,6 +92,9 @@ Usage:
   llm-wiki hook claude <EventName>
   llm-wiki bootstrap --workspace <project>
   llm-wiki migrate --workspace <project>
+  llm-wiki context "<query>" --workspace <project> [--limit 5] [--no-expand]
+  llm-wiki lint --workspace <project>
+  llm-wiki consolidate --workspace <project> [--dry-run]
 `);
     return;
   }
@@ -143,6 +167,27 @@ Usage:
     return;
   }
 
+  if (command === 'context') {
+    const projectRoot = resolve(options.workspace || process.cwd());
+    const query = rest.join(' ').trim();
+    printJsonOrText(await buildContextPack(projectRoot, query, options), options, formatContextPack);
+    return;
+  }
+
+  if (command === 'lint') {
+    const projectRoot = resolve(options.workspace || process.cwd());
+    const result = await runLint(projectRoot, options);
+    printJsonOrText(result, options, formatLintResult);
+    if (!result.ok) process.exitCode = 1;
+    return;
+  }
+
+  if (command === 'consolidate') {
+    const projectRoot = resolve(options.workspace || process.cwd());
+    printJsonOrText(await runConsolidate(projectRoot, options), options, formatConsolidateResult);
+    return;
+  }
+
   if (command === 'hook') {
     const provider = rest[0] || 'codex';
     const eventName = rest[1];
@@ -183,6 +228,8 @@ function formatStatus(value) {
     `- version: ${value.runtimeVersion}`,
     `- runtime: ${value.runtimeVersion} (${value.installSource})`,
     `- bin: ${value.binPath}`,
+    `- command: ${value.commandPath || 'not found'}`,
+    `- command matches runtime: ${value.commandMatchesRuntime ? 'yes' : 'no'}`,
     `- hooks current: ${value.hooksCurrent ? 'yes' : 'no'}`,
     `- codex hook: ${value.codexInstalled ? 'current' : 'missing/outdated'}`,
     `- claude hook: ${value.claudeInstalled ? 'current' : 'missing/outdated'}`,