llm-wiki-kit 0.2.4 → 0.2.6

package/README.md

@@ -16,6 +16,20 @@ llm-wiki doctor --workspace /apps
 
 Restart Claude Code and Codex sessions after installation.
 
+### 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
@@ -121,9 +135,11 @@ Installed npm runtimes also perform a cached update notice check from hooks whil
 
 For `llm-wiki-kit` code releases, source tests are not enough. After code changes, publish the package, install the newly published version, and verify the installed CLI and hooks with `version`, `status`, `doctor`, `update`, `lint`, and hook smoke checks before calling the release complete.
 
+Native Windows changes require a real Windows smoke before release. The release gate is: install the packed candidate on a Windows host, run `llm-wiki install`, `llm-wiki status`, and `llm-wiki doctor` against a temporary Windows project, inspect `%USERPROFILE%\.codex\hooks.json` and `%USERPROFILE%\.claude\settings.json`, then repeat the minimal smoke after `npm install -g llm-wiki-kit@latest` once published. Simulated unit tests are not enough for the Windows support claim.
+
 After a plain `npm install -g llm-wiki-kit@latest`, existing hooks keep working when they already point at the global npm package path. The next `SessionStart`/`InstructionsLoaded` hook automatically reapplies safe managed template updates for the active project root. Clearly generated older `llm-wiki/AGENTS.md` and procedure files are refreshed even when old state is missing; user-edited files are not overwritten and are surfaced to the active agent as cleanup work. If hooks point at a source checkout or stale shim, run `llm-wiki post-update --workspace <project>` or `llm-wiki install --workspace <project>` once to reconnect them.
 
-`llm-wiki install` no longer creates a user-local `~/.local/bin/llm-wiki` shim when an npm/nvm global `llm-wiki` command already resolves to the current runtime. If an older kit-managed local shim is shadowing that npm command, install backs it up and removes it.
+On Linux/macOS, `llm-wiki install` no longer creates a user-local `~/.local/bin/llm-wiki` shim when an npm/nvm global `llm-wiki` command already resolves to the current runtime. If an older kit-managed local shim is shadowing that npm command, install backs it up and removes it. 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:
 

package/docs/manual.md

@@ -120,6 +120,14 @@ llm-wiki install --workspace /path/to/project --profile standard
 llm-wiki install --workspace /path/to/project --profile standard --no-project
 ```
 
+Native Windows에서는 PowerShell/Windows Terminal에서 npm shim을 사용한다.
+
+```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
+```
+
 `standard` profile은 기본 profile이다.
 
 - context injection
@@ -130,7 +138,7 @@ llm-wiki install --workspace /path/to/project --profile standard --no-project
 
 `--no-project`는 hook/bin 설치만 하고 현재 workspace bootstrap은 하지 않을 때 사용한다.
 
-global npm package 설치 자체는 환경에 따라 `npm install -g` 또는 `sudo npm install -g`로 수행한다. hook 설정 갱신은 보통 일반 사용자 home 아래 파일을 수정하므로 `llm-wiki install`은 해당 user로 실행한다.
+global npm package 설치 자체는 환경에 따라 `npm install -g` 또는 `sudo npm install -g`로 수행한다. hook 설정 갱신은 보통 일반 사용자 home 아래 파일을 수정하므로 `llm-wiki install`은 해당 user로 실행한다. Windows에서는 npm이 만든 `llm-wiki.cmd`를 표준 command shim으로 사용하며 Unix-style `~/.local/bin` symlink를 만들지 않는다. Codex hook에는 Windows 실행용 `commandWindows`가 함께 기록된다.
 
 ### `llm-wiki update`
 
@@ -416,6 +424,18 @@ node --test
 npm pack --dry-run
 ```
 
