# Operations

## Profiles

`standard` is the default:

- inject context
- record redacted summaries
- allow tool calls while redacting authentication values before storage
- 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
- enforce project-specific storage policies more aggressively

## Install

Published npm package:

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

Native Windows:

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

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:

- uses an npm/nvm global `llm-wiki` command when it already resolves to the current runtime
- on Linux/macOS, creates or keeps a current `~/.local/bin/llm-wiki` fallback shim for non-login Claude/Codex Bash environments
- on Linux/macOS, replaces older kit-managed local shims that do not point at the current runtime, while leaving unmanaged local commands alone when another current runtime command is available
- on Windows, relies on the npm-generated `llm-wiki.cmd` shim and does not create a Unix-style local symlink
- 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`

By default, a fresh install manages Codex and Claude Code hooks/skills plus the opencode bridge. Use `--providers codex,claude` or `--providers none` to select integrations; `--no-codex`, `--no-claude`, and `--no-opencode` subtract from the selected set. `--skills` and `--no-skills` explicitly set bundled skill management. Install/update choices are stored in the operator's kit data directory and reused on later updates. `status --providers ...` and `doctor --providers ...` only override the diagnostic view; they do not save a new selection. A provider outside the managed selection may still be installed and is reported as unmanaged.

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 /path/to/project --profile standard
```

On Windows source checkouts, run the CLI through Node instead of `install.sh`:

```powershell
npm install
node bin\llm-wiki.js install --workspace C:\path\to\project --profile standard
```

Pre-publish server smoke tests must use an isolated home, npm prefix, provider homes, and temporary workspace. Do not install the candidate globally:

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

Do not delete a project `llm-wiki/` tree to reinstall the runtime. `llm-wiki uninstall` preserves wiki contents by default. `uninstall --full` is the explicit removal path and verifies an external backup before removing the wiki.

## Windows Verification Runner

Use `scripts/windows-runner/` for long Windows checks that should survive transport disconnects. The runner is a filesystem-backed queue, not a network service. Prefer SSH/scp for normal submission and polling; keep WinRM only as a bootstrap or emergency recovery fallback.

Install the scheduled task once on Windows:

```powershell
Set-Location <llm-wiki-kit>\scripts\windows-runner
.\install-scheduled-task.ps1 -Root C:\llm-wiki-runner
```

The default task is on-demand only: it has no repeating trigger, uses hidden task settings, and runs one queued job only when `Start-ScheduledTask -TaskName LlmWikiWindowsRunner` is called. Use `-EnablePolling -IntervalMinutes <minutes>` only for machines where a periodic background poller is acceptable.

Submit a job by writing `queue\<id>.json`; the `id` field must match the filename:

```json
{
  "id": "20260620-001",
  "command": "pwsh",
  "args": ["-NoProfile", "-File", "C:\\llm-wiki-runner\\scripts\\verify.ps1"],
  "cwd": "C:\\work\\llm-wiki-kit",
  "timeout_seconds": 900
}
```

From Linux/Codex, use SSH/scp only for short submission and polling:

```bash
scp job.json windows-host:/C:/llm-wiki-runner/queue/20260620-001.json
ssh windows-host 'powershell -NoProfile -Command "Start-ScheduledTask -TaskName LlmWikiWindowsRunner"'
ssh windows-host 'powershell -NoProfile -Command "Get-Content C:\llm-wiki-runner\logs\20260620-001.status.json"'
```

