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

## Windows Codex or Claude Code Does Not Run a Hook

Windows provider hooks start a small `node.exe -e` bootstrap, which then launches the exact installed Node binary and `llm-wiki.js` path stored in the hook. The outer `node.exe` must resolve in the environment used by Codex or Claude Code. Windows shell search can differ from the installer process and may select a current-directory executable before a PATH entry. A terminal can find Node while an already-running agent has a different `PATH` or working directory.

Check Node from a new terminal, reinstall the managed hooks as the settings owner, and restart the provider:

```powershell
where.exe node.exe
node.exe --version
llm-wiki install --workspace C:\path\to\project --profile standard
llm-wiki status --workspace C:\path\to\project
```

If `where.exe node.exe` cannot find Node, add the Node installation directory to the environment used to start the agent, then restart it. This terminal lookup does not prove which executable the provider will select; check for an unintended `node.exe` in the provider's current project directory or earlier search locations. If hooks still do not run, inspect the status/doctor result for a stale or user-edited hook. With the current expected matcher, normal install/update updates the unambiguous kit command in place while preserving user sibling hooks. A known legacy default matcher is normalized only for a pure kit-owned entry with no user siblings. Custom matchers and multiple kit duplicates stay stale for review. Use explicit `--replace-hooks` only when duplicate entries are proven kit-owned and their non-command metadata, including nested fields, matches. Uninstall can remove a proven kit command after its matcher was edited while preserving user fields; a mixed hook object with another unknown/user command field remains wholly untouched. Do not hand-edit the Base64 command.

When install/update cannot reconcile a stale or partial provider setup safely, it prints the warning, preserves provider warnings/partial state in the existing result, and exits nonzero. It does not add a new JSON `incomplete` field. `llm-wiki status` adds `codexStaleEvents` and `claudeStaleEvents` to report stale/unmanaged hooks separately from missing hooks. Review the existing command entry before choosing `--replace-hooks`; no new command flags are required for ordinary setup.

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

## `new` Says The Workspace Is Not Initialized

`llm-wiki new` only writes into an initialized project wiki. Bootstrap the intended project root first, then retry:

```bash
llm-wiki bootstrap --workspace /path/to/project
llm-wiki new release-checks --workspace /path/to/project --type procedure
```

Check that `--workspace` points to the project root, not to `llm-wiki/` itself. The command validates the destination under an allowed wiki or procedure root; traversal, absolute paths, and symlink escapes fail before a page is written.

## Fork Reports A Destination Conflict

Preview all source pages and target collisions without writing:

```bash
llm-wiki fork --from /path/to/source --to /path/to/target --dry-run
```

By default, any existing destination stops the fork without changing target files. Review the plan, then pass `--overwrite` only when replacing those pages is intended. The prior destination is backed up first. Private and no-export pages are skipped by the fork policy.

## Provider Integration Is Missing Or Unmanaged

`status` and `doctor` distinguish the saved provider selection from integrations observed on disk. Inspect the selected set and required checks:

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

These provider overrides are read-only. To change the saved installation choice, run `install` or `update` with `--providers codex` and, when relevant, `--skills`. A provider outside the managed selection is not reinstalled by later updates.

## Search Reports Partial Results

For `--all-projects`, `partial-results` or `incomplete: true` means at least one project could not be fully searched or discovered. Read the available project provenance, reduce the search root, or raise `--max-dirs` if the intended projects were beyond the discovery cap. A partial result exits nonzero; do not describe it as a complete search. A normal no-hit result is still a successful search.

## Full Uninstall Stops Before Removing The Wiki

`uninstall --full` requires a verified backup outside the wiki before it changes providers or removes wiki content. A backup path, copy, hash, containment, or final identity failure stops removal. Check free space and the reported backup location, then inspect the source wiki and retry only after correcting the cause. Do not delete a partial backup to make room until its recovery value is understood.

If the command reports a partial mutation, inspect the sanitized operation record before acknowledging it:

On Windows, a file-lock or rename failure while recording the operation's final state can report `WORKSPACE_MUTATION_FINALIZE_FAILED` with a message such as `workspace mutation completion could not be recorded`. Some page or provider changes may already be complete; this error does not mean they were rolled back. Stop other writes to the workspace, inspect the operation record, and review any listed backup before choosing recovery:

```bash
llm-wiki maintenance --workspace /path/to/project --inspect-operation
llm-wiki doctor --workspace /path/to/project
```

Use `--ack-operation <id>` only when inspection confirms the owner is no longer active and the current file inventory and hashes satisfy the operation's recorded state. The command rechecks those conditions; do not acknowledge blindly. Acknowledgement clears the mutation guard; it does not restore files or roll back a provider change.

## Release Digest Or Installed Manifest Check Fails

Do not publish or install the candidate globally. The tarball may differ from the expected build, the source checkout may not match its pushed ref, or an installed file may differ from the external manifest. Repack from a clean checkout of the exact pushed SHA, recreate the manifest, and repeat both Linux and native Windows gates against the same tarball. See [Release Verification](manual.md#release-verification).

When `-ExpectedSha256` is supplied, the Windows verifier requires a 64-character hexadecimal SHA-256 digest and checks it against the tarball before installing. Candidate preflight may supply only that digest. Final verification with `-ReleaseManifest` requires both flags, checks their digest/version agreement, and verifies installed file hashes before running feature stages. A version match alone does not prove which source bytes were installed.
