fix: docs: Windows npm pack/shebang path notes + smoke script

README.md

@@ -155,3 +155,12 @@ golden fixtures, determinism, parity, process gates). MIT.
 - [Changelog](CHANGELOG.md)
 - [GitHub Action usage](docs/github-action-usage.md)
 - [Example config](docs/examples/agentsmd.config.json)
+
+## Windows notes (`npm pack` / bin)
+
+On Windows, `npm pack` installs package bins via `.cmd` shims. A Unix shebang (`#!/usr/bin/env node`) in the bin entry is ignored by `cmd.exe` but honored under Git Bash, WSL, and when Node launches the file directly.
+
+- **Supported:** `npx <bin>`, `npm exec -- <bin>`, and the generated `.cmd` shim after `npm install -g` from the tarball.
+- **Limitation:** running the raw bin path as a shell script (`./bin/foo`) requires a Unix-like shell; use `node path/to/bin` or the npm shim instead.
+- **Process test:** lint/sync from the packed tarball should be invoked via `npm exec` / `npx` so path separators and shims match Windows.
+

package.json

@@ -1,7 +1,7 @@
 {
   "name": "@daichunghy/agentsmd",
   "version": "0.1.0-alpha.3",
-  "description": "One source of truth for AI agent instructions — linted, wired, scored.",
+  "description": "One source of truth for AI agent instructions \u2014 linted, wired, scored.",
   "license": "MIT",
   "author": "daichunghy",
   "publishConfig": {
@@ -37,7 +37,8 @@
     "test": "vitest run",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "prepublishOnly": "npm run build",
-    "verify": "npm run typecheck && npm run build && npm run build:action && npm run test"
+    "verify": "npm run typecheck && npm run build && npm run build:action && npm run test",
+    "test:windows-pack": "node scripts/windows-pack-smoke.js"
   },
   "keywords": [
     "agents-md",

scripts/windows-pack-smoke.js

@@ -0,0 +1,16 @@
+// Smoke: resolve package bin the way npm shims do (node + entry), path-safe on Windows.
+const path = require("path");
+const fs = require("fs");
+const pkg = require("../package.json");
+const bin = pkg.bin;
+const entry = typeof bin === "string" ? bin : bin[Object.keys(bin)[0]];
+const abs = path.join(__dirname, "..", entry);
+if (!fs.existsSync(abs)) {
+  console.error("missing bin", abs);
+  process.exit(1);
+}
+const head = fs.readFileSync(abs, "utf8").split(/\r?\n/, 1)[0];
+if (!head.startsWith("#!") && !abs.endsWith(".js")) {
+  console.warn("no shebang on", entry, "(ok on Windows via npm shim)");
+}
+console.log("windows-pack-smoke ok:", path.normalize(abs));