The runner moves jobs through `queue\`, `running\`, `done\`, and `failed\`, and writes `logs\<id>.status.json`, `logs\<id>.stdout.log`, and `logs\<id>.stderr.log`. Final states are `succeeded`, `failed`, or `timed_out`. Keep credentials and raw `.env` contents out of job JSON and logs; use the Windows account's secret store when a verification script needs secrets.

Use WinRM only to bootstrap or recover the Windows host when SSH, `sshd`, the scheduled task, or the queue directory is unavailable. Normal release and regression checks should go through SSH/scp plus `LlmWikiWindowsRunner`.

## Maintainer And Agent Reference

Daily work should happen through Claude Code/Codex. These commands are for maintainer checks, troubleshooting, and agent-side maintenance.

```bash
llm-wiki version
llm-wiki status --workspace /path/to/project
llm-wiki doctor --workspace /path/to/project
llm-wiki projects --workspace /path/to/search-root
llm-wiki update --check --workspace /path/to/project [--to <version-or-tag>]
llm-wiki update --workspace /path/to/search-root
llm-wiki update --current-only --workspace /path/to/project
llm-wiki update --dry-run --workspace /path/to/project
llm-wiki update --workspace /path/to/search-root --timeout-ms 120000 --max-dirs 5000
llm-wiki install --workspace /path/to/project --providers codex,claude --skills
llm-wiki doctor --workspace /path/to/project --providers codex
llm-wiki search "release" --workspace /path/to/project --all-projects --max-dirs 500
llm-wiki maintenance --workspace /path/to/project --inspect-operation
llm-wiki post-update --workspace /path/to/project
llm-wiki post-update --all --workspace /path/to/search-root
llm-wiki context "search phrase" --workspace /path/to/project --budget-chars 4000 --show-hidden-reason
llm-wiki context "search phrase" --workspace /path/to/project --compact --max-context-chars 900
llm-wiki memory "search phrase" --workspace /path/to/project
llm-wiki lint --workspace /path/to/project
llm-wiki consolidate --workspace /path/to/project
llm-wiki maintenance --workspace /path/to/project
llm-wiki maintenance --workspace /path/to/project --apply-lifecycle --dry-run
llm-wiki archive-questions --workspace /path/to/project --dry-run
```

`status` is offline and answers whether the local installation is internally consistent:

- runtime version and install source
- whether the `llm-wiki` command on `PATH` resolves to the current runtime
- Codex/Claude hook entries pointing at the current runtime
- project template state from `llm-wiki/.kit-state.json`
- active wiki root and workspace-root ambiguity warnings
- current managed file hashes
- auto-updateable managed rules and managed-looking rules that need agent cleanup
- pending wiki maintenance count
- command lifecycle registry health so public commands, hook reminders, and internal hook modules do not drift apart
- provider-specific bundled skill state for Codex at `$CODEX_HOME/skills` or `~/.codex/skills`, and Claude Code at `~/.claude/skills`
- managed provider selection, whether it came from explicit CLI intent or legacy integration traces, and any incomplete install attempt

`update --check [--to <version-or-tag>]` is online and asks npm for the target version. It reports `update available` only when that registry target is newer than the installed version, so it does not suggest downgrades.

Installed npm runtimes also run a cached hook-side update notice check while the user works. It never installs automatically. If npm has a newer release, `SessionStart`/`InstructionsLoaded`/`UserPromptSubmit` context includes a passive runtime update status for both Codex and Claude: current runtime, npm registry target, and the manual `llm-wiki update --workspace <project-or-search-root>` command to use when the user asks for update or maintenance work. It is not an active instruction to interrupt the current answer or tell the user to update. 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` to suppress this status block while diagnosing.

`projects --workspace <search-root>` lists discovered project roots that have `llm-wiki/.kit-state.json` or an older `llm-wiki/wiki/index.md`, reports whether their managed templates are current, and prints the update commands for the search root.

`update` applies changes explicitly only when the user runs it:

- runs `npm install -g llm-wiki-kit@<target>` only when the registry target is newer than the installed runtime
- skips only npm installation when the installed runtime already satisfies the target, then still runs post-update maintenance
- checks `npm root -g`/`npm prefix -g` before install and refuses to claim success when npm would update a different global prefix than the active runtime
- verifies that the active runtime and `post-update` child runtime reached the registry target after install
- prints before/after runtime, registry target, npm global root, active runtime root, and PATH command diagnostics
- reinstalls hook entries without duplicating them
- syncs bundled Codex and Claude Code skills only for selected providers; removal skips unmanaged or locally edited skills unless kit ownership and unchanged content are verified
- patches only managed project files across known or discovered project roots
- backs up changed files under `~/.local/share/llm-wiki-kit/backups/`
- prints `project details` lines showing each processed directory, changed paths, skipped `path:reason` entries, and unchanged counts
- prints update progress to stderr and keeps JSON output parseable on stdout
- force-kills unresponsive child commands after timeout so slow npm/WSL environments do not wait forever

