# Troubleshooting

## Hooks Do Not Run

Run:

```bash
llm-wiki doctor --workspace /path/to/project
llm-wiki status --workspace /path/to/project
```

Then restart Claude Code or Codex.

`doctor` and `status` report whether hooks point at the current runtime, whether the `llm-wiki` command on `PATH` resolves to that runtime, and whether project managed templates are current. If hooks or shims point at a source checkout or stale path, run one of these once:

```bash
llm-wiki post-update --workspace /path/to/project
llm-wiki install --workspace /path/to/project --profile standard
```

Routine hooks do not refresh templates. Use `post-update` or `install` explicitly after reviewing the reported drift.

## 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.

## Unexpected Live Q&A Or Maintenance Items

The default `answer-first` policy creates handoff-focused checkpoints only for captured user questions with explicit durable intent, structured durable conclusions, or durable wiki/procedure updates. Ordinary tool-heavy work, verification-only summaries, status checks, and keyword-only turns should not create `outputs/questions/` chunks or maintenance queue items.

If generic work is still being archived, check for an old runtime or deprecated eager mode:

```bash
llm-wiki version
llm-wiki status --workspace /path/to/project
```

The kit uses the answer-first capture mode: hooks only archive handoff-worthy durable checkpoints and queue structured durable conclusions for batch review. Simple answers, status checks, and ordinary tool-heavy work are not promoted.

## llm-wiki update Appears To Hang

`update` runs `npm view`, optional `npm install -g`, project discovery, and `post-update`. It prints progress to stderr while keeping JSON output on stdout parseable. In slow WSL or Windows-mounted trees, start with a bounded dry run:

```bash
llm-wiki update --dry-run --workspace /path/to/project --current-only --timeout-ms 30000
llm-wiki update --dry-run --workspace /path/to/search-root --max-dirs 1000 --timeout-ms 30000
```

If the current project succeeds but the search root is slow, use `--current-only` for that project or raise `--max-dirs` intentionally. If npm itself is slow, compare with:

```bash
npm view llm-wiki-kit version --registry=https://registry.npmjs.org/
```

When a child command exceeds `--timeout-ms`, `update` terminates it and then force-kills it after a short grace period.

## Claude Code Settings Error: Invalid Hook Key

Some Claude Code versions reject newer hook event keys such as `PostToolBatch`. Run:

```bash
claude --version
llm-wiki install --workspace /path/to/project --profile standard
llm-wiki doctor --workspace /path/to/project
```

The installer detects the local Claude version, installs only compatible hook events, and removes kit-managed hooks for unsupported event keys. User-defined hooks are preserved when possible.

## 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
candidate_dir="$(mktemp -d)"
smoke_root="$(mktemp -d)"
npm pack --json --pack-destination "$candidate_dir"
HOME="$smoke_root/home" NPM_CONFIG_CACHE="$smoke_root/npm-cache" NPM_CONFIG_USERCONFIG="$smoke_root/isolated.npmrc" npm install --prefix "$smoke_root/prefix" --ignore-scripts "$candidate_dir/llm-wiki-kit-<version>.tgz"
HOME="$smoke_root/home" XDG_DATA_HOME="$smoke_root/data" CODEX_HOME="$smoke_root/codex" node "$smoke_root/prefix/node_modules/llm-wiki-kit/bin/llm-wiki.js" install --workspace "$smoke_root/project" --profile standard --json
```

Real registry-based update checks will work only after `npm view llm-wiki-kit version` succeeds.

## npm install -g Fails With ECONNRESET

`ECONNRESET` means npm reached the network path but the connection was reset while reading from the registry. This is usually a proxy, firewall, TLS inspection, DNS, or WSL/network issue on the installing server. It is different from `E404`, which means the package or registry entry was not found.

First confirm the registry and package from the same shell:

```bash
npm view llm-wiki-kit version --registry=https://registry.npmjs.org/
curl -Iv https://registry.npmjs.org/llm-wiki-kit
```

When installing with `sudo`, check root's npm config too because it may not match the current user's config:

```bash
npm config get registry
sudo npm config get registry
sudo npm config get proxy
sudo npm config get https-proxy
sudo npm ping --registry=https://registry.npmjs.org/
```

If the server is behind an HTTP proxy, configure it for root npm:

```bash
sudo npm config set proxy http://proxy-host:proxy-port
sudo npm config set https-proxy http://proxy-host:proxy-port
sudo npm config set registry https://registry.npmjs.org/
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.

Newer `llm-wiki update` releases diagnose this before claiming success. If the npm global root does not match the active runtime root, or if `npm install -g` exits 0 but the active runtime is still old, `update` exits nonzero with details such as `active runtime root`, `npm global root`, `runtime before`, `runtime after`, and `command matches runtime`. On root-owned Linux prefixes, run the printed `sudo npm install -g llm-wiki-kit@<target>` command, then run the printed `llm-wiki post-update ...` command as the normal Codex/Claude user.

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

On Native Windows, use PowerShell:

