llm-wiki-kit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,132 @@
+# llm-wiki-kit
+
+`llm-wiki-kit` is a hook-first living wiki runtime for Claude Code and Codex.
+
+The goal is not to make users run `ingest` or `record` commands. After install, normal Claude Code/Codex work should naturally become a project-local Markdown wiki under `llm-wiki/`.
+
+## Quick Start
+
+After the package is published to npm:
+
+```bash
+npm install -g llm-wiki-kit
+llm-wiki install --workspace /apps --profile standard
+llm-wiki doctor
+```
+
+Restart Claude Code and Codex sessions after installation.
+
+The default install mode is npm global install. On servers where the global npm prefix is root-owned, use sudo:
+
+```bash
+sudo npm install -g llm-wiki-kit
+```
+
+If sudo is not available, use a user-local npm prefix as a fallback:
+
+```bash
+npm config set prefix "$HOME/.local"
+npm install -g llm-wiki-kit
+```
+
+For development or pre-publish server smoke tests, install from a local tarball instead:
+
+```bash
+npm pack --pack-destination /tmp
+npm install -g /tmp/llm-wiki-kit-<version>.tgz
+llm-wiki install --workspace /apps --profile standard
+```
+
+## What Gets Created
+
+Each project gets a local wiki:
+
+```text
+llm-wiki/
+├── .kit-state.json
+├── raw/
+├── wiki/
+│   ├── index.md
+│   ├── log.md
+│   ├── sources/
+│   ├── concepts/
+│   ├── entities/
+│   ├── decisions/
+│   ├── architecture/
+│   ├── debugging/
+│   ├── context/
+│   └── queries/
+├── outputs/
+└── 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.
+
+## Normal Use
+
+Use Claude Code or Codex normally.
+
+The installed hooks:
+
+- inject relevant wiki context at session start and prompt submit time
+- record redacted turn summaries
+- capture decision points, debugging findings, changed files, and verification notes
+- update `llm-wiki/outputs/questions/YYYY-MM-DD-live-qa.md`
+- promote useful answers into `llm-wiki/wiki/queries/`
+- promote decision-like turns into `llm-wiki/wiki/decisions/`
+
+If you need to think about saving every answer manually, the setup has failed.
+
+## User-Facing Commands
+
+```bash
+llm-wiki install --workspace /path/to/project --profile standard
+llm-wiki doctor
+llm-wiki status --workspace /path/to/project
+llm-wiki update --check --workspace /path/to/project
+llm-wiki update --dry-run --workspace /path/to/project
+llm-wiki update --workspace /path/to/project
+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.
+
+`llm-wiki update --check` is the online update check. It compares the installed package version with the npm registry without changing files.
+
+`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.
+
+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:
+
+```bash
+llm-wiki hook codex SessionStart
+llm-wiki hook claude Stop
+```
+
+## Security Defaults
+
+- Full raw transcript capture is disabled by default.
+- `.env`, tokens, private keys, credentials, `raw_private/`, and `secrets/` are blocked or redacted.
+- Hook payloads are stored only as redacted event envelopes.
+- Store customer or personal data only after explicit sanitization.
+
+## Development Notes
+
+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
+./install.sh --workspace /apps --profile standard
+node --test
+```
+
+`llm-wiki update` intentionally refuses to self-update from a source checkout. Install the npm package or a tarball first when testing update behavior.
+
+## Design Sources
+
+- Kochim LLM Wiki implementation guide: `https://kochim.com/boards/posts/1779116400000_llm-wiki-implementation-guide-2026/`
+- Local research baseline: `docs/research/baseline.md`
+- Codex hooks and `AGENTS.md`
+- Claude Code hooks and `CLAUDE.md`

package/bin/llm-wiki.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { runCli } from '../src/cli.js';
+
+runCli(process.argv.slice(2)).catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+});

package/docs/concepts.md

@@ -0,0 +1,29 @@
+# Concepts
+
+`llm-wiki-kit` follows the LLM Wiki pattern:
+
+```text
+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.
+- `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.
+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.
+
+The kit is a template/runtime repository. It must not centralize project wiki contents.
+
+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.
+- curated wiki pages remain project-owned content and are not overwritten by runtime updates.