+Native Windows 관련 변경은 publish 전 실제 Windows 설치 검증이 필수다. 후보 tarball을 Windows host에 설치하고 임시 project에서 다음을 확인한다.
+
+```powershell
+npm install -g .\llm-wiki-kit-<version>.tgz
+llm-wiki version
+llm-wiki install --workspace C:\Temp\llm-wiki-kit-smoke --profile standard
+llm-wiki status --workspace C:\Temp\llm-wiki-kit-smoke
+llm-wiki doctor --workspace C:\Temp\llm-wiki-kit-smoke
+```
+
+검증에는 `%USERPROFILE%\.codex\hooks.json`의 `commandWindows`, `%USERPROFILE%\.claude\settings.json`의 Windows-safe `node.exe` command, project-local `llm-wiki/` 생성, sample hook roundtrip이 포함된다. 원격 자동화는 WinRM을 사용하되 credential은 환경변수나 secret store로만 전달하고 wiki/log에 저장하지 않는다.
+
 publish 후 검증:
 
 ```bash
@@ -431,6 +451,8 @@ llm-wiki update --workspace /apps --current-only
 
 `llm-wiki-kit` 코드 변경 릴리스는 publish와 새 published version 설치 후 검증까지 끝나야 완료로 본다. root-owned global npm prefix에서는 package install에 `sudo npm install -g`가 필요할 수 있고, user home hook 갱신은 일반 user로 `llm-wiki install` 또는 `post-update`를 실행한다.
 
+Windows 지원 변경이 포함된 릴리스는 publish 후에도 같은 Windows host에서 `npm install -g llm-wiki-kit@latest` 후 최소 `version/status/doctor` smoke를 반복한다.
+
 ## Troubleshooting Shortcuts
 
 hook이 안 돈다면:
@@ -449,6 +471,14 @@ npm root -g
 node "$(npm root -g)/llm-wiki-kit/bin/llm-wiki.js" version
 ```
 
+Windows에서는 `where llm-wiki`와 npm prefix를 먼저 확인한다.
+
+```powershell
+where llm-wiki
+npm root -g
+node "$(npm root -g)\llm-wiki-kit\bin\llm-wiki.js" version
+```
+
 local shim이 npm global command를 shadowing하면:
 
 ```bash

package/docs/operations.md

@@ -24,6 +24,14 @@ npm install -g llm-wiki-kit
 llm-wiki install --workspace /apps --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
@@ -42,8 +50,9 @@ Avoid mixing root-owned and user-local installs unless you intentionally choose
 The installer:
 
 - uses an npm/nvm global `llm-wiki` command when it already resolves to the current runtime
-- removes an older kit-managed `~/.local/bin/llm-wiki` shim when it shadows that npm/nvm command
-- creates a user-local shim only when no `PATH` command points at the current runtime, such as source checkout development or user-local fallback installs
+- on Linux/macOS, removes an older kit-managed `~/.local/bin/llm-wiki` shim when it shadows that npm/nvm command
+- on Linux/macOS, creates a user-local shim only when no `PATH` command points at the current runtime, such as source checkout development or user-local fallback installs
+- 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/`
@@ -58,6 +67,13 @@ npm install
 ./install.sh --workspace /apps --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 can use a local tarball:
 
 ```bash
@@ -211,6 +227,25 @@ 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
@@ -242,6 +277,18 @@ npm pack --dry-run
 
 Check that the tarball includes `bin/`, `src/`, `docs/`, `examples/`, `README.md`, `LICENSE`, `install.sh`, and `package.json`, but does not include project-local `llm-wiki/` contents.
 
+For Native Windows changes, a real Windows smoke is mandatory before publishing. Install the candidate tarball on a Windows host and verify:
+
+```powershell
+npm install -g .\llm-wiki-kit-<version>.tgz
+llm-wiki version
+llm-wiki install --workspace C:\Temp\llm-wiki-kit-smoke --profile standard
+llm-wiki status --workspace C:\Temp\llm-wiki-kit-smoke
+llm-wiki doctor --workspace C:\Temp\llm-wiki-kit-smoke
+```
+
+Inspect `%USERPROFILE%\.codex\hooks.json` for `commandWindows`, `%USERPROFILE%\.claude\settings.json` for a Windows-safe `node.exe` hook command, and the temporary project for the generated `llm-wiki/` tree. If this is automated from Linux, use WinRM and keep credentials only in environment variables or a secret store.
+
 After publishing:
 
 ```bash
@@ -253,6 +300,8 @@ llm-wiki doctor --workspace /apps
 llm-wiki update --check --workspace /apps
 ```
 
+For Native Windows changes, repeat a minimal post-publish smoke on the same Windows host after `npm install -g llm-wiki-kit@latest`.
+
 ## Uninstall
 
 ```bash

package/docs/troubleshooting.md

