# llm-wiki-kit

`llm-wiki-kit` is a hook-first living wiki runtime for Claude Code, Codex, and opencode.

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/`.

## Language Behavior

`llm-wiki-kit` is designed for mixed Korean and English teams:

- Korean user prompt -> Korean hook guidance.
- English user prompt -> English hook guidance.
- Codex synthetic plan execution prompts — specifically the exact phrase `Implement the plan.` — are treated as neutral, so they reuse the last real session language or project preference instead of forcing English.
- Project `.kit-state.json` may set `preferredLanguage` to `ko` or `en` for neutral prompts.
- If there is no clear current prompt language, Claude Code `settings.json` `language` is used when present.
- If that setting is missing, local `CLAUDE.md` and `AGENTS.md` language signals are used.
- The fallback is English.
- Commands, paths, code identifiers, package names, logs, and original error text are not translated.

Codex and Claude Code users do not need different commands for Korean or English projects.

## Quick Start

```bash
npm install -g llm-wiki-kit@latest
llm-wiki install --workspace /path/to/project --profile standard
llm-wiki doctor --workspace /path/to/project
```

Restart Claude Code and Codex sessions after installation.

Install also syncs bundled Codex and Claude Code skills named `llm-wiki-*` into `$CODEX_HOME/skills` or `~/.codex/skills`, and into `~/.claude/skills`. Existing same-name user skills are preserved, and kit-managed skills are updated only when they were not locally edited, except obsolete public llm-wiki skills that the kit removes from active provider skill roots. Use `--no-codex` to skip Codex hooks and skills, `--no-claude` to skip Claude hooks and skills, `--no-opencode` to skip the opencode bridge plugin, and `--no-skills` when you want to install hooks without writing either skill root.

### Native Windows

Native Windows is supported through the npm-generated `llm-wiki.cmd` shim. Use PowerShell or Windows Terminal with Node.js 20+:

```powershell
npm install -g llm-wiki-kit@latest
llm-wiki install --workspace C:\path\to\project --profile standard
llm-wiki doctor --workspace C:\path\to\project
```

On Windows, `llm-wiki install` does not create a Unix-style `~/.local/bin` symlink. It verifies the npm shim on `PATH`, installs Codex hooks with `commandWindows`, and writes Claude Code hooks with a Windows-safe `node.exe <bin>` command. Restart Codex and Claude Code after installation.

Use WSL2 instead when your repository and tooling already live in Linux. Native Windows support is for Windows-hosted projects and the native Codex/Claude Code surfaces.

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 smoke tests, build one concrete tarball and use the isolated release verifier. Do not install a prepublish candidate globally or point it at a real workspace:

```bash
candidate_dir="$(mktemp -d)"
npm pack --json --pack-destination "$candidate_dir"
```

First use the isolated Linux home/prefix procedure in `docs/manual.md`. Then transfer that same tarball to a native Windows host and run PowerShell 7 there:

```powershell
pwsh -NoProfile -File C:\work\llm-wiki-kit\scripts\windows-runner\verify-release.ps1 -Mode Tarball -PackageSpec C:\Temp\llm-wiki-kit-<version>.tgz -ExpectedVersion <version>
```

## What Gets Created

Each project gets a local wiki:

```text
llm-wiki/
├── .kit-state.json
├── raw/
├── wiki/
│   ├── index.md
│   ├── memory.md
│   ├── log.md
│   ├── sources/
│   ├── concepts/
│   ├── decisions/
│   ├── architecture/
│   ├── debugging/
│   ├── context/
│   └── queries/
├── outputs/
│   ├── questions/
│   ├── reports/
│   ├── exports/
│   └── maintenance/
├── evals/
└── procedures/
```

`raw/` is the immutable or redacted evidence layer. General source material belongs in `raw/sources/`; older `raw/inbox/`, `raw/assets/`, top-level `llm-wiki/sources/`, top-level `llm-wiki/templates/`, and `wiki/entities/` folders are migrated during maintenance. `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, requested reports, and pending wiki maintenance candidates. `.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 content stays composed (filenames are English ASCII kebab-case per N2).

## Normal Use

Use Claude Code or Codex normally.

The installed hooks:

- inject functional compact context at session start, instructions loaded, and prompt submit. The hook still uses `wiki/memory.md`, `wiki/index.md`, relevant wiki search results, maintenance signals, update status, and any compact recovery packet; it formats only the useful parts so user-visible hook context does not look like a raw debug dump.
- automatically choose Korean or English hook guidance from the current real user prompt, keep Codex synthetic plan execution prompts neutral, then fall back to remembered session language, project `preferredLanguage`, Claude Code `language`, local `CLAUDE.md`/`AGENTS.md`, and English.
- operate only in projects that were explicitly initialized with `llm-wiki bootstrap`, `install`, or `migrate`; routine hooks do not bootstrap arbitrary working directories
- record small redacted raw event envelopes and per-turn state
- capture handoff-focused checkpoints only when a captured user question has explicit durable intent, a structured durable conclusion, or a durable wiki/procedure update
- attach safe `evidence_refs` candidates to generated queue items when changed files or verification commands are available
- before compaction, classify the current turn and save a checkpoint only for explicit durable requests, structured durable conclusions with required evidence, or durable wiki/procedure updates; simple work stays in transient runtime state
- after compaction, keep summaries transient; if pre-compact preservation failed, prepare a recovery packet for the next legal model-visible context hook
- allow tool calls to proceed without secret/PII-based hook blocking
- update chunked `llm-wiki/outputs/questions/YYYY-MM-DD/live-qa-001.md` style archives only for handoff-worthy durable checkpoints
- avoid automatic `wiki/queries/` and `wiki/decisions/` promotion in the default answer-first mode
- queue durable cleanup candidates for explicit documentation requests, structured durable conclusions, or queue-worthy recovered stale turn state that were not reflected in durable wiki/procedure files
- recover stale per-turn state into that queue on the next session start or prompt submit only when the buffered turn is queue-worthy
- nudge the active LLM to batch-review accumulated candidates and fold only explicit, repeated, or clearly reusable facts into existing wiki pages
- report stale managed rules/templates during normal hooks and apply changes only through explicit install/update/post-update/maintenance commands
- provide bundled Codex and Claude Code skills for setup, query, lifecycle, and export workflows without replacing user-created same-name active skills except obsolete public llm-wiki skill entries

Korean and English explicit-durable detection are intentionally **asymmetric**, not parallel. English forms require an object (`remember this`, `record the decision`); Korean action verbs (`추가해`/`정리해`/`남겨둬`/`기억해`/`메모해`/`기록해`) count as explicit durable requests only when a wiki/document/page/memory context token (`위키`/`wiki`/`문서`/`페이지`/`메모리`) accompanies them, so ordinary work requests like `이 기능 추가해줘` stay transient. The Korean documentation noun/verb `문서화`/`문서화해` is self-gating (it carries the documentation context itself) and therefore matches without a separate context token; this is a deliberate divergence from the English `document` verb, which still requires an object. Edge-case forms are not guaranteed to be symmetric across the two languages. Short Korean requests are preserved as long as they contain at least three Hangul syllables.

Only Korean and English are supported. Prompts in other CJK scripts (for example Japanese or Chinese, which contain no Hangul) are treated as English by the fallback chain, with no warning. This is by design, not a bug.

If you need to think about saving every answer manually, the setup has failed.
If wiki maintenance delays the actual answer, the setup is being used wrong. The kit uses the answer-first capture mode: simple answers, status checks, and ordinary tool-heavy work stay out of durable wiki and live Q&A, while explicit durable requests, structured durable conclusions, and detected wiki/procedure updates are archived and queued for batch review.
Pre-compact preservation always lets compaction proceed. `LLM_WIKI_KIT_PRECOMPACT_ENFORCEMENT=off` suppresses failure warnings; `limited` and `soft` both emit a non-blocking warning if checkpoint storage fails. The hook never reads `transcript_path`; checkpoints and recovery packets are built only from bounded, redacted turn state captured by hook events.

## Operational Commands

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 post-update`, `llm-wiki projects`
- Structure & legacy: `llm-wiki bootstrap`, `llm-wiki migrate`, `llm-wiki fork`
- Diagnostics: `llm-wiki doctor`, `llm-wiki status`, `llm-wiki version`
- Manual: `llm-wiki manual`
- Agent maintenance helpers: `llm-wiki search`, `llm-wiki context`, `llm-wiki memory`, `llm-wiki lint`, `llm-wiki consolidate`, `llm-wiki maintenance`, `llm-wiki eval`, `llm-wiki export`
- Live Q&A archive helper: `llm-wiki archive-questions --workspace <project> [--date YYYY-MM-DD] [--dry-run]`
- Page scaffold: `llm-wiki new <slug> --workspace <project> [--type <type>] [--title "<title>"] [--dir <wiki/...>] [--dry-run]` — create a curated page with a complete, lint-clean frontmatter stub (required fields + `keywords` seeded from the title) so no field is missed on creation.
- Internal hook targets: `llm-wiki hook codex|claude|opencode <EventName>`
- Cleanup: `llm-wiki uninstall`

