@holmes-lab/holmes-kit 0.1.10 → 0.1.12

package/CHANGELOG.md

@@ -4,6 +4,41 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+<!-- @implements A-SPEC-209 -->
+## [0.1.12] - 2026-08-23
+
+### Added
+- **Install Guide (`docs/install-guide.md`, shipped in the package)**: install paths organised by
+  account type and privileges — a decision table first, commands second — because the same wrong
+  command (`npm install -g` against a protected prefix) was run three times by a real adopter
+  before the right one. Troubleshooting is keyed to the exact error text npm prints (`EPERM mkdir`,
+  `notarget`, `better-sqlite3` build failures, `spawn sh ENOENT`), and each entry says why
+  elevation is the wrong fix.
+
+### Changed
+- **README Quickstart leads with the situation table**, and steps 2–3 use `npx holmes-kit …` —
+  the bare `holmes-kit` they previously showed only exists on PATH after a global install, which
+  is not the primary path.
+
+<!-- @implements A-SPEC-209 -->
+## [0.1.11] - 2026-08-23
+
+### Added
+- **`doctor` diagnoses the global npm prefix (REQ-243)**: after a Windows adopter hit `EPERM` on
+  `npm install -g` twice — once elevated — `doctor` now reads the npm global prefix, computes where
+  a global install would land (win32: `<prefix>\\node_modules`; POSIX: `<prefix>/lib/node_modules`),
+  and checks writability on the deepest existing ancestor, which is what decides the real mkdir's
+  fate. An unwritable prefix is a **WARN** naming the exact directory the install would die in, with
+  a user-space prefix prescription — never elevation, which npm's own error text suggests and which
+  would run better-sqlite3's install script with system privileges. An unreadable probe is a WARN
+  carrying the reason, never a silent pass. The check cannot FAIL: a red doctor would tell a user
+  with a healthy local install that the install is broken.
+
+### Unchanged
+- The `-g` EPERM itself is not fixable by any package: it occurs while npm creates the scope
+  directory, before a single package file is transferred. The supported regular-account path remains
+  the local install (`npm install --save-dev`), which touches no protected directory.
+
 <!-- @implements A-SPEC-209 -->
 ## [0.1.10] - 2026-08-23
 

package/README.md

@@ -51,58 +51,35 @@ Holmes-Kit prioritizes **CLI-based AI Coding Agents** where OS-level process hoo
 
 ## ⚡ Quickstart (3-Minute Setup)
 