By default, `update --workspace <search-root>` performs the npm runtime update once, then reapplies managed templates to every known or discovered project root under the search root. Use `update --current-only --workspace <project>` to limit template reapplication to one project. Use `--max-dirs` when a search root is a very large or slow tree.

`post-update --workspace <project>` skips npm installation and reapplies the saved provider selection, its bundled skills, and safe managed template updates. `post-update --all --workspace <search-root>` does the same template reapplication across discovered project roots. Text output reports projects processed separately from the managed template changed/skipped/unchanged counts. Use `--providers <list>` for an explicit install/update selection, `--skills` or `--no-skills` to set skills intent, and `--no-codex`, `--no-claude`, or `--no-opencode` to subtract a provider. An explicit selection is preserved by later updates; a provider excluded from it is not reinstalled.

After a plain `npm install -g llm-wiki-kit@latest`, existing hooks keep working when they already point at the global npm package path. `SessionStart` and `InstructionsLoaded` inspect project state and may report stale templates, but they do not rewrite project files. Run `llm-wiki post-update --workspace <project>` or `llm-wiki install --workspace <project>` explicitly to refresh templates or reconnect stale hooks. On Linux/macOS, `install` also creates or keeps a current `~/.local/bin/llm-wiki` fallback shim so agent Bash sessions can find the command when their PATH omits the npm/nvm global bin directory.

## Context And Wiki Maintenance

Daily use should be Claude Code/Codex first. The user should not need to run a chain of `llm-wiki` commands while working. Hooks inject context automatically, but the current user answer takes priority over wiki cleanup. The active agent updates durable wiki pages when reusable project knowledge appears and the turn's importance or user consent justifies persistence. Hook context policy is function-first: memory, search, maintenance, and update signals remain available, while user-visible context is formatted as functional compact context instead of a raw dump.

In the answer-first capture mode, `Stop` and `SessionEnd` append live Q&A only for handoff-worthy durable checkpoints: explicit documentation requests from the captured user question, structured durable conclusions, or detected durable wiki/procedure updates. Simple answers, status checks, keyword-only responses, ordinary tool-heavy work, verification-only summaries, and ordinary durable keywords such as "root cause" inside work summaries are not promoted by themselves. Live Q&A uses chunked files under `llm-wiki/outputs/questions/YYYY-MM-DD/` and rolls over by line/byte budget. Hooks do not auto-create `wiki/queries/` or `wiki/decisions/`. If the user explicitly asked for recording/documentation, or the turn contains a structured durable conclusion such as `Decision:` or `Root cause:`, and no durable wiki/procedure update is detected, a pending cleanup candidate is written to `llm-wiki/outputs/maintenance/queue.md` with a local `signal_level` such as `explicit`, `high`, `low`, or `recovered`. Debugging-style conclusions such as `Root cause:`, `Resolution:`, and `Fix:` enter the queue only when verification or changed-file evidence exists. `PreCompact` performs the same answer-first classification before context compaction: non-durable turns remain transient, archive-worthy turns get a live Q&A checkpoint, and explicit/structured durable candidates get a checkpoint plus queue item only when needed. If checkpoint storage fails, compaction still proceeds and the hook prepares an important-only compact recovery packet for the next legal context-injection event. `SessionStart` and `UserPromptSubmit` recover stale per-turn state into the same queue only when the buffered turn is queue-worthy and the previous stop hook did not complete. `SessionStart` can inject a queue summary but does not apply mutating lifecycle hygiene; `UserPromptSubmit` injects a compact soft reminder only for wiki/maintenance prompts, approved items, explicit durable requests, recovered items, or when the queue crosses the batch review threshold. This is a recovery and reminder layer, not a transcript capture path.

