From 0c16479c5d2a9883257a296f294bc89b5e538eb1 Mon Sep 17 00:00:00 2001
From: Vedant Madane <6527493+VedantMadane@users.noreply.github.com>
Date: Mon, 24 Aug 2026 03:38:21 +0530
Subject: [PATCH] fix: docs: Windows npm pack/shebang path notes + smoke script

- README.md: Windows npm pack/shebang notes
- scripts\windows-pack-smoke.js
- package.json: test:windows-pack

Fixes #8

Signed-off-by: Vedant Madane <6527493+VedantMadane@users.noreply.github.com>
---
 README.md                     |  9 +++++++++
 package.json                  |  5 +++--
 scripts/windows-pack-smoke.js | 16 ++++++++++++++++
 3 files changed, 28 insertions(+), 2 deletions(-)
 create mode 100644 scripts/windows-pack-smoke.js

diff --git a/README.md b/README.md
index e673284..568f87e 100644
--- a/README.md
+++ b/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.
+
diff --git a/package.json b/package.json
index 5a35e14..6252fb5 100644
--- a/package.json
+++ b/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",
diff --git a/scripts/windows-pack-smoke.js b/scripts/windows-pack-smoke.js
new file mode 100644
index 0000000..172c7ec
--- /dev/null
+++ b/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));