@dev-pi2pie/word-counter 0.1.3 → 0.1.4

package/README.md

@@ -139,6 +139,33 @@ word-counter --path ./examples/test-case-multi-files-support --keep-progress
 
 Progress is transient by default, auto-disabled for single-input runs, and suppressed in `--format raw` and `--format json`.
 
+### Batch Concurrency (`--jobs`)
+
+Use `--jobs` to control batch concurrency:
+
+```bash
+word-counter --path ./examples/test-case-multi-files-support --jobs 1
+word-counter --path ./examples/test-case-multi-files-support --jobs 4
+```
+
+Quick policy:
+
+- no `--jobs` and `--jobs 1` are equivalent baseline behavior.
+- `--jobs 1`: async main-thread `load+count` baseline.
+- `--jobs > 1`: worker `load+count` with async fallback when workers are unavailable.
+- if requested `--jobs` exceeds host `suggestedMaxJobs` (from `--print-jobs-limit`), the CLI warns and runs with the suggested limit as a safety cap.
+- use `--quiet-warnings` to suppress non-fatal warning lines (for example jobs-limit advisory and worker-fallback warning).
+
+Inspect host jobs diagnostics:
+
+```bash
+word-counter --print-jobs-limit
+```
+
+`--print-jobs-limit` must be used alone (no other inputs or runtime flags).
+
+For full policy details, JSON parity expectations (`--misc`, `--total-of whitespace,words`), and benchmark standards, see [`docs/batch-jobs-usage-guide.md`](docs/batch-jobs-usage-guide.md).
+
 ### Stable Path Resolution Contract
 
 - Repeated `--path` values are accepted as mixed inputs (file + directory).
@@ -197,6 +224,8 @@ For additional usage details and troubleshooting, see [`docs/regex-usage-guide.m
 
 ### Debugging Diagnostics (`--debug`)
 
+Noise policy: default output shows errors + warnings; `--debug` enables diagnostics; `--verbose` enables per-item diagnostics; `--quiet-warnings` suppresses warnings.
+
 `--debug` remains the diagnostics gate and now defaults to `compact` event volume:
 
 - lifecycle/stage timing events
@@ -229,7 +258,7 @@ word-counter --path ./examples/test-case-multi-files-support --debug --debug-rep
 word-counter --path ./examples/test-case-multi-files-support --debug --debug-report ./logs/debug.jsonl --debug-tee
 ```
 
-Skip details stay debug-gated and can still be suppressed with `--quiet-skips`.
+Skip details stay debug-gated and can be suppressed with `--quiet-skips`.
 
 ## How It Works
 
@@ -468,8 +497,9 @@ Example (trimmed):
   "frontmatterType": "yaml",
   "total": 7,
   "items": [
-    { "name": "content", "source": "frontmatter", "result": { "total": 3 } },
-    { "name": "content", "source": "content", "result": { "total": 4 } }
+    { "name": "content", "source": "frontmatter", "result": { "total": 4 } },
+    { "name": "content", "source": "frontmatter", "result": { "total": 2 } },
+    { "name": "content", "source": "content", "result": { "total": 5 } }
   ]
 }
 ```
@@ -562,7 +592,7 @@ word-counter --include-whitespace "Hi\tthere\n"
 word-counter --misc "Hi\tthere\n"
 ```
 
-In the CLI, `--include-whitespace` implies with `--non-words` (same behavior as `--misc`). `--non-words` alone does not include whitespace. When enabled, whitespace counts appear under `nonWords.whitespace`, and `total = words + nonWords` (emoji + symbols + punctuation + whitespace). JSON output also includes top-level `counts` when `nonWords` is enabled. See `docs/schemas/whitespace-categories.md` for how whitespace is categorized.
+In the CLI, `--include-whitespace` implies `--non-words` (same behavior as `--misc`). `--non-words` alone does not include whitespace. When enabled, whitespace counts appear under `nonWords.whitespace`, and `total = words + nonWords` (emoji + symbols + punctuation + whitespace). JSON output also includes top-level `counts` when `nonWords` is enabled. See `docs/schemas/whitespace-categories.md` for how whitespace is categorized.
 
 Example JSON (trimmed):