fix: handle EPERM on restricted directories, add quickstart to README

CHANGELOG.md

@@ -5,6 +5,17 @@ Versions follow [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v3.3.1 — 2026-05-16
+
+**Hardening + quickstart polish.**
+
+- Fixed `EPERM` crash when scanning directories with restricted permissions (Windows `WinSAT`, etc.) — `collectFiles` now skips unreadable directories and files instead of throwing
+- Added npm badge to root README
+- Added Quickstart section at top of root README: `npx code-warden init`, `report`, `hooks`
+- Added contributor note about `npx` local-package conflict in source checkouts
+
+---
+
 ## v3.3.0 — 2026-05-16
 
 **npm package + CLI quickstart.**

README.md

@@ -8,12 +8,34 @@
   <img src="https://img.shields.io/badge/license-MIT-yellow" alt="MIT License" />
   <img src="https://img.shields.io/badge/Claude%20Hooks-PreToolUse-purple" alt="Claude Code PreToolUse Hooks" />
   <img src="https://img.shields.io/badge/AI%20Governance-enforced-red" alt="AI Governance Enforced" />
+  <a href="https://www.npmjs.com/package/code-warden">
+    <img src="https://img.shields.io/npm/v/code-warden" alt="npm" />
+  </a>
 </p>
 
 <p align="center">
   <img src="logo/hero-banner.png" alt="Code-Warden — Portable AI Coding Governance Layer" width="100%" />
 </p>
 
+## Quickstart
+
+```bash
+npx code-warden init
+```
+
+Generate a governance report:
+
+```bash
+npx code-warden report
+```
+
+Enable hard hooks where supported:
+
+```bash
+npx code-warden hooks claude
+npx code-warden hooks codex
+```
+
 ## Who This Is For
 
 **Code-Warden is for when AI coding stops being autocomplete and starts being delegated work.**

code-warden/README.md

@@ -194,6 +194,12 @@ See [`CONFIGURE.md`](CONFIGURE.md) for team-size profiles and tuning rationale.
 | `references/operations.md` | Verification, source-control hygiene, dependency control |
 | `references/research-and-fit.md` | Live research gate, stack fit, product-shape guardrails |
 
+## Note for contributors
+
+> If testing `npx code-warden` from inside the Code-Warden source checkout,
+> npm may prefer the local package context. Test from a separate directory for
+> the same behavior users will see.
+
 ## Author
 
 Justin Davis — MIT License

code-warden/package.json

@@ -1,6 +1,6 @@
 {
   "name": "code-warden",
-  "version": "3.3.0",
+  "version": "3.3.1",
   "description": "Verifiable governance for AI-assisted development — checks, hooks, and evidence.",
   "main": "SKILL.md",
   "bin": {

code-warden/tools/lib/file-collection.js

@@ -30,10 +30,13 @@ const SKIP_EXTS = new Set([
  * @param {string[]} results - accumulator (mutated)
  */
 function collectFiles(dir, results) {
-  for (const entry of fs.readdirSync(dir)) {
+  let entries;
+  try { entries = fs.readdirSync(dir); } catch { return; }
+  for (const entry of entries) {
     if (SKIP_DIRS.has(entry)) continue;
     const full = path.join(dir, entry);
-    const stat = fs.statSync(full);
+    let stat;
+    try { stat = fs.statSync(full); } catch { continue; }
     if (stat.isDirectory()) {
       collectFiles(full, results);
     } else if (!SKIP_EXTS.has(path.extname(entry).toLowerCase())) {