@@ -123,6 +123,15 @@ 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
@@ -135,7 +144,7 @@ After a manual `sudo npm install -g llm-wiki-kit@latest`, a normal-user `llm-wik
 
 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. `install` uses an npm/nvm global command when it already resolves to the current runtime, removes an older kit-managed local shim when it shadows that command, and creates a local shim only when no `PATH` command points at the current runtime.
+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, removes an older kit-managed local shim when it shadows that command, and creates a local shim only when no `PATH` command points 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:
 
@@ -159,6 +168,16 @@ 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 when the server policy allows system-wide global packages:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-wiki-kit",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "Hook-first living LLM Wiki runtime for Codex and Claude Code.",
   "type": "module",
   "files": [

package/src/cli.js

@@ -131,7 +131,7 @@ Usage:
       `- workspace: ${value.workspace}`,
       `- runtime bin: ${value.binPath}`,
       `- command: ${value.commandPath || 'not found on PATH'}`,
-      `- local shim: ${value.localBin} (${value.localBinAction})`,
+      `- command shim: ${value.localBin || value.commandPath || 'not found'} (${value.localBinAction})`,
       `- changed hooks: ${value.changed.length ? value.changed.join(', ') : 'none (already installed)'}`,
       'Restart Codex/Claude Code sessions so new hooks are loaded.',
     ].join('\n'));
@@ -281,11 +281,12 @@ function formatStatus(value) {
   return [
     'llm-wiki-kit status',
     `- version: ${value.runtimeVersion}`,
+    `- platform: ${value.platform || process.platform}`,
     `- runtime: ${value.runtimeVersion} (${value.installSource})`,
     `- bin: ${value.binPath}`,
     `- command: ${value.commandPath || 'not found'}`,
     `- command matches runtime: ${value.commandMatchesRuntime ? 'yes' : 'no'}`,
-    `- local shim: ${value.localBin?.path || 'unknown'} (${value.localBin?.exists ? (value.localBin.managed ? 'managed' : 'unmanaged') : 'absent'}${value.localBin?.matchesRuntime ? ', current' : ''})`,
+    `- command shim: ${value.localBin?.path || 'unknown'} (${value.localBin?.exists ? (value.localBin.managed ? 'managed' : 'unmanaged') : 'absent'}${value.localBin?.matchesRuntime ? ', current' : ''})`,
     `- hooks current: ${value.hooksCurrent ? 'yes' : 'no'}`,
     `- codex hook: ${value.codexInstalled ? 'current' : 'missing/outdated'}`,
     `- claude hook: ${value.claudeInstalled ? 'current' : 'missing/outdated'}`,

package/src/doctor.js

@@ -1,9 +1,11 @@
 import { spawnSync } from 'child_process';
-import { join } from 'path';
+import { dirname, join } from 'path';
 import { mkdtemp } from 'fs/promises';
 import { tmpdir } from 'os';
+import { fileURLToPath } from 'url';
 import { exists, kitDataDir } from './fs-utils.js';
 import { status } from './install.js';
+import { isWindows } from './platform.js';
 
 function nodeMajor() {
   return Number.parseInt(process.versions.node.split('.')[0], 10);
@@ -28,8 +30,8 @@ export async function runDoctor(options = {}) {
     `version=${stat.claudeVersion || 'unknown'}; unsupported=${(stat.claudeUnsupportedKitEvents || []).join(', ') || 'none'}`
   );
   add('project-templates', 'project templates current', stat.project.managedFilesCurrent, stat.project.statePath);
-  add('codex-command', 'codex command available', spawnSync('codex', ['--version'], { encoding: 'utf8' }).status === 0, 'codex --version');
-  add('claude-command', 'claude command available', spawnSync('claude', ['--version'], { encoding: 'utf8' }).status === 0, 'claude --version');
+  add('codex-command', 'codex command available', commandVersionAvailable('codex'), 'codex --version');
+  add('claude-command', 'claude command available', commandVersionAvailable('claude'), 'claude --version');
   add('state-writable', 'state directory writable', await canWrite(join(kitDataDir(), '.doctor')), kitDataDir());
   add('docs', 'docs present', await docsPresent(), 'README.md and docs/');
   add('sample-hook', 'sample hook roundtrip', await sampleHookRoundtrip(stat.binPath), 'UserPromptSubmit fixture');
@@ -38,8 +40,17 @@ export async function runDoctor(options = {}) {
   return { ok: allOk, checks, workspace: stat.workspace, status: stat };
 }
 
+function commandVersionAvailable(command) {
+  const result = spawnSync(command, ['--version'], {
+    encoding: 'utf8',
+    shell: isWindows(),
+    timeout: 10000,
+  });
+  return result.status === 0;
+}
+
 async function docsPresent() {
-  const root = new URL('..', import.meta.url).pathname;
+  const root = dirname(dirname(fileURLToPath(import.meta.url)));
   return (await exists(join(root, 'README.md'))) &&
     (await exists(join(root, 'docs', 'concepts.md'))) &&
     (await exists(join(root, 'docs', 'security.md')));
@@ -105,17 +116,22 @@ function failed(result, id) {
 
 function doctorRemediation(result) {
   const workspace = result.workspace || process.cwd();
+  const windows = isWindows({ platform: result.status?.platform });
   const suggestions = [];
   if (failed(result, 'install-source')) {
     suggestions.push(`normal install: npm install -g llm-wiki-kit@latest && llm-wiki install --workspace ${workspace} --profile standard`);
-    suggestions.push(`source checkout development: ./install.sh --workspace ${workspace} --profile standard`);
+    suggestions.push(windows
+      ? `source checkout development: node bin\\llm-wiki.js install --workspace ${workspace} --profile standard`
+      : `source checkout development: ./install.sh --workspace ${workspace} --profile standard`);
   }
   if (failed(result, 'command-path')) {
     const local = result.status?.localBin;
-    if (result.status?.installSource === 'npm' && local?.exists && local.managed) {
+    if (!windows && result.status?.installSource === 'npm' && local?.exists && local.managed) {
       suggestions.push(`remove stale managed local shim if it still shadows npm: rm -f ${local.path} && hash -r`);
     }
-    suggestions.push(`reconnect command and hooks: llm-wiki install --workspace ${workspace} --profile standard`);
+    suggestions.push(windows
+      ? `reinstall npm shim and hooks: npm install -g llm-wiki-kit@latest && llm-wiki install --workspace ${workspace} --profile standard`
+      : `reconnect command and hooks: llm-wiki install --workspace ${workspace} --profile standard`);
   }
   if (failed(result, 'codex-hook') || failed(result, 'claude-hook') || failed(result, 'claude-settings-compatible')) {
     suggestions.push(`install hooks: llm-wiki install --workspace ${workspace} --profile standard, then restart Codex/Claude Code sessions`);

package/src/fs-utils.js

@@ -14,6 +14,7 @@ import {
 } from 'fs/promises';
 import { basename, dirname, join, parse, resolve } from 'path';
 import { PROJECT_MARKERS } from './constants.js';
+import { cacheHomeRelative, dataHomeRelative, isWindows } from './platform.js';
 import { normalizeForStorage } from './redaction.js';
 
 export function homeDir() {
@@ -21,13 +22,23 @@ export function homeDir() {
 }
 
 export function dataHome() {
+  if (isWindows() && process.env.LOCALAPPDATA) return process.env.LOCALAPPDATA;
   return process.env.XDG_DATA_HOME || join(homeDir(), '.local', 'share');
 }
 
 export function cacheHome() {
+  if (isWindows() && process.env.LOCALAPPDATA) return join(process.env.LOCALAPPDATA, 'llm-wiki-kit', 'cache');
   return process.env.XDG_CACHE_HOME || join(homeDir(), '.cache');
 }
 
+export function defaultDataHome(options = {}) {
+  return join(homeDir(), dataHomeRelative(options));
+}
+
+export function defaultCacheHome(options = {}) {
+  return join(homeDir(), cacheHomeRelative(options));
+}
+
 export function kitDataDir() {
   return join(dataHome(), 'llm-wiki-kit');
 }

package/src/install.js

@@ -1,50 +1,26 @@
-import { realpathSync } from 'fs';
 import { chmod, lstat, readlink, unlink } from 'fs/promises';
-import { spawnSync } from 'child_process';
 import { join, resolve } from 'path';
 import { CODEX_EVENTS, KIT_NAME } from './constants.js';
 import { detectClaudeVersion, supportedClaudeEvents } from './claude-compat.js';
 import { backupFile, exists, homeDir, readJson, safeSymlink, writeJson } from './fs-utils.js';
 import { maintenanceSummary } from './maintenance.js';
+import {
+  commandForNodeScript,
+  commandMatchesRuntime,
+  commandPaths as findCommandPaths,
+  inspectCommandPath,
+  isWindows,
+  realpathOrOriginal,
+  samePath,
+  sameResolvedPath,
+} from './platform.js';
 import { inspectProjectState } from './project-state.js';
 import { bootstrapProject } from './project.js';
 import { recordProject } from './projects.js';
 import { binPath, detectInstallSource, packageRoot, runtimeVersion } from './version.js';
 
-function shellQuote(value) {
-  return `"${String(value).replace(/(["\\$`])/g, '\\$1')}"`;
-}
-
-export function hookCommand(provider, eventName) {
-  return `${shellQuote(process.execPath)} ${shellQuote(binPath)} hook ${provider} ${eventName}`;
-}
-
-function llmWikiCommandPaths() {
-  const result = spawnSync('sh', ['-lc', 'which -a llm-wiki 2>/dev/null || true'], {
-    encoding: 'utf8',
-  });
-  if (result.error) return [];
-  return [...new Set(result.stdout.split(/\r?\n/).map((line) => line.trim()).filter(Boolean))];
-}
-
-function realpathOrOriginal(path) {
-  if (!path) return null;
-  try {
-    return realpathSync(path);
-  } catch {
-    return path;
-  }
-}
-
-function sameResolvedPath(left, right) {
-  const resolvedLeft = realpathOrOriginal(left);
-  const resolvedRight = realpathOrOriginal(right);
-  return Boolean(resolvedLeft && resolvedRight && resolvedLeft === resolvedRight);
-}
-
-function samePath(left, right) {
-  if (!left || !right) return false;
-  return resolve(left) === resolve(right);
+export function hookCommand(provider, eventName, options = {}) {
+  return commandForNodeScript(binPath, ['hook', provider, eventName], options);
 }
 
 function isKitPath(path) {
@@ -52,8 +28,12 @@ function isKitPath(path) {
 }
 
 function isKitHookEntry(entry) {
-  const serialized = JSON.stringify(entry || {});
-  return serialized.includes(KIT_NAME) || serialized.includes(binPath) || serialized.includes('/llm-wiki-kit/');
+  const serialized = normalizeHookPathText(JSON.stringify(entry || {}));
+  return serialized.includes(KIT_NAME) || serialized.includes(normalizeHookPathText(binPath)) || serialized.includes('/llm-wiki-kit/');
+}
+
+function normalizeHookPathText(value) {
+  return String(value || '').replace(/\\\\/g, '/').replace(/\\/g, '/');
 }
 
 async function inspectLocalBin(localBinPath) {
@@ -85,7 +65,7 @@ async function inspectLocalBin(localBinPath) {
 }
 
 async function reconcileLocalBin(localBinPath) {
-  const commandPathsBefore = llmWikiCommandPaths();
+  const commandPathsBefore = await findCommandPaths('llm-wiki');
   const localBefore = await inspectLocalBin(localBinPath);
   const alternateRuntimeCommand = commandPathsBefore.some((path) => (
     !samePath(path, localBinPath) && sameResolvedPath(path, binPath)
@@ -114,7 +94,7 @@ async function reconcileLocalBin(localBinPath) {
     await safeSymlink(binPath, localBinPath);
   }
 
-  const commandPathsAfter = llmWikiCommandPaths();
+  const commandPathsAfter = await findCommandPaths('llm-wiki');
   const localAfter = await inspectLocalBin(localBinPath);
   return {
     ...localAfter,
@@ -126,6 +106,23 @@ async function reconcileLocalBin(localBinPath) {
   };
 }
 
+async function reconcileWindowsCommand() {
+  const commandPathsBefore = await findCommandPaths('llm-wiki', { platform: 'win32' });
+  const commandPath = commandPathsBefore[0] || null;
+  const command = await inspectCommandPath(commandPath, binPath, {
+    platform: 'win32',
+    installSource: detectInstallSource(),
+  });
+  return {
+    ...command,
+    action: command.matchesRuntime ? 'skipped-windows-npm-shim-available' : 'skipped-windows-no-local-shim',
+    alternateRuntimeCommand: command.matchesRuntime,
+    commandPathsBefore,
+    commandPathsAfter: commandPathsBefore,
+    commandPath,
+  };
+}
+
 function addHook(hooks, eventName, command, options = {}) {
   hooks[eventName] = Array.isArray(hooks[eventName]) ? hooks[eventName] : [];
   const already = hooks[eventName].some((entry) => (
@@ -142,6 +139,7 @@ function addHook(hooks, eventName, command, options = {}) {
       },
     ],
   };
+  if (options.commandWindows) entry.hooks[0].commandWindows = options.commandWindows;
   if (options.matcher) entry.matcher = options.matcher;
   hooks[eventName].push(entry);
   return true;
@@ -188,12 +186,23 @@ function unsupportedKitClaudeEvents(hooks, supportedEvents) {
     .sort();
 }
 
+function hookTextIncludes(text, value) {
+  return normalizeHookPathText(text).includes(normalizeHookPathText(value));
+}
+
+function hookEventIncludesBin(entries) {
+  return hookTextIncludes(JSON.stringify(entries || {}), binPath);
+}
+
 export async function install(options = {}) {
   const workspace = resolve(options.workspace || process.cwd());
   await chmod(binPath, 0o755).catch(() => {});
-  const localBin = join(homeDir(), '.local', 'bin');
-  const localBinPath = join(localBin, 'llm-wiki');
-  const localBinResult = await reconcileLocalBin(localBinPath);
+  const platform = options.platform || process.platform;
+  const localBin = isWindows({ platform }) ? null : join(homeDir(), '.local', 'bin');
+  const localBinPath = localBin ? join(localBin, 'llm-wiki') : null;
+  const localBinResult = isWindows({ platform })
+    ? await reconcileWindowsCommand()
+    : await reconcileLocalBin(localBinPath);
   if (!options.noProject) {
     await bootstrapProject(workspace, { profile: options.profile || 'standard', recordState: true });
     await recordProject(workspace, 'install');
@@ -213,7 +222,9 @@ export async function install(options = {}) {
     }
     for (const eventName of CODEX_EVENTS) {
       const matcher = eventName === 'SessionStart' ? 'startup|resume|clear' : undefined;
-      if (addHook(codex.hooks, eventName, hookCommand('codex', eventName), { matcher })) {
+      const command = hookCommand('codex', eventName, { platform });
+      const commandWindows = isWindows({ platform }) ? hookCommand('codex', eventName, { platform: 'win32' }) : undefined;
+      if (addHook(codex.hooks, eventName, command, { matcher, commandWindows })) {
         codexChanged = true;
         changed.push(`codex:${eventName}`);
       }
@@ -241,7 +252,7 @@ export async function install(options = {}) {
     }
     for (const eventName of claudeEvents) {
       const matcher = eventName === 'SessionStart' ? 'startup|resume|clear' : undefined;
-      if (addHook(claude.hooks, eventName, hookCommand('claude', eventName), { matcher })) {
+      if (addHook(claude.hooks, eventName, hookCommand('claude', eventName, { platform }), { matcher })) {
         claudeChanged = true;
         changed.push(`claude:${eventName}`);
       }
@@ -294,31 +305,39 @@ export async function uninstall(options = {}) {
 
 export async function status(options = {}) {
   const workspace = resolve(options.workspace || process.cwd());
+  const platform = options.platform || process.platform;
   const codexHooksPath = join(homeDir(), '.codex', 'hooks.json');
   const claudeSettingsPath = join(homeDir(), '.claude', 'settings.json');
   const codex = await readJson(codexHooksPath, {});
   const claude = await readJson(claudeSettingsPath, {});
   const claudeDetection = detectClaudeVersion();
   const claudeEvents = supportedClaudeEvents(claudeDetection);
-  const claudeMissingEvents = claudeEvents.filter((eventName) => !JSON.stringify(claude.hooks?.[eventName] || []).includes(binPath));
+  const claudeMissingEvents = claudeEvents.filter((eventName) => !hookEventIncludesBin(claude.hooks?.[eventName] || []));
   const claudeUnsupportedKitEvents = unsupportedKitClaudeEvents(claude.hooks || {}, claudeEvents);
-  const codexInstalled = JSON.stringify(codex.hooks || {}).includes(binPath);
+  const codexInstalled = hookEventIncludesBin(codex.hooks || {});
   const claudeInstalled = claudeMissingEvents.length === 0 && claudeUnsupportedKitEvents.length === 0;
-  const commandPaths = llmWikiCommandPaths();
-  const commandPath = commandPaths[0] || null;
+  const discoveredCommandPaths = await findCommandPaths('llm-wiki', { platform });
+  const commandPath = discoveredCommandPaths[0] || null;
   const resolvedCommandPath = realpathOrOriginal(commandPath);
   const resolvedBinPath = realpathOrOriginal(binPath);
-  const localBinPath = join(homeDir(), '.local', 'bin', 'llm-wiki');
-  const localBin = await inspectLocalBin(localBinPath);
+  const localBinPath = isWindows({ platform }) ? null : join(homeDir(), '.local', 'bin', 'llm-wiki');
+  const localBin = localBinPath
+    ? await inspectLocalBin(localBinPath)
+    : await inspectCommandPath(commandPath, binPath, { platform, installSource: detectInstallSource() });
+  const commandMatches = await commandMatchesRuntime(commandPath, binPath, {
+    platform,
+    installSource: detectInstallSource(),
+  });
   return {
     workspace,
+    platform,
     runtimeVersion: runtimeVersion(),
     packageRoot,
     installSource: detectInstallSource(),
     binPath,
     commandPath,
-    commandPaths,
-    commandMatchesRuntime: Boolean(resolvedCommandPath && resolvedBinPath && resolvedCommandPath === resolvedBinPath),
+    commandPaths: discoveredCommandPaths,
+    commandMatchesRuntime: Boolean(commandMatches || (resolvedCommandPath && resolvedBinPath && resolvedCommandPath === resolvedBinPath)),
     localBin,
     codexInstalled,
     claudeInstalled,

package/src/platform.js

@@ -0,0 +1,178 @@
+import { realpathSync } from 'fs';
+import { access, lstat, readFile } from 'fs/promises';
+import { constants as fsConstants } from 'fs';
+import { delimiter, dirname, extname, join, resolve } from 'path';
+import { packageName, packageRoot } from './version.js';
+
+export function runtimePlatform(options = {}) {
+  return options.platform || process.platform;
+}
+
+export function isWindows(options = {}) {
+  return runtimePlatform(options) === 'win32';
+}
+
+export function pathDelimiter(options = {}) {
+  return isWindows(options) ? ';' : delimiter;
+}
+
+export function pathEnvValue(env = process.env, options = {}) {
+  if (!isWindows(options)) return env.PATH || '';
+  const key = Object.keys(env).find((name) => name.toLowerCase() === 'path');
+  return key ? env[key] || '' : env.PATH || '';
+}
+
+export function dataHomeRelative(options = {}) {
+  return isWindows(options)
+    ? join('AppData', 'Local')
+    : join('.local', 'share');
+}
+
+export function cacheHomeRelative(options = {}) {
+  return isWindows(options)
+    ? join('AppData', 'Local', 'llm-wiki-kit', 'cache')
+    : '.cache';
+}
+
+export function commandQuote(value, options = {}) {
+  return isWindows(options)
+    ? `"${String(value).replace(/"/g, '""')}"`
+    : `"${String(value).replace(/(["\\$`])/g, '\\$1')}"`;
+}
+
+export function commandForNodeScript(scriptPath, args = [], options = {}) {
+  if (!isWindows(options)) {
+    return [commandQuote(process.execPath, options), commandQuote(scriptPath, options), ...args].join(' ');
+  }
+  return [process.execPath, scriptPath, ...args]
+    .map((part) => commandQuote(part, options))
+    .join(' ');
+}
+
+export function realpathOrOriginal(path) {
+  if (!path) return null;
+  try {
+    return realpathSync(path);
+  } catch {
+    return path;
+  }
+}
+
+export function sameResolvedPath(left, right) {
+  const resolvedLeft = realpathOrOriginal(left);
+  const resolvedRight = realpathOrOriginal(right);
+  return Boolean(resolvedLeft && resolvedRight && resolvedLeft === resolvedRight);
+}
+
+export function samePath(left, right) {
+  if (!left || !right) return false;
+  return resolve(left) === resolve(right);
+}
+
+function unique(values) {
+  return [...new Set(values.filter(Boolean))];
+}
+
+function windowsExtensions(env = process.env) {
+  return unique((env.PATHEXT || '.COM;.EXE;.BAT;.CMD;.PS1')
+    .split(';')
+    .map((part) => part.trim())
+    .filter(Boolean)
+    .flatMap((part) => [part, part.toLowerCase(), part.toUpperCase()]));
+}
+
+function commandCandidates(dir, command, options = {}) {
+  const direct = join(dir, command);
+  if (!isWindows(options) || extname(command)) return [direct];
+  return [direct, ...windowsExtensions(options.env).map((ext) => join(dir, `${command}${ext}`))];
+}
+
+async function commandFileExists(path, options = {}) {
+  try {
+    await access(path, isWindows(options) ? fsConstants.F_OK : fsConstants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function commandPaths(command, options = {}) {
+  const env = options.env || process.env;
+  const pathValue = pathEnvValue(env, options);
+  const paths = [];
+  for (const dir of pathValue.split(pathDelimiter(options)).filter(Boolean)) {
+    for (const candidate of commandCandidates(dir, command, { ...options, env })) {
+      if (await commandFileExists(candidate, options)) paths.push(candidate);
+    }
+  }
+  return unique(paths);
+}
+
+function normalizePathText(value) {
+  return String(value || '').replace(/\\/g, '/').toLowerCase();
+}
+
+async function commandShimReferencesRuntime(commandPath, binPath, options = {}) {
+  if (!isWindows(options) || !commandPath) return false;
+  const extension = extname(commandPath).toLowerCase();
+  if (!['', '.cmd', '.bat', '.ps1'].includes(extension)) return false;
+  let content = '';
+  try {
+    content = await readFile(commandPath, 'utf8');
+  } catch {
+    return false;
+  }
+  const normalized = normalizePathText(content);
+  const normalizedBin = normalizePathText(binPath);
+  if (normalized.includes(normalizedBin)) return true;
+  if (options.installSource === 'npm') {
+    const commandDirPackageRoot = join(dirname(commandPath), 'node_modules', packageName());
+    return sameResolvedPath(commandDirPackageRoot, packageRoot) &&
+      normalized.includes(`node_modules/${packageName()}/bin/llm-wiki.js`);
+  }
+  return false;
+}
+
+export async function commandMatchesRuntime(commandPath, binPath, options = {}) {
+  if (!commandPath || !binPath) return false;
+  if (sameResolvedPath(commandPath, binPath)) return true;
+  return commandShimReferencesRuntime(commandPath, binPath, options);
+}
+
+export async function inspectCommandPath(commandPath, binPath, options = {}) {
+  if (!commandPath) {
+    return {
+      path: null,
+      exists: false,
+      symlink: false,
+      target: null,
+      resolved: null,
+      managed: false,
+      matchesRuntime: false,
+    };
+  }
+  try {
+    const stat = await lstat(commandPath);
+    const resolved = realpathOrOriginal(commandPath);
+    const matchesRuntime = await commandMatchesRuntime(commandPath, binPath, options);
+    return {
+      path: commandPath,
+      exists: true,
+      symlink: stat.isSymbolicLink(),
+      target: null,
+      resolved,
+      managed: matchesRuntime,
+      matchesRuntime,
+    };
+  } catch {
+    return {
+      path: commandPath,
+      exists: false,
+      symlink: false,
+      target: null,
+      resolved: null,
+      managed: false,
+      matchesRuntime: false,
+    };
+  }
+}

package/src/update-notice.js

@@ -1,6 +1,7 @@
 import { spawnSync } from 'child_process';
 import { join, resolve } from 'path';
 import { cacheHome, readJson, writeJson } from './fs-utils.js';
+import { isWindows } from './platform.js';
 import { commandForProject } from './projects.js';
 import { compareVersions, parseRegistryVersion } from './update.js';
 import { detectInstallSource, packageName, runtimeVersion } from './version.js';
@@ -62,6 +63,7 @@ function trimDetail(value) {
 function checkRegistry(target) {
   const result = spawnSync(npmCommand(), ['view', `${packageName()}@${target}`, 'version'], {
     encoding: 'utf8',
+    shell: isWindows(),
     timeout: timeoutMs(),
   });
   if (result.status !== 0 || result.error) {

package/src/update.js

@@ -3,6 +3,7 @@ import { join, resolve } from 'path';
 import { exists } from './fs-utils.js';
 import { appendWikiLog } from './project.js';
 import { install } from './install.js';
+import { isWindows } from './platform.js';
 import { applyProjectTemplateUpdate, inspectProjectState } from './project-state.js';
 import { knownProjectRoots, recordProject } from './projects.js';
 import { binPath, detectInstallSource, packageName, runtimeVersion } from './version.js';
@@ -24,7 +25,8 @@ async function runCommand(command, args, options = {}) {
   const killGraceMs = options.killGraceMs || 2000;
   const label = options.label || commandLine(command, args);
   const startedAt = Date.now();
-  const detached = process.platform !== 'win32';
+  const windows = isWindows(options);
+  const detached = !windows;
   let stdout = '';
   let stderr = '';
   let settled = false;
@@ -67,6 +69,7 @@ async function runCommand(command, args, options = {}) {
       child = spawn(command, args, {
         detached,
         env: options.env || process.env,
+        shell: windows,
         stdio: ['ignore', 'pipe', 'pipe'],
       });
     } catch (error) {