Use `llm-wiki archive-questions --workspace <project> --dry-run` to review splitting legacy `outputs/questions/YYYY-MM-DD-live-qa.md` files into the chunked layout. Running it without `--dry-run` preserves the original under `outputs/questions/archive/originals/` with a checksum sidecar and replaces the legacy file with a pointer stub.

Pre-compact preservation defaults to `LLM_WIKI_KIT_PRECOMPACT_ENFORCEMENT=limited`, but compaction is never blocked by llm-wiki-kit. `limited` and `soft` emit non-blocking failure warnings, and `off` suppresses failure output. `PreCompact` never opens `transcript_path`; it uses only bounded, redacted state captured by prior hook events.

`llm-wiki context "<query>"` is the manual full-debug form of the context sources used by hook injection. Hook output for Codex and Claude may be functionally compact, but this command remains verbose so maintainers can inspect all source layers. It reads:

- `llm-wiki/wiki/memory.md` as the short hot index
- `llm-wiki/wiki/index.md` as the navigation map
- MiniSearch results from durable `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

Default context search prioritizes durable semantic/procedural pages and also searches metadata such as `aliases`, `description`, `globs`, and scalar values under `extensions`. Extension matches have a low boost. It hides pages with `memory_type: episodic` and episodic query/context/session roles unless explicitly promoted. It also hides `status: archived` and `superseded_by` pages unless `--include-archived` is requested. `status: stale` pages remain searchable but receive a lower score. JSON output includes memory/index/hit/snippet budget metadata plus hit confidence metadata so maintainers can see how much context each layer consumed and why hook output may suppress weak matches. Use `--budget-chars <n>` to inspect bounded hit snippets, `--compact --max-context-chars <n>` to preview hook-sized output, and `--show-hidden-reason` to see which pages were excluded by durable visibility policy. Use `--include-episodic` only when debugging historical automatic pages:

Use it only 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 --budget-chars 4000 --show-hidden-reason
llm-wiki context "auth architecture" --workspace /path/to/project --compact --max-context-chars 900
llm-wiki context "auth architecture" --workspace /path/to/project --limit 8 --no-expand
llm-wiki context "auth architecture" --workspace /path/to/project --include-episodic
llm-wiki context "auth architecture" --workspace /path/to/project --include-archived
```

`llm-wiki memory [query]` is the read-only review surface for the active wiki. It prints the active wiki root, current `memory.md` focus bullets, durable entry points, optional retrieval hits for the query, maintenance queue state, and lint/eval health. Use it when checking whether the wiki is helping agent onboarding and handoff; queue state changes still go through `llm-wiki maintenance`.

`llm-wiki lint` checks Markdown wiki health without modifying wiki content (it may write `.kit/` runtime caches such as the search-corpus index and the lint-batch counter). The lint gate is **batched** by default: 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. `llm-wiki lint <file> --workspace <project> --fail-on-warning --suppress-auto-fixable` remains available as an on-demand single-file spot-check (`--fail-on-warning` makes warnings fail too, `--suppress-auto-fixable` hides only frontmatter issues the next Stop hook auto-normalizes), but is no longer required after every write. Single-file lint includes page-local rules plus link resolution against the full alias/graph and excludes corpus-global and graph-derived rules (e.g. `orphan-page`) that editing the file cannot fix. Per-path lint exceptions live in `llm-wiki/.kit/lint-exceptions.json` (absent = none): each entry suppresses one code on a `paths` glob with a required `reason` and optional `expires`; secret-detection codes demote to `warning` (never silent, also under global `lintSeverity: off`) and corpus-integrity codes cannot be excepted. `llm-wiki lint --show-suppressed` re-shows dropped issues; `llm-wiki doctor` validates the file; suppressed/demoted findings are recorded redacted in `llm-wiki/outputs/maintenance/lint-exceptions.log`.

Corpus lint checks include:

- missing `index.md`, `log.md`, or `memory.md`
- missing or invalid frontmatter
- missing required core frontmatter, unknown top-level fields, invalid `extensions`, duplicate YAML keys, aliases, or custom tags
- 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`
- invalid `activation`, `visibility`, `aliases`, or `globs` frontmatter
- missing `evidence_refs` on reviewed high-importance durable pages
- secret-like content patterns such as tokens, password assignments, bearer credentials, and private keys
- duplicate aliases or titles
- stale pages and orphan candidates
- `memory.md` near-budget or oversized state
- `index.md` near-budget or oversized state and excessive `importance: 5` saturation
- wiki page count near the growth review threshold (default search still indexes the complete tree)
- default-hidden episodic/context/session page growth
- stale/archived pages without supersession metadata or links
- outdated managed rules/templates from earlier `llm-wiki-kit` versions
- stale or oversized maintenance queues

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`
- refreshes the generated block inside `wiki/queries/archive-index.md`, an episodic page that collects archived/superseded wiki pages and outputs archives (live Q&A days, reviewed maintenance months) so they stay findable via `--include-episodic`
- balances generated memory across page types and caps it at 12 pages/8KB
- caps generated index output at 80 pages, 8 pages per type, and 24KB
- caps generated archive-index output at 16KB
- keeps only durable non-archived pages in generated maps
- skips `stale`, `archived`, and `superseded_by` pages from durable generated maps while preserving them on disk and listing them in `archive-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`)
- reports shown/omitted memory, index, and archive counts, hidden episodic pages, and archived/stale/superseded skipped counts, including in `--dry-run`
- 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`

Agents may run `consolidate` after meaningful wiki growth. Users should not need to run it after every turn.

The full health budgets are 16KB for `memory.md` and 32KB for `index.md`; lint begins warning at 12KB and 24KB respectively. Generated blocks stay below tighter limits so handwritten material retains room.

Curated pages require `title`, `type`, `status`, `memory_type`, and `last_updated`. Optional standard fields use defaults, and project-specific typed metadata belongs under `extensions` with lowercase snake_case keys. Semantic edits must update `last_updated` and revise evidence or verification metadata when its meaning changed. Formatting-only normalization does not count as verification.

Use `llm-wiki maintenance --workspace <project> --normalize-frontmatter --dry-run` to preview explicit normalization. Without `--dry-run`, the command backs up changed files, fills inferable core fields, merges legacy `source_id`, removes redundant defaults, and moves unknown top-level fields under `extensions`. It accepts UTF-8 BOM and Windows CRLF input, and leaves malformed YAML, invalid extension keys, and extension collisions untouched for manual review. Hooks never run it automatically.

`llm-wiki maintenance --workspace <project>` prints queue counts, review due status, and the first pending items. It does not merge wiki pages by itself; the active agent should batch-review pending or approved items, update the closest existing durable wiki document only for explicit, repeated, or clearly reusable facts, then mark the queue item `done` or `skipped`. Periodic maintenance is an agent-side task, not something users need to run after every turn.

`llm-wiki maintenance --workspace <project> --apply-lifecycle --dry-run` previews queue hygiene and deprecated layout cleanup. Running it without `--dry-run` keeps explicit/high-signal pending candidates pending for batch review when pending reaches 15, skips low-signal pending candidates older than 14 days, never auto-skips explicit requests or recovered `result_missing` items, moves old `done`/`skipped` items beyond the latest 10 into `outputs/maintenance/archive/YYYY-MM.md`, and migrates known deprecated layout content into the current taxonomy. `raw/inbox/` moves to `raw/sources/`, `raw/assets/` moves to `raw/sources/assets/`, top-level `sources/` moves to `wiki/sources/`, top-level `templates/` moves to `wiki/context/`, and `wiki/entities/` moves to `wiki/concepts/` with entity page frontmatter rewritten to `type: "concept"`. 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 writes new durable wiki conclusions automatically, never auto-approves page promotion, and never deletes user content to force conformity; byte-identical files can be deduplicated, conflicts get `*-migrated-<timestamp>` names, and unknown directories are surfaced for review. Routine hooks only surface reminders; lifecycle changes require this explicit command.

`llm-wiki maintenance --workspace <project> --json` includes `reviewDue`, `reviewReasons`, `pendingCount`, `stalePendingCount`, `health`, `recommendedCommands`, and lifecycle action counts when lifecycle is applied. Review is due when the last review is older than 14 days, pending queue size reaches 15, stale or result-missing pending items exist, lint has warnings/errors, `memory.md` is near budget, or wiki page count reaches 80% of the growth review threshold. This threshold does not truncate search. Hook reminders are soft: `SessionStart`/`InstructionsLoaded` may show a short due note, while `UserPromptSubmit` shows one compact item only for wiki/maintenance prompts, approved items, explicit durable requests, recovered items, or batch review threshold pressure. The reminder never blocks the current answer.

Recommended agent checklist:

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

When a new runtime sees an older project, `SessionStart`/`InstructionsLoaded` report managed-template drift without modifying files. Run `llm-wiki post-update --workspace <project>` or `llm-wiki install --workspace <project>` to refresh clearly generated files. Files that look user-edited are preserved and surfaced to the active agent as cleanup context instead of being overwritten.

## 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, run install once. The kit replaces older managed local shims that do not point at the current runtime, keeps current local shims as safe fallbacks, and reports unmanaged local commands through `status`/`doctor`.

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

Do not delete the whole `~/.local/bin` directory. It may contain unrelated user tools.

## Updating Native Windows Installs

Windows uses npm's command shim. If `llm-wiki` is missing or old after install, inspect the Windows command resolution:

```powershell
where llm-wiki
npm root -g
node "$(npm root -g)\llm-wiki-kit\bin\llm-wiki.js" version
llm-wiki status --workspace C:\path\to\project
```

If `where llm-wiki` does not show the npm shim, reinstall the package in the active Node installation:

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

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 its recorded hash still matches, the whole file exactly matches the current generated template, or the whole file exactly matches a known legacy generated template
- generated procedures are replaced only when their recorded hash still matches, the whole file exactly matches the current generated template, or the whole file exactly matches a known legacy generated template
- missing generated `llm-wiki/AGENTS.md` and procedure files are restored when the project wiki tree exists
- customized managed-looking files and malformed root policy markers are not overwritten; `status`, `lint`, and injected maintenance context surface them for agent cleanup
- `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.