```powershell
where 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, reconnect through the installer:

```bash
llm-wiki install --workspace /path/to/project --profile standard
hash -r
llm-wiki status --workspace /path/to/project
```

After a manual `sudo npm install -g llm-wiki-kit@latest`, a normal-user `llm-wiki update --workspace <search-root>` can be used to reapply hooks, bundled Codex/Claude skills, and managed templates. When the installed runtime already matches the registry target, `update` skips only the npm install step and still runs post-update maintenance. In that case, `npm install: skipped (runtime already current)` is expected; confirm `post-update: ran` plus the `projects processed`, project-template changed/skipped/unchanged counts, and `project details` lines to see what project maintenance did.

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.

Running `llm-wiki post-update --workspace /path/to/project` or `llm-wiki install --workspace /path/to/project --profile standard` also reconnects hook entries to the current runtime. On Linux/macOS, `install` uses an npm/nvm global command when it already resolves to the current runtime, creates or keeps a current `~/.local/bin/llm-wiki` fallback shim for narrow agent PATHs, and replaces older kit-managed local shims that do not point at the current runtime. On Windows, `install` relies on npm's `llm-wiki.cmd` shim and does not create a Unix-style symlink.

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`. Let install handle managed shims first:

```bash
llm-wiki install --workspace /path/to/project --profile standard
hash -r
which -a llm-wiki
readlink -f "$(command -v llm-wiki)"
llm-wiki version
llm-wiki status --workspace /path/to/project
```

Do not remove the entire `~/.local/bin` directory; it may contain unrelated commands. If `status` or `doctor` reports an unmanaged local command that still shadows npm, inspect that one file before removing it. If the nvm command is missing, 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.

If `where llm-wiki` is empty on Windows after npm install, the active Node npm prefix is not on `PATH` or npm did not create the shim. Reinstall with the active Node installation, then restart the terminal:

```powershell
npm uninstall -g llm-wiki-kit
npm install -g llm-wiki-kit@latest --registry=https://registry.npmjs.org/ --prefer-online
where llm-wiki
llm-wiki install --workspace C:\path\to\project --profile standard
llm-wiki doctor --workspace C:\path\to\project
```

## npm install -g Fails With EACCES

If npm tries to write under `/usr` and fails with `EACCES`, use sudo only for the package install when the server policy allows system-wide global packages:

```bash
sudo npm install -g llm-wiki-kit@latest
llm-wiki post-update --workspace /path/to/project
llm-wiki status --workspace /path/to/project
```

Do not use `sudo llm-wiki update` as the normal recovery path. The npm package may install, but the follow-up hook, skill, and managed-template writes can run as root and update the wrong Codex/Claude home or leave root-owned project files. If you need to refresh many known projects after the sudo package install, run this as the normal user:

```bash
llm-wiki update --workspace /path/to/search-root
```

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 the isolated home/prefix procedure above, or the exact-tarball release verifier in `docs/manual.md`. Never install an unpublished candidate globally or run it against a real workspace/provider home.

## 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

## Maintenance Queue Is Empty Or Stale

In the default answer-first mode, `llm-wiki/outputs/maintenance/queue.md` is created when a user explicitly asked for durable recording/documentation, a turn has a structured durable conclusion, or stale per-turn state is recovered, and no durable wiki update was detected. It is not expected to grow after every normal `Stop`, and ordinary durable words inside a work summary are not enough by themselves.

Check the queue and health warnings:

```bash
llm-wiki maintenance --workspace /path/to/project
llm-wiki maintenance --workspace /path/to/project --apply-lifecycle --dry-run
llm-wiki lint --workspace /path/to/project
```

If the queue is always empty during ordinary Q&A, that is normal. If you expected an explicit documentation request or structured durable conclusion to queue, confirm hooks run and that the turn had a captured `UserPromptSubmit`. If pending items stay around, the active agent should batch-review them, merge only explicit, repeated, or clearly reusable content into existing durable wiki pages, and mark each item `done` or `skipped` without delaying unrelated answers. When pending reaches the lifecycle threshold, `--apply-lifecycle` keeps candidates pending for batch review, skips stale low-signal items, archives old reviewed entries, and migrates known deprecated layout (`raw/inbox`, `raw/assets`, top-level `sources`, top-level `templates`, `wiki/entities`, and legacy daily live Q&A files) into the current layout. The cleanup is content-preserving: originals are archived or moved, conflicts receive migrated suffixes, unknown directories are left for review, and durable wiki pages are never created or auto-approved automatically.

## Authentication Values Were Redacted

The hook does not block tool calls only because inputs look sensitive. Durable summaries redact authentication values before writing, while ordinary work context such as dates, phone numbers, emails, and business identifiers is preserved by default.

Hook payloads are stored as small redacted event envelopes rather than full transcripts. `PreCompact` never reads `transcript_path`; its checkpoints contain only bounded, redacted turn state already captured by hook events. Manual and hook context output is redacted before wiki excerpts or search hits are returned.

## Duplicate Pages Appear

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