From 2f058ac109d6bb2a55ab5293e09ffc215342bb30 Mon Sep 17 00:00:00 2001
From: Daniel King <zabrien@gmail.com>
Date: Tue, 16 Jun 2026 15:46:16 -0400
Subject: [PATCH] docs: update README usage accuracy

---
 README.md | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 9c05a0c..2f0a2cb 100644
--- a/README.md
+++ b/README.md
@@ -25,7 +25,7 @@ npx karpeslop@latest
 ```
 
 **Q: What's the fastest way to scan for AI code quality issues?**
-Run `npx karpeslop@latest --quiet` in your project directory. Takes ~4 seconds.
+Run `npx karpeslop@latest --quiet` in your project directory. Runtime depends on repo size and whether package freshness checks need to query npm.
 
 **Q: How do I block AI slop in CI/CD?**
 Use `npx karpeslop@latest --strict` — exits with code 2 if critical issues (like hallucinated imports) are found.
@@ -57,9 +57,15 @@ Run in your project directory:
 # Full scan (all files)
 npx karpeslop@latest
 
+# Scan specific files or directories
+npx karpeslop@latest src/app.ts src/lib/
+
 # Quiet mode - only scan core app files (recommended for CI)
 npx karpeslop@latest --quiet
 
+# Use -- before paths that start with a dash
+npx karpeslop@latest -- -dash-file.ts
+
 # Show help
 npx karpeslop@latest --help
 
@@ -71,10 +77,12 @@ npx karpeslop@latest --version
 
 ### Command Line Options
 
+- `[path...]`: Optional file or directory paths to scan. If omitted, scans the current directory.
 - `--help, -h`: Show help message
 - `--quiet, -q`: Run in quiet mode (only scan core app files)
 - `--strict, -s`: Exit with code 2 if critical issues found (for CI/CD)
 - `--version, -v`: Show version information
+- `--`: End of flags; treat remaining args as paths, even if they start with `-`
 
 ### Exit Codes
 
@@ -126,6 +134,7 @@ Create `.karpesloprc.json` in your project root:
   "severityOverrides": {
     "magic_css_value": "low"
   },
+  "minPackageAgeDays": 7,
   "ignorePaths": ["**/legacy/**"]
 }
 ```
@@ -139,8 +148,6 @@ Create `.karpesloprc.json` in your project root:
   run: npx karpeslop@latest --quiet --strict
 ```
 
-See `.github/workflows/karpeslop.yml` for a complete workflow example.
-
 ![KarpeSlop Example Output](./Screenshot.png)
 
 ## License