package/docs/integrations/claude-code.md

@@ -0,0 +1,48 @@
+# Claude Code Integration
+
+`llm-wiki-kit` installs command hooks into `~/.claude/settings.json`.
+
+The command target is:
+
+```bash
+llm-wiki hook claude <EventName>
+```
+
+The installed hook stores the Node executable and the absolute package binary path. A system-wide npm install usually points at:
+
+```bash
+/usr/lib/node_modules/llm-wiki-kit/bin/llm-wiki.js
+```
+
+User-local fallback installs may instead point under `$HOME/.local/lib/node_modules`.
+
+Handled events:
+
+- `SessionStart`
+- `InstructionsLoaded`
+- `UserPromptSubmit`
+- `PreToolUse`
+- `PostToolUse`
+- `PostToolBatch`
+- `PreCompact`
+- `PostCompact`
+- `SubagentStop`
+- `Stop`
+- `SessionEnd`
+
+Claude Code reads `CLAUDE.md`. For project compatibility, the kit creates a `CLAUDE.md` stub containing:
+
+```text
+@AGENTS.md
+```
+
+when no project `CLAUDE.md` exists. Existing `CLAUDE.md` files are not overwritten.
+
+After installation or update, run:
+
+```bash
+llm-wiki status --workspace /path/to/project
+llm-wiki doctor
+```
+
+Restart Claude Code so it reloads hook settings.

package/docs/integrations/codex.md

@@ -0,0 +1,45 @@
+# Codex Integration
+
+`llm-wiki-kit` installs command hooks into the Codex hook configuration, usually `~/.codex/hooks.json`.
+
+The command target is:
+
+```bash
+llm-wiki hook codex <EventName>
+```
+
+The installed hook stores the Node executable and the absolute package binary path. A system-wide npm install usually points at:
+
+```bash
+/usr/lib/node_modules/llm-wiki-kit/bin/llm-wiki.js
+```
+
+User-local fallback installs may instead point under `$HOME/.local/lib/node_modules`.
+
+Handled events:
+
+- `SessionStart`
+- `UserPromptSubmit`
+- `PreToolUse`
+- `PostToolUse`
+- `PreCompact`
+- `PostCompact`
+- `SubagentStop`
+- `Stop`
+
+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.
+- `PreToolUse` blocks secret-looking paths or payloads.
+- `PostToolUse` records redacted tool summaries in a turn buffer.
+- `Stop` writes live Q&A and durable wiki pages.
+
+Run these after install:
+
+```bash
+llm-wiki status --workspace /path/to/project
+llm-wiki doctor
+```
+
+If Codex reports untrusted hooks, trust the hook through Codex's own trust flow or run a trusted automation profile that explicitly accepts the hook source. Restart Codex after hook installation or update.

package/docs/operations.md