For Korean-first Codex projects, set `preferredLanguage: "ko"` in `llm-wiki/.kit-state.json` when neutral prompts should stay Korean. This is especially useful after Codex plan approval, because Codex may submit `Implement the plan.` as the next prompt and the runtime deliberately treats that exact synthetic prompt as language-neutral.

## Release Checklist

Before publishing, run the source suite and build an isolated candidate:

```bash
node --test
npm audit --omit=dev --audit-level=high
npm pack --dry-run
git diff --check
candidate_dir="$(mktemp -d)"
npm pack --json --pack-destination "$candidate_dir"
```

Install the candidate only into an isolated home, npm prefix, provider roots, and temporary project. Run the setup/use scenarios on Linux and native Windows against the same candidate tarball. Do not install a prepublish candidate globally or point it at a real workspace. Include `bin/`, `src/`, `skills/`, `docs/`, `scripts/`, `examples/`, the tests required by the native Windows verifier, `README.md`, `LICENSE`, `install.sh`, and `package.json`; exclude project-local `llm-wiki/` content.

For native Windows changes, run the isolated verifier against the same candidate tarball:

```powershell
pwsh -NoProfile -File .\scripts\windows-runner\verify-release.ps1 -Mode Tarball -PackageSpec .\llm-wiki-kit-<version>.tgz -ExpectedVersion <version> -OutputPath .\release-result.json
```

For this initial candidate pass, add `-ExpectedSha256 <candidate-sha256>` to bind the smoke to the concrete tarball. A release manifest is not required until the final artifact is rebuilt from the clean pushed SHA.