-### 1. Install
-
-Install it into the project you want to govern. This is the path verified end to end — the
-wiring `init` writes uses absolute paths, so a local install works from any directory:
-
-```bash
-npm install --save-dev @holmes-lab/holmes-kit
-```
-
-<details>
-<summary>Prefer one install for many projects? (<code>npm install -g</code>)</summary>
-
-A global install works too, but **do not elevate to get it**. Where npm puts global packages is
-your npm configuration, not ours — and on Windows it often points inside the Node.js installation
-directory:
-
-```text
-npm error code EPERM
-npm error path C:\Program Files\nodejs\node_modules\@holmes-lab
-```
-
-Running the install as Administrator would "fix" that by executing this package's native
-dependency install scripts with system privileges. Point npm at a user-writable prefix instead:
-
-```powershell
-npm config set prefix "$env:APPDATA\npm"          # Windows
-# then ensure %APPDATA%\npm is on PATH
-```
-```bash
-npm config set prefix "$HOME/.npm-global"          # macOS / Linux
-export PATH="$HOME/.npm-global/bin:$PATH"
-```
-
-A Node version manager (`nvm`, `fnm`, `volta`) does the same thing by keeping the whole
-toolchain under your home directory.
-</details>
-
-**Prerequisites** — Node.js `>= 20.0.0`, plus a native binary for two kinds of dependency:
-
-| Dependency | How the binary arrives |
-|---|---|
-| 8 tree-sitter grammars | Prebuilt binaries ship inside the packages (`darwin-arm64`, `darwin-x64`, `linux-x64`, `win32-x64`) — nothing is compiled |
-| `better-sqlite3` | Downloaded at install time by `prebuild-install`, **falling back to compiling** if no prebuild matches your platform and Node ABI |
-
-Only the second can require a toolchain. If it has to compile, you need a C++ build environment:
-Xcode Command Line Tools on macOS, Visual Studio Build Tools on Windows, or
-`apk add --no-cache python3 make g++` on Alpine.
+### 1. Install — find your row first
+
+The same wrong command was run three times by a real adopter before the right one; a table beats
+prose read top-to-bottom.
+
+| Which situation are you in? | Privileges | Command |
+|---|---|---|
+| **Using it in one project** (most people) | none | `npm install --save-dev @holmes-lab/holmes-kit` |
+| Company-managed PC / restricted account | none | same — no system directory is touched |
+| CI / container | none | same, plus `--prefer-online` right after a release |
+| CLI across many projects (`-g`) | depends | run `npm config get prefix` first — see below |
+
+**Before `npm install -g`**: if `npm config get prefix` names a protected directory
+(`C:\Program Files\nodejs`, `/usr/local`), `-g` dies with `EPERM` **before any package file
+arrives** — no package version can fix that, and elevation is the wrong fix (it runs native
+install scripts with system privileges, and it did not even work in the reported case). Move the
+prefix to user space instead — one-time setup, exact commands in the
+**[Install Guide](docs/install-guide.md)**, along with troubleshooting keyed to the exact error
+text (`EPERM mkdir`, `notarget`, `better-sqlite3` build failures).
+
+**Prerequisites** — Node.js `>= 20.0.0`. The 8 tree-sitter grammars ship prebuilt binaries for
+macOS/Linux/Windows and compile nothing; `better-sqlite3` downloads a prebuild at install time,
+falling back to compiling — only that fallback needs a C++ toolchain (VS Build Tools / Xcode CLT /
+`apk add python3 make g++`).
 
 ### 2. Initialize in Your Project
 ```bash
 cd /path/to/your/project
-holmes-kit init
+npx holmes-kit init      # drop the npx prefix if you installed with -g
 ```
 *An interactive prompt will ask which AI agent harnesses to wire into your project:*
 ```text
@@ -114,7 +91,7 @@ holmes-kit init
 
 ### 3. Verify Health
 ```bash