@@ -0,0 +1,137 @@
+# Operations
+
+## Profiles
+
+`standard` is the default:
+
+- inject context
+- record redacted summaries
+- block secret-looking tool access
+- write live Q&A and wiki pages
+
+`strict` is reserved for future stronger enforcement:
+
+- fail closed when hooks are disabled
+- require successful stop/session-end recording
+- block raw/wiki boundary violations more aggressively
+
+## Install
+
+Published npm package:
+
+```bash
+npm install -g llm-wiki-kit
+llm-wiki install --workspace /apps --profile standard
+```
+
+The default install mode is npm global install. On servers where the global npm prefix is root-owned, use sudo:
+
+```bash
+sudo npm install -g llm-wiki-kit
+```
+
+If sudo is not available, configure a user-local prefix as a fallback:
+
+```bash
+npm config set prefix "$HOME/.local"
+npm install -g llm-wiki-kit
+```
+
+Avoid mixing root-owned and user-local installs unless you intentionally choose which `llm-wiki` appears first on `PATH`.
+
+The installer:
+
+- creates `~/.local/bin/llm-wiki`
+- backs up existing Codex/Claude settings before editing
+- merges hook entries without removing existing hooks
+- bootstraps the workspace `llm-wiki/`
+- records managed template state in `llm-wiki/.kit-state.json`
+
+Source checkout installs are still useful for development:
+
+```bash
+./install.sh --workspace /apps --profile standard
+```
+
+Pre-publish server smoke tests can use a local tarball:
+
+```bash
+npm pack --pack-destination /tmp
+npm install -g /tmp/llm-wiki-kit-<version>.tgz
+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
+
+```bash
+llm-wiki status --workspace /path/to/project
+llm-wiki update --check --workspace /path/to/project
+llm-wiki update --dry-run --workspace /path/to/project
+llm-wiki update --workspace /path/to/project
+```
+
+`status` is offline and answers whether the local installation is internally consistent:
+
+- runtime version and install source
+- Codex/Claude hook entries pointing at the current runtime
+- project template state from `llm-wiki/.kit-state.json`
+- current managed file hashes
+
+`update --check` is online and asks npm whether a newer package version exists.
+
+`update` applies changes explicitly only when the user runs it:
+
+- runs `npm install -g llm-wiki-kit@<target>`
+- restarts into the updated binary for `post-update`
+- reinstalls hook entries without duplicating them
+- patches only managed project files
+- backs up changed files under `~/.local/share/llm-wiki-kit/backups/`
+
+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
+
+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.
+
+## Release Checklist
+
+Before publishing:
+
+```bash
+node --test
+npm pack --dry-run
+```
+
+Check that the tarball includes `bin/`, `src/`, `docs/`, `examples/`, `README.md`, `LICENSE`, `install.sh`, and `package.json`, but does not include project-local `llm-wiki/` contents.
+
+After publishing:
+
+```bash
+npm view llm-wiki-kit version
+npm install -g llm-wiki-kit
+llm-wiki install --workspace /apps --profile standard
+llm-wiki status --workspace /apps
+llm-wiki doctor
+llm-wiki update --check --workspace /apps
+```
+
+## Uninstall
+
+```bash
+llm-wiki uninstall
+```
+
+Only hook entries pointing at this kit are removed. Project wiki contents are left intact.
+
+## Migration
+
+```bash
+llm-wiki migrate --workspace /path/to/project
+```
+
+Migration is copy-only. Existing `omx_wiki/*.md` files are copied into `llm-wiki/wiki/context/`; originals are preserved.

package/docs/research/baseline.md

@@ -0,0 +1,18 @@
+# Research Baseline
+
+The implementation baseline is:
+
+- Kochim LLM Wiki implementation guide: `https://kochim.com/boards/posts/1779116400000_llm-wiki-implementation-guide-2026/`
+- `/apps/deep-research-report.md`
+
+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.
+- `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.
+

package/docs/security.md

@@ -0,0 +1,27 @@
+# Security
+
+The default policy is conservative.
+
+Do not store:
+
+- credentials
+- tokens
+- private keys
+- `.env` contents
+- customer identifiers
+- personal data
+- contracts, invoices, or financial details
+- private raw transcripts unless the project explicitly opts in
+
+The runtime redacts common secret patterns and blocks secret-looking tool paths such as:
+
+- `.env`
+- `*.pem`
+- `*.key`
+- `id_rsa`
+- `secrets/`
+- `credentials/`
+- `raw_private/`
+
+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

@@ -0,0 +1,101 @@
+# Troubleshooting
+
+## Hooks Do Not Run
+
+Run:
+
+```bash
+llm-wiki doctor
+llm-wiki status
+```
+
+Then restart Claude Code or Codex.
+
+## Is An Update Available?
+
+Use the offline check first:
+
+```bash
+llm-wiki status --workspace /path/to/project
+```
+
+If the runtime and project state are consistent but you want to know whether npm has a newer release:
+
+```bash
+llm-wiki update --check --workspace /path/to/project
+```
+
+`status` does not contact the network. `update --check` contacts npm but does not change files.
+
+## npm Says The Package Is Not Found
+
+If `llm-wiki update --check` returns npm 404, the package is not published to the registry being used. Until publish, test npm installation with a local tarball:
+
+```bash
+npm pack --pack-destination /tmp
+npm install -g /tmp/llm-wiki-kit-<version>.tgz
+llm-wiki install --workspace /path/to/project --profile standard
+```
+
+Real registry-based update checks will work only after `npm view llm-wiki-kit version` succeeds.
+
+## 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:
+
+```bash
+sudo npm install -g llm-wiki-kit
+```
+
+If sudo is not available, set a user-local prefix:
+
+```bash
+npm config set prefix "$HOME/.local"
+npm install -g llm-wiki-kit
+```
+
+Make sure `$HOME/.local/bin` is on `PATH`, then confirm:
+
+```bash
+command -v llm-wiki
+llm-wiki status --workspace /path/to/project
+```
+
+Avoid mixing root-owned and user-local installs unless you intentionally choose which `llm-wiki` appears first on `PATH`.
+
+## Update Fails From A Source Checkout
+
+`llm-wiki update` is designed for global npm installs. If the command says it cannot self-update from a source checkout, install the package first:
+
+```bash
+npm install -g llm-wiki-kit
+llm-wiki update --workspace /path/to/project
+```
+
+For pre-publish testing, use `npm pack` and install the generated tarball globally.
+
+## Codex Says The Hook Is Untrusted
+
+Use Codex's hook trust flow or run in a trusted automation profile. `llm-wiki-kit` does not silently bypass Codex trust.
+
+## Claude Code Does Not Load Context
+
+Check:
+
+- `~/.claude/settings.json` contains a hook command pointing at the installed `llm-wiki-kit/bin/llm-wiki.js`
+- project `CLAUDE.md` exists or imports `@AGENTS.md`
+- the session was restarted after install
+
+## A Secret Was Detected
+
+The hook blocks or redacts secret-like content. Move sensitive material out of the project wiki path and use sanitized source notes.
+
+## Duplicate Pages Appear
+
+Run a manual review:
+
+```bash
+rg -n "title:|aliases:|source_ids:" llm-wiki/wiki
+```
+
+Prefer merging duplicates into existing pages and preserving contradictions in an `Open Questions` section.

package/examples/hook-fixtures/stop.json

@@ -0,0 +1,6 @@
+{
+  "hook_event_name": "Stop",
+  "cwd": "/tmp/llm-wiki-kit-fixture",
+  "session_id": "fixture-session",
+  "last_assistant_message": "Decision: use a plain Markdown living wiki with hook-based capture and redaction."
+}

package/examples/hook-fixtures/user-prompt-submit.json

@@ -0,0 +1,7 @@
+{
+  "hook_event_name": "UserPromptSubmit",
+  "cwd": "/tmp/llm-wiki-kit-fixture",
+  "session_id": "fixture-session",
+  "prompt": "Explain the current architecture decision and remember useful context."
+}
+

package/examples/minimal-project/AGENTS.md

@@ -0,0 +1,10 @@
+# Minimal Project Instructions
+
+This project uses `llm-wiki-kit`.
+
+- Start from `llm-wiki/wiki/index.md`.
+- Keep raw source material immutable.
+- Update existing wiki pages before creating duplicates.
+- Store useful answers in `llm-wiki/wiki/queries/`.
+- Do not store secrets or private data.
+

package/install.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+node "$SCRIPT_DIR/bin/llm-wiki.js" install "$@"

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "llm-wiki-kit",
+  "version": "0.1.0",
+  "description": "Hook-first living LLM Wiki runtime for Codex and Claude Code.",
+  "type": "module",
+  "files": [
+    "bin/",
+    "src/",
+    "docs/",
+    "examples/",
+    "README.md",
+    "LICENSE",
+    "install.sh"
+  ],
+  "bin": {
+    "llm-wiki": "bin/llm-wiki.js"
+  },
+  "scripts": {
+    "test": "node --test",
+    "doctor": "node bin/llm-wiki.js doctor",
+    "status": "node bin/llm-wiki.js status"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT"
+}