The verifier creates disposable provider homes and a temporary project, checks installed hooks/skills/templates, and runs native NTFS feature stages without changing the normal user's provider state. If automated from Linux, prefer SSH/scp plus the Windows verification runner. Use WinRM only as a bootstrap or emergency recovery fallback, and keep credentials only in environment variables or a secret store.

After candidate preflight, commit and push the reviewed release scope only with release authorization. From the exact clean pushed SHA, pack again and create an external release manifest:

```bash
mkdir -p /path/to/verified
npm pack --json --pack-destination /path/to/verified
node scripts/release/create-manifest.mjs \
  --tarball /path/to/verified/llm-wiki-kit-<version>.tgz \
  --output /path/to/verified/release-manifest.json \
  --source-ref origin/main
```

The helper fails if the checkout is dirty, if `HEAD` differs from the tracking ref, or if an `ls-remote` read says the actual remote branch has moved. The manifest records the source SHA, version, tarball SHA-256/SHA-512 integrity, lockfile hash, toolchain, packed paths, and hashes for files under `bin/`, `src/`, `skills/`, and `docs/`. Keep it outside the tarball. Run both platform feature matrices on this final tarball and manifest:

```powershell
pwsh -NoProfile -File .\scripts\windows-runner\verify-release.ps1 `
  -Mode Tarball `
  -PackageSpec C:\release\llm-wiki-kit-<version>.tgz `
  -ExpectedVersion <version> `
  -ExpectedSha256 <sha256-from-manifest> `
  -ReleaseManifest C:\release\release-manifest.json
```

On Linux, run both installed-byte verification and the feature matrix against the same package root:

```bash
node scripts/release/verify-installed-manifest.mjs --manifest /path/to/verified/release-manifest.json --package-root /path/to/isolated/prefix/node_modules/llm-wiki-kit --tarball /path/to/verified/llm-wiki-kit-<version>.tgz
node /path/to/isolated/prefix/node_modules/llm-wiki-kit/scripts/release/verify-features.mjs --package-root /path/to/isolated/prefix/node_modules/llm-wiki-kit --expected-version <version>
```

The feature verifier runs packaged fixture suites and a CLI smoke with temporary homes. Its `passedIds` lists the F01–F12/U01–U04 coverage; the Windows runner adds each ID as a separate result stage. It cleans its temporary data when it exits.

For long automated checks, submit the release smoke through `scripts/windows-runner/` and poll its status. This keeps verification local to Windows when transport disconnects. If code, docs, version, or bytes change after the final manifest, rebuild and repeat both platform gates. Publish only that verified tarball when explicitly authorized.

After publishing, verify registry delivery in isolated Linux and Windows environments against the recorded version and SHA-512 integrity. Do not make global installs or normal provider/workspace writes part of a prepublish test. A registry smoke must verify installed bytes and exercise at least the setup, status, doctor, lint, eval, memory-health, and hook/skill/template paths before the release is complete.

```bash
npm view llm-wiki-kit version
npm view llm-wiki-kit dist.integrity --json
```

For example, use a temporary prefix and user home when installing from the registry:

```bash
smoke_root="$(mktemp -d)"
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 llm-wiki-kit@<version>
```

On Windows, run the same registry package test with temporary `HOME`, prefix, and provider roots through the native runner. Compare registry `dist.integrity` to the manifest SHA-512 integrity and verify installed files. Tag only after Linux and Windows registry-install verification succeeds.

## Uninstall

```bash
llm-wiki uninstall
```

The default removes kit-managed integrations and leaves project wiki contents intact. Use `llm-wiki uninstall --providers codex` to limit provider removal. `llm-wiki uninstall --full` also removes the wiki only after an external tree backup is created and verified. If backup creation, verification, or final identity checks fail, removal stops. A partial deletion reports which paths remain; the verified backup is retained for recovery. Backups can include private wiki/raw data, so protect their operator data directory.

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