`llm-wiki manual` prints the full package manual from `docs/manual.md`. Keep that document current when adding public commands, options, hook behavior, directory conventions, security policy, or update flows.

`llm-wiki status` is an offline consistency check. It reports the installed runtime version, hook targets, whether the `llm-wiki` command on `PATH` resolves to the current runtime, whether bundled Codex and Claude Code skills are current at each provider root, whether the current workspace has the current managed templates applied, how many rules are auto-updateable, how many managed-looking rules need agent cleanup, and how many wiki maintenance items are pending.

`llm-wiki update --check [--to <version-or-tag>]` is the online update check. It compares the installed package version with the npm registry target without changing files, and reports an available update only when the target version is newer than the installed version.

`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. Before installing, it checks whether `npm root -g` points at the active runtime package root; after installing, it verifies the active runtime and `post-update` runtime reached the registry target. If either check fails, it exits nonzero and prints the exact runtime/npm roots plus the manual install/post-update commands to run. If `npm install -g` fails with `EACCES` or another permission error, update preserves npm's original error and explains that only the package install should use privilege escalation, followed by `post-update` or `update` as the normal Codex/Claude user. If the installed runtime already satisfies the registry target, it prints an already-current result, skips only `npm install -g`, and still runs post-update maintenance. The text output separates `npm install: skipped (runtime already current)` from `post-update: ran`, then reports how many projects were processed and how many managed templates changed, skipped, or stayed unchanged. It also prints `project details` lines that show each processed directory plus changed paths, skipped `path:reason` entries, and unchanged counts. Use `--current-only` when you intentionally want to update only the supplied workspace. Existing wiki content is not overwritten. The command prints step progress to stderr, including registry lookup, npm root/prefix checks, npm install, post-update, and project discovery. Use `--timeout-ms <ms>` to bound external commands and `--max-dirs <n>` to bound project discovery under large or slow roots such as WSL `/mnt/*` trees.

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, Codex and Claude receive the same passive runtime update status in hook context: current runtime, npm registry target, and the manual command to use when the user asks for update or maintenance work. It is not an instruction to interrupt the current answer or to sell the update to the user. The cache is scoped to the npm command used for lookup so test/fake npm checks do not leak into normal hook sessions. Set `LLM_WIKI_KIT_UPDATE_NOTICE=0` only when diagnosing or suppressing that status block.

`llm-wiki post-update --workspace <project>` reapplies the current runtime's hook entries, bundled Codex and Claude Code skills, and safe managed template updates without running `npm install -g`. Use `post-update --all --workspace <search-root>` to reapply templates across discovered project roots. Add `--no-codex` to skip Codex hooks and skills, `--no-claude` to skip Claude hooks and skills, or `--no-skills` to inspect/update hooks/templates without writing either skill root.

`llm-wiki search "<query>"` is the agent-facing search surface. Hits carry a `wiki/path.md#section` ref plus a file-accurate `L<start>-L<end>` line range, so agents read just the matched section with their native Read tool instead of whole pages. Single short body-only matches are dropped as retrieval noise (rollback: `LLM_WIKI_KIT_SEARCH_FILTER=0`; inspect with `--show-filtered`), and a no-match exits 0 with an explicit outcome line — retry once with the suggested vocabulary (copy-pasteable command included), then state that the wiki has no record and answer normally. `--json` emits a versioned redacted schema; `--all-projects` searches sibling project wikis.

`llm-wiki context "<query>"` prints the full debug view of the layered context sources used by hooks. Hook injection may render those sources as functional compact context for Codex and Claude, but this CLI stays verbose so maintainers can inspect retrieval, section refs, snippets, memory, index, expansion behavior, context budget metadata, `rankReason`, `matchedFields`, `scoreBreakdown`, `confidenceLevel`, `confidenceReasons`, `visibilityReason`, and `evidenceRefs`. Wiki pages are indexed by Markdown section, and standard metadata plus scalar values under `extensions` are searchable; extension matches have a deliberately small boost. Results remain page-compatible by keeping the best section hit per page. The text formatter adds a short `why selected` line for each hit; hook compact context deliberately omits that extra detail and uses short `wiki/path.md#section` refs. Use `--budget-chars <n>` for reviewable context packs, `--compact --max-context-chars <n>` to preview hook-sized output, and `--show-hidden-reason` to inspect pages excluded by visibility policy. Daily use should rely on hook injection. By default, pages with `memory_type: episodic` and episodic query/context/session roles are excluded unless promoted with durable metadata; use `--include-episodic` only when debugging old automatic records. Archived or superseded pages are hidden unless `--include-archived` is requested, while stale pages remain searchable with lower score.

Bundled Codex and Claude Code skills:

- `llm-wiki-setup`
- `llm-wiki-query`
- `llm-wiki-lifecycle`
- `llm-wiki-export`
- `llm-wiki-keywords`

The high-frequency skills are intended to trigger from ordinary user language, not only explicit commands. Read-only memory questions should route to `llm-wiki-query`. Durable "remember/document/save/report this" requests, cleanup, queue review, archive, consolidate, lint/eval hygiene, and stale policy/document follow-through should route to `llm-wiki-lifecycle`. Lifecycle evaluates internal `document`, `maintain`, and `upgrade-docs` mode flags independently: durable persistence defaults to `document + maintain`, while `upgrade-docs` runs only on clear update, migration, lint, or old-policy signals.

`llm-wiki memory [query]` is the review surface for the active wiki. It reports current `memory.md` focus bullets, durable entry points, active workspace/wiki root, optional retrieval hits for a query, maintenance queue state, and lint/eval health. It is read-only; queue changes still go through `llm-wiki maintenance`.

`llm-wiki lint` checks wiki health and detects outdated managed rules from older kit versions. Curated pages are expected to carry `title`, `type`, `status`, `memory_type`, and `last_updated`; a missing required field is reported as a warning (and auto-filled on changed durable pages during maintenance), while an invalid value (for example an unknown `type` or `status`) is an error. Optional standard fields have runtime defaults, while project-specific metadata belongs under typed `extensions` with lowercase snake_case keys. It validates optional `evidence_refs` entries with the prefixes `file:`, `cmd:`, `raw:`, and `url:`. It also warns when `memory.md`, `index.md`, or `log.md` approaches its budget, a hand-authored `memory.md` current-focus bullet exceeds the density guidance (`memory-focus-bullet-density`), `importance: 5` is saturated, wiki page count reaches the growth review threshold, hidden episodic pages accumulate, or stale/archived pages lack discoverability. This threshold is a health signal, not a search truncation limit. Semantic content edits should revise `last_updated` and any verification/evidence metadata whose meaning changed; formatting-only normalization is not verification. Lint does not enforce the `last_updated` revision mechanically (there is no baseline diff); it is agent guidance surfaced as a health signal. For a single page after authoring, `llm-wiki lint <file> --workspace <project> --fail-on-warning --suppress-auto-fixable` is an on-demand spot-check (page-local rules plus link resolution; `--fail-on-warning` fails on warnings too; `--suppress-auto-fixable` hides frontmatter issues the next Stop hook auto-normalizes); it is no longer required after every write. By default the lint gate is **batched**: the kit counts durable `wiki/**` and `procedures/**` page changes since the last corpus lint and prompts you after N changes (default 10, configurable via `lintBatchThreshold` in `.kit-state.json`); run `llm-wiki lint --workspace <project>` when prompted or before reporting a documentation task complete, and a corpus lint resets the counter. Per-path lint exceptions live in `llm-wiki/.kit/lint-exceptions.json` (absent = none): each entry suppresses one lint code on a `paths` glob with a required `reason` and optional `expires`; secret-detection codes (`secret-like-content` family) demote to `warning` instead of silencing (also under global `lintSeverity: off`), corpus-integrity codes cannot be excepted, and `llm-wiki lint --show-suppressed` re-shows dropped issues.

`llm-wiki consolidate` refreshes only generated marker blocks in `wiki/memory.md`, `wiki/index.md`, and `wiki/queries/archive-index.md`. It balances the memory map across page types, caps generated memory at 12 entries/8KB, caps the index at 80 entries/8 per type/24KB, and caps the archive-index at 16KB; it reports shown and omitted counts. The generated `archive-index.md` is an episodic page that collects archived/superseded wiki pages plus outputs archives (live Q&A, reviewed maintenance) so they stay findable after archival — search it with `llm-wiki context "<query>" --include-episodic`. Lint warns at 12KB for `memory.md`, 24KB for `index.md`/`log.md`, and surfaces 16KB / 32KB as upper health thresholds (and flags `memory-focus-bullet-density` when a hand-authored current-focus bullet exceeds 400 chars); these are warning-level health signals that feed maintenance review, not lint-failing errors (structural problems like broken links, invalid enum values, secret-like content, and YAML errors are the lint errors). Generated maps keep durable non-archived pages and skip episodic/stale/archived/superseded pages. It is an agent maintenance helper, not a command users should run after every turn.

`llm-wiki maintenance --workspace <project> --normalize-frontmatter --dry-run` previews explicit YAML normalization. Applying it merges legacy `source_id` into `source_ids`, fills inferable required core fields, removes redundant defaults, and moves unknown top-level fields under `extensions`; ambiguous collisions and invalid extension keys are left untouched for review. Hooks never run this normalization automatically.

`llm-wiki maintenance --workspace <project> --derive-tags [--dry-run]` backfills Obsidian-style tags (`type/<type>`, `memory/<memory_type>`, `status/<status>`) from existing metadata. Preview with `--dry-run` first. Hooks never run this automatically.

`llm-wiki maintenance --workspace <project> --normalize-filenames` previews renaming curated pages to the naming policy (lowercase ASCII kebab-case, length and shape rules, title↔filename alignment); `--apply` performs the rename, appends the prior stem as an alias so existing wikilinks keep resolving, and rewrites internal wikilinks. Conflicting target names are skipped for review. Hooks never run this normalization automatically.

`llm-wiki maintenance` prints the queue and review due status from `llm-wiki/outputs/maintenance/queue.md`. Queue states are `pending -> approved -> done` or `skipped`. Use `llm-wiki maintenance --workspace <project> --approve <id> --target <wiki/...md>` only when a human/agent explicitly accepts durable promotion, `--done <id> --target <wiki/...md>` after the active agent has merged the fact into a durable page, and `--skip <id> [--note "..."]` for duplicate or non-durable candidates. `llm-wiki maintenance --workspace <project> --apply-lifecycle --dry-run` previews queue hygiene and deprecated layout cleanup; without `--dry-run`, candidates remain pending for batch review, old low-signal candidates may be skipped, old reviewed items move to `outputs/maintenance/archive/`, and known deprecated folders are migrated (`raw/inbox/` to `raw/sources/`, `raw/assets/` to `raw/sources/assets/`, `wiki/entities/` to `wiki/concepts/`, top-level `sources/` to `wiki/sources/`, and top-level `templates/` to `wiki/context/`) before empty deprecated directories are removed. Legacy daily live Q&A files are preserved under `outputs/questions/archive/originals/` and converted to chunked `outputs/questions/YYYY-MM-DD/live-qa-001.md` files. The lifecycle never deletes user content to force conformity: duplicate content is deduplicated only when bytes match, conflicts get `*-migrated-<timestamp>` names, and unknown directories are left for lint/agent review. Routine hooks never apply this mutating lifecycle; they only surface compact reminders. Approved items are shown before pending items in hook reminders.

`llm-wiki eval --workspace <project> [--fixture <path>] [--limit 5] [--json]` runs retrieval fixtures from `llm-wiki/evals/retrieval.json` by default. A missing or empty fixture is a failing evaluation and exits nonzero. Fixtures list `query`, `expected`, and `unexpected` paths; output reports recall, MRR, stale-hit rate, citation coverage, missed expected hits, unexpected hits, hidden unexpected hits, and top hits using the same durable visibility policy as export.

`llm-wiki export --workspace <project> [--format all|llms|llms-full|json] [--output <dir>] [--dry-run] [--json]` writes durable wiki manifests under `llm-wiki/outputs/exports/` by default. `llms.txt` is an agent onboarding and handoff manifest, not a passive SEO artifact. `llms-full.txt` is a redacted durable context bundle for compaction recovery or handoff. `llm-wiki.json` is a structured manifest for future adapters and eval tooling. Export uses the same durable visibility policy as search/eval and redacts credentials before writing.

`llm-wiki fork --from <source-workspace> --to <target-workspace>` copies durable wiki pages from one workspace to another and stamps each with a `forked_from: { workspace, path, hash, copied_at }` frontmatter block. Lint warns when a forked page drifts from its recorded hash so sibling workspaces can detect translation edits, status changes, or evidence refresh without manual comparison.

Every public and internal command is registered in `src/command-lifecycle.js` with its intended lifecycle role. Hooks do not shell out to CLI commands; they share internal modules with the CLI. `status`, `doctor`, and tests expose registry drift so commands are not added without hook policy, docs, and tests.

`llm-wiki archive-questions` splits older legacy `llm-wiki/outputs/questions/YYYY-MM-DD-live-qa.md` files into the chunked `llm-wiki/outputs/questions/YYYY-MM-DD/` layout. It preserves the original under `outputs/questions/archive/originals/` with a SHA-256 sidecar and replaces the legacy file with a short pointer stub. Use `--dry-run` first when reviewing a large archive. This is a narrow subset of `maintenance --apply-lifecycle` (which already archives legacy live Q&A); use the standalone command when you want to split Q&A files without touching the maintenance queue or layout.

`llm-wiki projects --workspace /path/to/search-root` lists project roots that already have `llm-wiki-kit` state or an older `llm-wiki/wiki/index.md`, and shows the update commands to run. `llm-wiki update --workspace /path/to/search-root` updates the global runtime once, then reapplies managed templates across every known or discovered project root under that search root. In update output, `projects processed` means the project roots were inspected by post-update; template changes are reported separately, and `project details` identifies which directory changed, skipped, or stayed unchanged.

For `llm-wiki-kit` code releases, source tests are not enough. Build one candidate tarball and verify it in isolated Linux and native Windows environments before commit/publish; after push, rebuild from the exact clean SHA and repeat those gates. Publish only that verified artifact with explicit external authority, then verify registry integrity and actual installed CLI, hooks, provider skill roots, templates, `version`, `status`, `doctor`, `update`, `lint`, and eval/memory health before calling the release complete. Use npm tokens only through protected environment variables; do not write them to repository `.npmrc`, wiki files, logs, generated exports, or commits.

Native Windows changes require a real Windows prepublish smoke against the exact candidate tarball, followed by a post-publish registry-install smoke. Run the packaged Windows tests, filesystem contention/replace checks, isolated install, `status`, `doctor`, lint/eval/memory health, and hook/skill/template checks. Simulated unit tests are not enough for the Windows support claim.

For long Windows verification runs, use the packaged file-queue runner in `scripts/windows-runner/` instead of keeping a foreground WinRM command open. Install `install-scheduled-task.ps1` once on the Windows host; by default it creates an on-demand hidden task with no repeating trigger. Submit JSON jobs into `C:\llm-wiki-runner\queue\`, run `Start-ScheduledTask -TaskName LlmWikiWindowsRunner`, and poll `logs\<job>.status.json`, `stdout.log`, and `stderr.log`. Prefer SSH/scp for normal submission, task triggering, and status polling. Keep WinRM only as a bootstrap or emergency recovery fallback.

After a plain `npm install -g llm-wiki-kit@latest`, existing hooks keep working when they already point at the global npm package path. Routine `SessionStart`/`InstructionsLoaded` hooks inspect and report stale managed templates but do not rewrite them. Run `llm-wiki post-update --workspace <project>` or `llm-wiki install --workspace <project>` explicitly to refresh generated templates and reconnect stale hooks; user-edited files remain protected.

On Linux/macOS, `llm-wiki install` creates or keeps a current user-local `~/.local/bin/llm-wiki` shim even when an npm/nvm global `llm-wiki` command already resolves to the current runtime. This keeps Claude/Codex non-login Bash environments working when their PATH includes `~/.local/bin` but not an nvm/npm global bin directory. If an unmanaged local command already exists, install leaves it alone when another current runtime command is available. On Windows, the npm-generated `llm-wiki.cmd` shim is the supported command entrypoint and no local symlink is created.

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, run install once so the kit can replace a managed stale shim or report an unmanaged one:

```bash
llm-wiki install --workspace /path/to/project --profile standard
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:

```bash
llm-wiki hook codex SessionStart
llm-wiki hook claude Stop
```

## Security Defaults

- Full raw transcript capture is disabled by default. An opt-in redacted full Q&A audit log (`LLM_WIKI_KIT_FULL_QA=1`) records every turn's redacted prompt/assistant/tool bodies under `raw/qa/` (local-only, gitignored); see `docs/integrations/opencode.md` and decision `2026-08-07-full-qa-capture-channel.md`.
- PreCompact never reads the transcript file referenced by `transcript_path`; it builds checkpoints only from bounded hook-captured turn state.
- Tool calls are not blocked only because inputs look sensitive.
- Authentication values such as tokens, passwords, private keys, Basic auth, URL user information, `curl -u`, and password-bearing CLI/database flags are redacted before durable summaries are written.
- Transient turn, compact, language, continuity, and recovery state requires a stable provider session/conversation identifier and fails closed without one; there is no shared `default` session artifact. `LLM_WIKI_KIT_PROJECT_SCOPED_TRANSIENT=1` is an opt-in for providers that emit no session id: it derives a per-project key so transient features degrade gracefully instead of failing closed. It is off by default and never shares state across projects.
- Generated exports are redacted and must not contain npm tokens, WinRM credentials, private keys, raw `.env`, or full raw transcripts.
- Hook payloads are stored only as append-only, schema-bounded redacted event envelopes without cwd, transcript path, prompt/tool body, or provider session ID.
- Phone numbers, emails, dates, and business identifiers are preserved by default so the wiki remains useful for local work.

## Development Notes

Source checkout installs are supported for development:

```bash
git clone <your-git-url>/llm-wiki-kit.git /path/to/llm-wiki-kit
cd /path/to/llm-wiki-kit
npm install
./install.sh --workspace /path/to/project --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`