fix: add install-time quick-start guidance

Author: ExceptionRegret

.memory/project-memory.md

@@ -19,8 +19,9 @@ Build an open-source deterministic security scanner that helps repository owners
 - npm manifest normalization now uses a valid `bin` path and passes `npm publish --dry-run`.
 - The public GitHub repository now exists at `https://github.com/ExceptionRegret/security-first-aid`.
 - The initial `main` branch commit has been pushed to GitHub.
-- The package is now published to npm as `security-first-aid@0.1.1`.
+- The package is now published to npm as `security-first-aid@0.1.2`.
 - Public execution through `npx security-first-aid@latest ...` has been verified, including the no-argument quick-start guide.
+- Global npm installs now print a post-install quick-start guide.
 - Release hardening now includes a Keep a Changelog file, release validation scripts, and a tag-driven GitHub Actions release workflow.
 - CLI no-argument and help-flag behavior now shows a real quick-start guide for npm and npx users.
 - Additional implemented rules now cover `pull_request_target` workflows and wildcard CORS in JSON config.

CHANGELOG.md

@@ -6,6 +6,12 @@ The format is based on Keep a Changelog, and this project adheres to Semantic Ve
 
 ## [Unreleased]
 
+## [0.1.2] - 2026-03-11
+
+### Added
+
+- Global npm installs now print a short post-install quick-start guide so users immediately see how to run the CLI.
+
 ## [0.1.1] - 2026-03-11
 
 ### Added

README.md

@@ -102,6 +102,8 @@ npm install -g security-first-aid
 sfa scan . --format terminal
 ```
 
+Global npm installs now print a short quick-start message after installation.
+
 If you just want the built-in guide:
 
 ```bash
@@ -198,7 +200,7 @@ npm pack
 Install that tarball globally:
 
 ```bash
-npm install -g ./security-first-aid-0.1.0.tgz
+npm install -g ./security-first-aid-0.1.2.tgz
 ```
 
 Then run:
@@ -227,7 +229,7 @@ Automated release path:
 1. update `package.json` to the target version
 2. add the matching release section to `CHANGELOG.md`
 3. commit the release changes
-4. push a tag like `v0.1.1`
+4. push a tag like `v0.1.2`
 
 The `Release` workflow will:
 
@@ -287,7 +289,7 @@ npx @your-org/security-first-aid@latest scan . --format terminal
 
 Current published version:
 
-- `security-first-aid@0.1.1`
+- `security-first-aid@0.1.2`
 
 ## Usage
 
@@ -511,7 +513,7 @@ npm link
 Or reinstall the tarball/global package:
 
 ```bash
-npm install -g ./security-first-aid-0.1.0.tgz
+npm install -g ./security-first-aid-0.1.2.tgz
 ```
 
 ### PowerShell blocks `sfa.ps1`
@@ -534,7 +536,7 @@ That only works after the package is published to npm. Before publishing, use on
 
 - `node ./src/cli/index.js ...`
 - `npm link` then `sfa ...`
-- `npm pack` then `npm install -g ./security-first-aid-0.1.0.tgz`
+- `npm pack` then `npm install -g ./security-first-aid-0.1.2.tgz`
 
 ## License
 

docs/reference/cli.md

@@ -16,6 +16,8 @@ sfa
 
 If you run `sfa` with no arguments, the CLI now prints a built-in quick-start guide instead of a minimal usage block.
 
+If you install the package globally from npm, the installer also prints a short post-install quick-start message.
+
 PowerShell note:
 
 - If PowerShell prefers a blocked `sfa.ps1` shim, run `sfa.cmd ...` or `cmd /c sfa ...`.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "security-first-aid",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Deterministic, local-first security scanner for repositories and CI/CD configuration.",
   "homepage": "https://github.com/ExceptionRegret/security-first-aid#readme",
   "type": "module",
@@ -17,6 +17,7 @@
   },
   "files": [
     "src",
+    "scripts/postinstall.mjs",
     "CHANGELOG.md",
     "README.md",
     "LICENSE"
@@ -25,6 +26,7 @@
     "sfa": "src/cli/index.js"
   },
   "scripts": {
+    "postinstall": "node scripts/postinstall.mjs",
     "test": "node --test --experimental-test-isolation=none",
     "check": "node --test --experimental-test-isolation=none && node scripts/smoke.mjs",
     "scan:fixture": "node ./src/cli/index.js scan ./tests/fixtures/insecure-service --format markdown",

scripts/postinstall.mjs

@@ -0,0 +1,26 @@
+const isGlobalInstall = process.env.npm_config_global === "true";
+const isCi = process.env.CI === "true";
+
+if (!isGlobalInstall || isCi) {
+  process.exit(0);
+}
+
+const lines = [
+  "",
+  "Security First Aid installed.",
+  "",
+  "Start here:",
+  "  sfa",
+  "  sfa scan . --format terminal",
+  "  sfa rules list --format json",
+  "",
+  "PowerShell note:",
+  "  If `sfa` is blocked by execution policy, use `sfa.cmd` or `cmd /c sfa`.",
+  "",
+  "Docs:",
+  "  README: https://github.com/ExceptionRegret/security-first-aid#readme",
+  "  npm:    https://www.npmjs.com/package/security-first-aid",
+  ""
+];
+
+process.stdout.write(`${lines.join("\n")}\n`);