-holmes-kit doctor
+npx holmes-kit doctor
 ```
 *If everything is green, your project is governed and ready for AI pair-programming!*
 

package/dist/.build-id

@@ -1 +1 @@
-a400784-mt568ove
+b820c0b-mt57zbc7

package/dist/holmes/cli/doctor.d.ts

@@ -28,6 +28,45 @@ export interface DoctorOptions {
  * real key-related failure.
  */
 export declare const STRIPPED_FOR_PROBE: readonly ["HOLMES_APPROVAL", "HOLMES_SPECS"];
+/**
+ * Where a global install actually lands for a given prefix.
+ *
+ * @implements A-SPEC-243
+ * The shapes differ, not just the separators: win32 puts global modules directly under the prefix,
+ * POSIX puts them under `lib/`. The win32 result is the exact directory the reported EPERM died in
+ * — npm mkdir-ing `@holmes-lab` inside `C:\Program Files\nodejs\node_modules`, before a single
+ * package file was transferred. That is why no package content can fix that failure, and why the
+ * only lever left is naming the condition here.
+ */
+export declare function globalInstallDir(prefix: string, platform: string): string;
+/** What the global-prefix probe saw. `unreadable` carries WHY npm could not be consulted. */
+export interface PrefixProbe {
+    prefix?: unknown;
+    dir?: string;
+    writable?: boolean;
+    platform?: string;
+    unreadable?: string;
+}
+/**
+ * Judge the global prefix. Pure — the probing lives with the caller.
+ *
+ * @implements A-SPEC-243
+ * Never FAIL: the `-g` path is optional, and a red doctor tells a user with a healthy local
+ * install that the install is broken — a false signal that comes back as distrust of the check.
+ *
+ * Never elevation: npm's own EPERM text ends with "try running the command again as
+ * root/Administrator", and pointing the opposite way is this check's reason to exist — elevation
+ * runs better-sqlite3's install script (`prebuild-install || node-gyp rebuild`) with system
+ * privileges. The prescription is a user-space prefix, per platform.
+ *
+ * An unreadable probe is a WARN carrying the reason, not a silent pass: a silent pass reads as
+ * "checked, no problem", which translates what was not seen into a verdict.
+ */
+export declare function prefixVerdict(input: PrefixProbe): {
+    level: Level;
+    detail: string;
+    fix?: string;
+};
 /** The parent environment minus the variables that legitimately change a gate decision. Pure. */
 export declare function probeEnv(parent: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
 /** Seam for the gate probe's child process. Default is a real `spawnSync`; tests inject a fake. */

package/dist/holmes/cli/doctor.js

@@ -34,6 +34,8 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.STRIPPED_FOR_PROBE = void 0;
+exports.globalInstallDir = globalInstallDir;
+exports.prefixVerdict = prefixVerdict;
 exports.probeEnv = probeEnv;
 exports.runDoctor = runDoctor;
 exports.formatChecks = formatChecks;
@@ -63,6 +65,56 @@ const GRAMMARS = [
  * real key-related failure.
  */
 exports.STRIPPED_FOR_PROBE = ['HOLMES_APPROVAL', 'HOLMES_SPECS'];
+/**
+ * Where a global install actually lands for a given prefix.
+ *
+ * @implements A-SPEC-243
+ * The shapes differ, not just the separators: win32 puts global modules directly under the prefix,
+ * POSIX puts them under `lib/`. The win32 result is the exact directory the reported EPERM died in
+ * — npm mkdir-ing `@holmes-lab` inside `C:\Program Files\nodejs\node_modules`, before a single
+ * package file was transferred. That is why no package content can fix that failure, and why the
+ * only lever left is naming the condition here.
+ */
+function globalInstallDir(prefix, platform) {
+    return platform === 'win32'
+        ? `${prefix.replace(/[\\/]+$/, '')}\\node_modules`
+        : `${prefix.replace(/\/+$/, '')}/lib/node_modules`;
+}
+/**
+ * Judge the global prefix. Pure — the probing lives with the caller.
+ *
+ * @implements A-SPEC-243
+ * Never FAIL: the `-g` path is optional, and a red doctor tells a user with a healthy local
+ * install that the install is broken — a false signal that comes back as distrust of the check.
+ *
+ * Never elevation: npm's own EPERM text ends with "try running the command again as
+ * root/Administrator", and pointing the opposite way is this check's reason to exist — elevation
+ * runs better-sqlite3's install script (`prebuild-install || node-gyp rebuild`) with system
+ * privileges. The prescription is a user-space prefix, per platform.
+ *
+ * An unreadable probe is a WARN carrying the reason, not a silent pass: a silent pass reads as
+ * "checked, no problem", which translates what was not seen into a verdict.
+ */
+function prefixVerdict(input) {
+    const reason = input.unreadable ?? (typeof input.prefix !== 'string' || input.prefix === ''
+        ? `npm 이 돌려준 prefix 를 해석할 수 없습니다 (${String(input.prefix)})`
+        : undefined);
+    if (reason !== undefined) {
+        return { level: 'WARN', detail: `전역 prefix 를 판독하지 못했습니다 — ${reason}. 로컬 설치(--save-dev)는 이 판정과 무관하게 동작합니다.` };
+    }
+    const prefix = input.prefix;
+    if (input.writable) {
+        return { level: 'PASS', detail: `전역 prefix(${prefix})가 현재 계정으로 쓰기 가능합니다 — npm install -g 가 권한 문제 없이 동작합니다.` };
+    }
+    const fix = input.platform === 'win32'
+        ? 'npm config set prefix "%APPDATA%\\npm" 실행 후 %APPDATA%\\npm 을 PATH 에 추가하고 터미널을 다시 여세요. 로컬 설치(npm install --save-dev)는 이 설정 없이도 동작합니다.'
+        : 'npm config set prefix "$HOME/.npm-global" 실행 후 $HOME/.npm-global/bin 을 PATH 에 추가하세요. 로컬 설치(npm install --save-dev)는 이 설정 없이도 동작합니다.';
+    return {
+        level: 'WARN',
+        detail: `전역 prefix(${prefix})가 현재 계정으로 쓰기 불가입니다 — npm install -g 는 ${input.dir ?? ''} 에 디렉터리를 만들다 EPERM 으로 죽습니다. 패키지가 도착하기 전 단계라 어떤 패키지도 이를 고칠 수 없습니다.`,
+        fix,
+    };
+}
 /** The parent environment minus the variables that legitimately change a gate decision. Pure. */
 function probeEnv(parent) {
     const out = { ...parent };
@@ -451,6 +503,33 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
         catch { /* an unreadable settings file is `target wiring`'s business, not this check's */ }
     }
     add('gate blind spots', 'PASS', (0, blind_spots_1.blindSpotSummary)());
+    // @implements A-SPEC-243 — the writability of the deepest EXISTING ancestor is what decides the
+    // real mkdir's fate, since the scope directory being created does not exist yet.
+    {
+        let verdict;
+        try {
+            const prefix = (0, node_child_process_1.execFileSync)('npm', ['config', 'get', 'prefix'], { encoding: 'utf8' }).trim();
+            const dir = globalInstallDir(prefix, process.platform);
+            let probe = dir;
+            while (!fs.existsSync(probe)) {
+                const parent = path.dirname(probe);
+                if (parent === probe)
+                    break;
+                probe = parent;
+            }
+            let writable = false;
+            try {
+                fs.accessSync(probe, fs.constants.W_OK);
+                writable = true;
+            }
+            catch { /* not writable */ }
+            verdict = prefixVerdict({ prefix, dir, writable, platform: process.platform });
+        }
+        catch (e) {
+            verdict = prefixVerdict({ unreadable: e instanceof Error ? e.message.split('\n')[0] : String(e) });
+        }
+        add('global prefix', verdict.level, verdict.detail, verdict.fix);
+    }
     add('environment', 'PASS', present);
     if (extraChecks) {
         checks.push(...extraChecks);

package/docs/install-guide.md

@@ -0,0 +1,131 @@
+# Install Guide — by account type and permissions
+
+This guide exists because of a measured failure, not a hypothetical one: an adopter on Windows ran
+`npm install -g` three times — once from an elevated PowerShell — and hit the same `EPERM` every
+time, because their npm global prefix pointed inside `C:\Program Files\nodejs`. The local install
+worked on the first try. Find your row, run its one command.
+
+## Which situation are you in?
+
+| Situation | Privileges needed | Command |
+|---|---|---|
+| **Using it in one project** (most people) | none | `npm install --save-dev @holmes-lab/holmes-kit` then `npx holmes-kit init` |
+| Company-managed PC / restricted account | none | same as above — no system directory is touched |
+| CI / container | none | same as above, plus `--prefer-online` right after a release |
+| Want the CLI across many projects (`-g`) | depends on your prefix | **check first**: `npm config get prefix` ↓ |
+
+The local install is the path verified end to end, on macOS and Windows, against the public
+registry. The wiring `init` writes uses absolute paths, so nothing needs to be on `PATH`.
+
+## Before `npm install -g`: check your prefix
+
+```
+npm config get prefix
+```
+
+| Result looks like | Verdict |
+|---|---|
+| `%APPDATA%\npm`, `~/.npm-global`, `/opt/homebrew`, an nvm/fnm/volta directory | user-writable — `npm install -g @holmes-lab/holmes-kit` works as-is |
+| `C:\Program Files\nodejs`, `/usr/local` | protected — `-g` dies with `EPERM` **before any package file arrives**. Move the prefix (below). **Do not elevate.** |
+
+`npx holmes-kit doctor` (after a local install) runs this exact check for you — the
+`global prefix` line names the directory and the remedy.
+
+### Moving the prefix to user space — one-time setup
+
+Windows (PowerShell):
+
+```powershell
+npm config set prefix "$env:APPDATA\npm"
+[Environment]::SetEnvironmentVariable('Path', "$([Environment]::GetEnvironmentVariable('Path','User'));$env:APPDATA\npm", 'User')
+# open a NEW terminal, then:
+npm install -g @holmes-lab/holmes-kit
+```
+
+macOS / Linux:
+
+```bash
+npm config set prefix "$HOME/.npm-global"
+export PATH="$HOME/.npm-global/bin:$PATH"   # add to your shell profile too
+npm install -g @holmes-lab/holmes-kit
+```
+
+A Node version manager (`nvm`, `fnm`, `volta`) achieves the same by keeping the whole toolchain
+under your home directory.
+
+### Why elevation is the wrong fix
+
+npm's own error text ends with *"try running the command again as root/Administrator."* Do not
+follow it here, for two reasons:
+
+1. **It may not even work.** The reported failure recurred from an elevated PowerShell — antivirus
+   and Windows Controlled Folder Access block protected-folder writes regardless of elevation.
+2. **When it works, it is worse.** `better-sqlite3` declares
+   `install: prebuild-install || node-gyp rebuild` — under an elevated `-g`, that downloads and
+   executes, or invokes a compiler, **with system privileges**. Keeping installs in user space is
+   what contains a compromised dependency.
+
+## Troubleshooting, by the error you actually see
+
+### `EPERM … mkdir C:\Program Files\nodejs\node_modules\@holmes-lab`
+
+```
+npm error code EPERM
+npm error syscall mkdir
+npm error path C:\Program Files\nodejs\node_modules\@holmes-lab
+```
+
+Your global prefix is a protected directory. The failure happens while npm creates the scope
+folder — **before a single package file is transferred** — so no package version can fix it, and
+neither can this one. Either drop `-g` (the local install needs none of this) or move the prefix
+(one-time setup above).
+
+### `notarget No matching version found`
+
+```
+npm error code ETARGET
+npm error notarget No matching version found for @holmes-lab/holmes-kit@<version>
+```
+
+Your npm metadata cache predates the release — measured minutes after publishing 0.1.11, the
+registry already listed the version while a default-cache install still refused it. Add
+`--prefer-online`, or retry in a few minutes.
+
+### `better-sqlite3` fails to build
+
+The one dependency that may need a toolchain. The 8 tree-sitter grammars ship prebuilt binaries
+(`darwin-arm64`, `darwin-x64`, `linux-x64`, `win32-x64`) and compile nothing; `better-sqlite3`
+downloads a prebuild at install time and **falls back to compiling** when none matches your
+platform and Node ABI. If it compiles, you need:
+
+| Platform | Toolchain |
+|---|---|
+| Windows | Visual Studio Build Tools (C++ workload) |
+| macOS | Xcode Command Line Tools (`xcode-select --install`) |
+| Alpine | `apk add --no-cache python3 make g++` |
+
+### `spawn sh ENOENT` during a git-URL install
+
+`npm i -g git+ssh://…` is not a supported path: npm 11 clones the repository into its cache and
+runs `prepare` there without installing dependencies, so the build tooling is missing. Install
+from the registry or from a packed tarball.
+
+## Verify — the last step of every path
+
+```
+npx holmes-kit doctor        # local install
+holmes-kit doctor            # global install
+```
+
+Expect `10 pass, 1 warn, 0 fail` on a healthy install. The lines that matter most:
+
+- `global prefix` — whether `-g` would work on this machine, and the remedy if not
+- `tree-sitter grammars` / `better-sqlite3` — whether the native modules actually load
+
+## What we deliberately do NOT do
+
+| Idea | Why not |
+|---|---|
+| A `postinstall` script that prints guidance | Triggers npm 11's `allow-scripts` warning and forfeits this package's current property of running no install scripts at all |
+| Recommending `npx @holmes-lab/holmes-kit init` with no install | `init` writes wiring with absolute paths; under bare `npx` those point into the npx cache and break when it is pruned |
+| Fixing your npm prefix from inside the package | A package rewriting your npm configuration is exactly the supply-chain behaviour this guide warns about |

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "@implements A-SPEC-209",
   "name": "@holmes-lab/holmes-kit",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "Holmes-Kit — deterministic Agentic Software Engineering (ASE) harness with causal traceability (spec chain + D-CPG + RTM + phase guardrail)",
   "main": "dist/holmes/mcp/server.js",
   "types": "dist/holmes/mcp/server.d.ts",
@@ -13,6 +13,7 @@
     "bin/",
     "dist/",
     "playbooks/",
+    "docs/install-guide.md",
     "CHANGELOG.md"
   ],
   "engines": {