cov-loupe 3.0.0 → 4.0.0.pre

data/docs/user/CLI_USAGE.md

@@ -1,12 +1,13 @@
 # CLI Usage Guide
 
-[Back to main README](../README.md)
+[Back to main README](../index.md)
 
 Complete reference for using cov-loupe from the command line.
 
 > Docs use `clp` as a shortcut pointing at the demo fixture with partial coverage:
-> `alias clp='cov-loupe --root docs/fixtures/demo_project'`
+> `alias clp='cov-loupe -R docs/fixtures/demo_project'`  # -R = --root
 > Replace `clp` with `cov-loupe` to run commands against your own project.
+> The demo fixture is a small Rails-like project in `docs/fixtures/demo_project` with intentional coverage gaps for testing `--tracked-globs`.
 
 ## Table of Contents
 
@@ -67,29 +68,29 @@ Default sort order is descending (highest coverage first) so the lowest-coverage
 |---------|--------------------------|-------------------------------------------------------|
 | `-o`    | `--sort-order`           | Sort by coverage percentage (ascending or descending) |
 | `-g`    | `--tracked-globs`        | Filter to specific file patterns                      |
-| `-S`    | `--staleness`            | Staleness checking mode (off or error)                |
+| `-S`    | `--raise-on-stale`       | Raise error if coverage is stale (default false)      |
 | `-fJ`   | `--format pretty-json`   | Output as pretty-printed JSON                         |
 | `-fj`   | `--format json`          | Output as single-line JSON                            |
 | `-f y`  | `--format yaml`          | Output as YAML                                        |
-| `-f ap` | `--format awesome_print` | Output using AwesomePrint                             |
+| `-f ap` | `--format amazing_print` | Output using AmazingPrint                             |                             |
 
 **Output (table format):**
 ```
 ┌────────────────────────────────────────┬──────────┬───────────┬─────────┬───────┐
 │ File                                   │        % │   Covered │   Total │ Stale │
 ├────────────────────────────────────────┼──────────┼───────────┼─────────┼───────┤
-│ lib/payments/refund_service.rb         │   60.00% │         3 │       5 │       │
-│ app/controllers/orders_controller.rb   │   70.00% │         7 │      10 │       │
+│ app/models/user.rb                     │  100.00% │         6 │       6 │       │
+│ lib/api/client.rb                      │   88.89% │         8 │       9 │       │
+│ app/models/order.rb                    │   85.71% │         6 │       7 │       │
 │ lib/ops/jobs/report_job.rb             │   80.00% │         4 │       5 │       │
 │ lib/payments/processor.rb              │   80.00% │         4 │       5 │       │
-│ app/models/order.rb                    │   85.71% │         6 │       7 │       │
-│ lib/api/client.rb                      │   88.89% │         8 │       9 │       │
-│ app/models/user.rb                     │  100.00% │         6 │       6 │       │
+│ app/controllers/orders_controller.rb   │   70.00% │         7 │      10 │       │
+│ lib/payments/refund_service.rb         │   60.00% │         3 │       5 │       │
 └────────────────────────────────────────┴──────────┴───────────┴─────────┴───────┘
 Files: total 7, ok 7, stale 0
 ```
 
-**Stale indicators:** M (missing file), T (timestamp mismatch), L (line count mismatch)
+**Stale indicators:** missing (missing file), newer (timestamp mismatch), length_mismatch (line count mismatch), error (staleness check error)
 
 ### `summary <path>`
 
@@ -98,7 +99,7 @@ Show covered/total/percentage for a specific file.
 ```sh
 clp summary app/models/order.rb
 clp summary app/models/order.rb -fJ
-clp summary app/models/order.rb --source full
+clp summary app/models/order.rb -s full  # -s = --source
 ```
 
 **Arguments:**
@@ -111,12 +112,16 @@ clp summary app/models/order.rb --source full
 | `-fJ` | `--format pretty-json` | Output as pretty-printed JSON         |
 | `-fj` | `--format json`        | Output as single-line JSON            |
 | `-f y` | `--format yaml`        | Output as YAML                        |
-| `-f ap` | `--format awesome_print` | Output using AwesomePrint         |
+| `-f ap` | `--format amazing_print` | Output using AmazingPrint                             |         |
 | `-s`  | `--source MODE`  | Include source code (full or uncovered)    |
 
 **Output (default format):**
 ```
-  85.71%       6/7       app/models/order.rb
+┌───────────────────────┬──────────┬─────────┬───────┬───────┐
+│ File                  │        % │ Covered │ Total │ Stale │
+├───────────────────────┼──────────┼─────────┼───────┼───────┤
+│ app/models/order.rb   │   85.71% │       6 │     7 │       │
+└───────────────────────┴──────────┴─────────┴───────┴───────┘
 ```
 
 **Output (JSON format):**
@@ -128,7 +133,7 @@ clp summary app/models/order.rb --source full
     "total": 7,
     "percentage": 85.71
   },
-  "stale": false
+  "stale": "ok"
 }
 ```
 
@@ -138,8 +143,8 @@ Show uncovered line numbers for a specific file.
 
 ```sh
 clp uncovered app/controllers/orders_controller.rb
-clp uncovered app/controllers/orders_controller.rb --source uncovered
-clp uncovered app/controllers/orders_controller.rb --source uncovered --context-lines 3
+clp uncovered app/controllers/orders_controller.rb -s uncovered  # -s = --source
+clp uncovered app/controllers/orders_controller.rb -s uncovered -c 3  # -c = --context-lines
 ```
 
 **Arguments:**
@@ -147,16 +152,15 @@ clp uncovered app/controllers/orders_controller.rb --source uncovered --context-
 
 **Options:**
 
-| Short | Long                  | Description                                           |
-|-------|-----------------------|-------------------------------------------------------|
-| `-s`  | `--source uncovered`  | Show uncovered lines with context                     |
-| `-c`  | `--context-lines N`   | Lines of context around uncovered lines (default: 2)  |
-|       | `--color`             | Enable syntax coloring                                |
-|       | `--no-color`          | Disable syntax coloring                               |
-| `-fJ` | `--format pretty-json` | Output as pretty-printed JSON                        |
-| `-fj` | `--format json`        | Output as single-line JSON                          |
-| `-f y` | `--format yaml`        | Output as YAML                                      |
-| `-f ap` | `--format awesome_print` | Output using AwesomePrint                         |
+| Short   | Long                     | Description                                          |
+|---------|--------------------------|------------------------------------------------------|
+| `-s`    | `--source uncovered`     | Show uncovered lines with context                    |
+| `-c`    | `--context-lines N`      | Lines of context around uncovered lines (default: 2) |
+| `-C`    | `--color BOOLEAN`        | Enable (`true`)/disable (`false`) syntax coloring    |
+| `-fJ`   | `--format pretty-json`   | Output as pretty-printed JSON                        |
+| `-fj`   | `--format json`          | Output as single-line JSON                           |
+| `-f y`  | `--format yaml`          | Output as YAML                                       |
+| `-f ap` | `--format amazing_print` | Output using AmazingPrint                             |                            |
 
 **Output (default format):**
 ```
@@ -194,7 +198,7 @@ Show per-line coverage with hit counts.
 ```sh
 clp detailed app/models/order.rb
 clp detailed app/models/order.rb -fJ
-clp detailed app/models/order.rb --source full
+clp detailed app/models/order.rb -s full  # -s = --source
 ```
 
 **Arguments:**
@@ -207,21 +211,25 @@ clp detailed app/models/order.rb --source full
 | `-fJ`   | `--format pretty-json`   | Output as pretty-printed JSON |
 | `-fj`   | `--format json`          | Output as single-line JSON    |
 | `-f y`  | `--format yaml`          | Output as YAML                |
-| `-f ap` | `--format awesome_print` | Output using AwesomePrint     |
+| `-f ap` | `--format amazing_print` | Output using AmazingPrint                             |     |
 | `-s`    | `--source MODE`          | Include source code           |
 
 **Output (default format):**
 ```
 File: app/models/order.rb
-  Line    Hits  Covered
- -----    ----  -------
-     6       1    yes
-     7       1    yes
-     8       1    yes
-    11       1    yes
-    12       1    yes
-    15       1    yes
-    16       0     no
+Coverage: 6/7 lines (85.71%)
+
+┌──────┬──────┬─────────┐
+│ Line │ Hits │ Covered │
+├──────┼──────┼─────────┤
+│    6 │    1 │   yes   │
+│    7 │    1 │   yes   │
+│    8 │    1 │   yes   │
+│   11 │    1 │   yes   │
+│   12 │    1 │   yes   │
+│   15 │    1 │   yes   │
+│   16 │    0 │   no    │
+└──────┴──────┴─────────┘
 ```
 
 **Output (JSON format):**
@@ -242,7 +250,7 @@ File: app/models/order.rb
     "total": 7,
     "percentage": 85.71
   },
-  "stale": false
+  "stale": "ok"
 }
 ```
 
@@ -269,7 +277,7 @@ File: app/models/order.rb
 {
   "file": "app/models/order.rb",
   "lines": [null, null, null, null, null, 1, 1, 1, null, null, 1, 1, null, null, 1, 0, null, null, null, null],
-  "stale": false
+  "stale": "ok"
 }
 ```
 
@@ -290,22 +298,73 @@ clp -g "lib/ops/jobs/*.rb" totals  # -g = --tracked-globs
 
 **Output (default format):**
 ```
-Lines: total 47       covered 38       uncovered 9
-Average coverage:  80.85% across 7 files (ok: 7, stale: 0)
+Tracked globs:
+  - lib/**/*.rb
+  - app/**/*.rb
+  - src/**/*.rb
+
+Totals
+┌──────────┬───────┬─────────┬───────────┬────────┐
+│ Metric   │ Total │ Covered │ Uncovered │      % │
+├──────────┼───────┼─────────┼───────────┼────────┤
+│ Lines    │    47 │      38 │         9 │ 80.85% │
+│ Files    │     7 │       7 │         0 │        │
+└──────────┴───────┴─────────┴───────────┴────────┘
+
+File breakdown:
+  With coverage: 7 total, 7 ok, 0 stale
+    Stale: missing on disk = 0, newer than coverage = 0, line mismatch = 0, unreadable = 0
+  Without coverage: 0 total
+    Missing from coverage = 0, unreadable = 0, skipped (errors) = 0
+```
+
+**Tracked globs (shown when tracking is enabled):**
+```
+Tracked globs:
+  - lib/**/*.rb
+  - app/**/*.rb
 ```
 
 **Output (JSON format):**
 ```json
 {
-  "lines": { "total": 47, "covered": 38, "uncovered": 9 },
-  "percentage": 80.85,
-  "files": { "total": 7, "ok": 7, "stale": 0 }
+  "lines": { "total": 47, "covered": 38, "uncovered": 9, "percent_covered": 80.85 },
+  "tracking": { "enabled": true, "globs": ["lib/**/*.rb", "app/**/*.rb"] },
+  "files": {
+    "total": 7,
+    "with_coverage": {
+      "total": 7,
+      "ok": 7,
+      "stale": {
+        "total": 0,
+        "by_type": {
+          "missing_from_disk": 0,
+          "newer": 0,
+          "length_mismatch": 0,
+          "unreadable": 0
+        }
+      }
+    },
+    "without_coverage": {
+      "total": 0,
+      "by_type": {
+        "missing_from_coverage": 0,
+        "unreadable": 0,
+        "skipped": 0
+      }
+    }
+  }
 }
 ```
 
 **Notes:**
-- Respects `--tracked-globs` when you only want to aggregate a subset of files.
-- Honors `--staleness error` to raise if coverage data is out of date.
+- `lines` are based on fresh coverage entries only.
+- `with_coverage.stale.by_type` uses readable labels: `missing_from_disk`, `newer`,
+  `length_mismatch`, `unreadable`.
+- `without_coverage` is only present when tracking is enabled (tracked globs provided).
+- Respects `-g` / `--tracked-globs` when you only want to aggregate a subset of files.
+- Totals exclude stale files (`"missing"`, `"newer"`, `"length_mismatch"`, `"error"`) so the aggregate reflects only fresh coverage data.
+- Honors `-S` / `--raise-on-stale` to raise if coverage data is out of date.
 
 ### `version`
 
@@ -329,14 +388,14 @@ These options work with all subcommands.
 
 Path to the `.resultset.json` file or a directory containing it.
 
-For a detailed explanation of how to configure the resultset location, including the default search path, environment variables, and MCP configuration, see the [Configuring the Resultset](../README.md#configuring-the-resultset) section in the main README.
+For a detailed explanation of how to configure the resultset location, including the default search path, environment variables, and MCP configuration, see the [Configuring the Resultset](../index.md#configuring-the-resultset) section in the main README.
 
 ### `-R, --root PATH`
 
 Project root directory (default: current directory).
 
 ```sh
-clp --root /path/to/project
+clp -R /path/to/project  # -R = --root
 ```
 
 ### `-fJ`
@@ -387,7 +446,7 @@ clp -s u uncovered lib/api/client.rb       # u = uncovered
 
 ### `-c, --context-lines N`
 
-Number of context lines around uncovered code (for `--source uncovered`). Must be a non-negative integer.
+Number of context lines around uncovered code (for `-s uncovered` / `--source uncovered`). Must be a non-negative integer.
 
 ```sh
 clp -s u -c 3 uncovered lib/api/client.rb  # -s u = uncovered, -c = --context-lines
@@ -395,49 +454,115 @@ clp -s u -c 3 uncovered lib/api/client.rb  # -s u = uncovered, -c = --context-li
 
 **Default:** 2 lines
 
-### `--color` / `--no-color`
+### Boolean Flags (`--color` / `-C`, `--raise-on-stale`)
 
-Enable or disable ANSI color codes in source output.
+These options require explicit boolean values. Recognized literals:
+
+| true   | false   |
+|--------|---------|
+| `yes`  | `no`    |
+| `y`    | `n`     |
+| `true` | `false` |
+| `t`    | `f`     |
+| `on`   | `off`   |
+| `+`    | `-`     |
+| `1`    | `0`     |
 
 ```sh
-clp uncovered lib/api/client.rb --source --color
-clp uncovered lib/api/client.rb --source --no-color
+clp --color false           # disable color
+clp --raise-on-stale yes    # enforce stale coverage failures
 ```
 
-**Default:** Colors enabled if output is a TTY
+### `-C, --color BOOLEAN`
 
-### `-S, --staleness MODE`
+Enable or disable ANSI color codes in source output. Requires an explicit boolean value.
 
-Staleness checking mode.
+```sh
+clp uncovered lib/api/client.rb -s uncovered --color true
+clp uncovered lib/api/client.rb -s uncovered -C false
+```
 
-**Modes:**
+**Default:** Colors enabled if output is a TTY
+
+### `-S, --raise-on-stale BOOLEAN`
 
-| Short | Long    | Description                                              |
-|-------|---------|----------------------------------------------------------|
-| `o`   | `off`   | Detect and mark stale files, but don't raise error (default) |
-| `e`   | `error` | Detect stale files and raise error                       |
+Raise error if coverage is stale. Requires an explicit boolean value. Default is `false` (only report staleness in output).
 
 ```sh
-# Exit with error if coverage is stale
-clp --staleness error
-clp -S e  # Short form
+# Enable raising an error if coverage is stale
+clp -S true
+clp --raise-on-stale yes
+
+# Explicitly disable raising an error (useful to override COV_LOUPE_OPTS)
+clp --raise-on-stale false
 ```
 
 **Staleness conditions:**
-- **M** (Missing): Source file no longer exists on disk
-- **T** (Timestamp): Source file modified after coverage was generated
-- **L** (Length): Source file line count differs from coverage data
+- **"missing"** (Missing): Source file no longer exists on disk
+- **"newer"** (Timestamp): Source file modified after coverage was generated
+- **"length_mismatch"** (Length): Source file line count differs from coverage data
+- **"error"** (Error): Staleness check failed due to permission or I/O errors
 - Tracked files missing from coverage (with --tracked-globs)
 
 ### `-g, --tracked-globs PATTERNS`
 
 Comma-separated glob patterns for files that should be tracked.
 
+**Default:** `[]` (empty - shows all files in the resultset)
+
+**Why no default patterns?**
+1. **Transparency** - Shows all coverage data without hiding files that don't match assumptions
+2. **Avoids false positives** - Broad patterns like `**/*.rb` flag migrations, bin scripts, etc. as "missing"
+3. **Project variety** - Coverage patterns vary by project structure (lib/, app/, src/, config/, etc.)
+
+**Important:** Files lacking any coverage at all (not loaded during tests) will not appear in the resultset and therefore won't be visible with the default empty array. To detect such files, you must set `--tracked-globs` to match the files you expect to have coverage.
+
+**Best practice:** Match your SimpleCov configuration by setting `COV_LOUPE_OPTS`:
+
+```ruby
+# In spec_helper.rb or similar
+SimpleCov.start do
+  add_filter '/spec/'
+  add_filter '/test/'
+  track_files 'lib/**/*.rb'
+  track_files 'app/**/*.rb'
+end
+```
+
 ```sh
-clp -g "lib/payments/**/*.rb,lib/ops/jobs/**/*.rb" list  # -g = --tracked-globs
+# In your shell config (.bashrc, .zshrc, etc.)
+# Match the track_files patterns above
+export COV_LOUPE_OPTS="--tracked-globs lib/**/*.rb,app/**/*.rb"
 ```
 
-Used with `--staleness error` to detect new files not yet in coverage and to filter the `list`/`totals` subcommands.
+**Usage:**
+
+```sh
+# Use environment variable for project-wide default
+export COV_LOUPE_OPTS="--tracked-globs lib/**/*.rb,app/**/*.rb"
+clp list  # Uses globs from env var
+
+# Or specify per-command
+clp -g "lib/api/**/*.rb" list
+
+# Multiple patterns
+clp -g "lib/**/*.rb,app/models/**/*.rb" list
+
+# Export for CI (with globs to match SimpleCov)
+clp -g "lib/**/*.rb,app/**/*.rb" -fJ list > coverage.json
+```
+
+**Use cases:**
+- **Exclude unwanted results** - Narrow focus to a subsystem or layer
+- **Include files without coverage** - Report files that should be tracked but aren't in the resultset
+- **CI validation** - Use with `-S`/`--raise-on-stale` to catch coverage gaps
+
+**Important:** The `missing_tracked_files` array (in `list` output) only includes files that:
+1. Match the tracked globs
+2. Exist in the filesystem
+3. Are NOT in the coverage resultset
+
+Without globs, this array is empty (no expectations = no violations).
 
 ### `-l, --log-file PATH`
 
@@ -451,7 +576,9 @@ clp -l stderr                   # Log to standard error
 
 **Default:** `./cov_loupe.log`
 
-### `--error-mode MODE`
+**Warning:** Log files may grow unbounded in long-running or CI usage. Consider using a log rotation tool or periodically cleaning up the log file if this is a concern.
+
+### `-e, --error-mode MODE`
 
 Error handling verbosity.
 
@@ -465,14 +592,62 @@ Error handling verbosity.
 
 ```sh
 clp --error-mode debug summary lib/api/client.rb
+clp -e debug summary lib/api/client.rb  # -e = --error-mode
+clp -edebug summary lib/api/client.rb   # attached short option form
 ```
 
-### `--force-cli`
+### `-O, --output-chars MODE`
+
+Control output character encoding for ASCII-only environments.
+
+**Modes:**
+
+| Short | Long        | Description                                       |
+|-------|-------------|---------------------------------------------------|
+| `d`   | `default`   | Auto-detect terminal UTF-8 support (default)      |
+| `f`   | `fancy`     | Force Unicode output with box-drawing characters  |
+| `a`   | `ascii`     | Force ASCII-only output with transliteration      |
+
+```sh
+# Default mode (auto-detect)
+clp list
+
+# Force ASCII mode (for legacy terminals or CI)
+clp -O ascii list
+clp -O a list  # a = ascii
+
+# Force fancy mode (Unicode characters)
+clp -O fancy list
+clp -O f list  # f = fancy
+```
+
+**What gets converted in ASCII mode:**
+- Table borders (│ ─ ┌ ┐ └ ┘ ├ ┤ ┬ ┴ ┼ → | - + + + + + + + + +)
+- Source code markers (✓ · → + -)
+- Error messages and file paths
+- All formatted output (tables, source, JSON, YAML)
+
+**What does NOT get converted:**
+- Log files (preserved in original encoding for debugging fidelity)
+- Gem post-install message
+
+**Use cases:**
+- **CI/CD systems** with ASCII-only terminals: `clp -O ascii list`
+- **Windows** with legacy encoding: `clp -O ascii summary lib/api/client.rb`
+- **Piped output** to files: `clp -O ascii list > coverage.txt`
+- **Force Unicode** even if terminal detection fails: `clp -O fancy list`
+
+**Note:** The default mode auto-detects whether your terminal supports UTF-8. If Unicode characters appear garbled or as question marks, try `clp -O ascii`.
+
+### `-m, --mode MODE`
 
-Force CLI mode even when stdin is piped or when the process is running in a non-interactive shell (CI, Codex, etc.). Without it, the executable may fall back to MCP server mode.
+Specify execution mode: `cli` or `mcp` (default: `cli`). Use `--mode mcp` to run as an MCP server.
+In v4.0.0+, automatic mode detection was removed; you must explicitly specify `--mode mcp` to run the MCP server.
 
 ```sh
-clp --force-cli list
+clp -m mcp               # MCP server mode (required for MCP), short option form
+clp --mode mcp           # MCP server mode (required for MCP), long option form
+clp -m cli list          # CLI mode (default), can use to override environment variable
 ```
 
 ### `validate` Subcommand
@@ -506,21 +681,21 @@ bundle exec cov-loupe validate coverage_policy.rb
 **String mode (inline code):**
 ```sh
 # Simple inline validation
-clp validate -i '->(m) { m.all_files.all? { |f| f["percentage"] >= 80 } }'
+clp validate -i '->(m) { m.list.all? { |f| f["percentage"] >= 80 } }'
 
 # With global options
-clp --resultset coverage validate -i '->(m) { m.all_files.size > 0 }'
+clp -r coverage validate -i '->(m) { m.list.size > 0 }'
 ```
 
 **Example predicate file:**
 ```ruby
 # coverage_policy.rb
 ->(model) do
-  model.all_files.all? { |f| f['percentage'] >= 80 }
+  model.list.all? { |f| f['percentage'] >= 80 }
 end
 ```
 
-See [examples/success_predicates/](../../examples/success_predicates/) for more examples.
+See [examples/success_predicates/](../examples/success_predicates.md) for more examples.
 
 ## Output Formats
 
@@ -548,15 +723,15 @@ Machine-readable output. Paths are relative to project root.
     "total": 7,
     "percentage": 85.71
   },
-  "stale": false
+  "stale": "ok"
 }
 ```
 
 **Staleness values:**
-- `false` - Coverage data is current
-- `"M"` - File missing (no longer exists on disk)
-- `"T"` - Timestamp mismatch (file modified after coverage)
-- `"L"` - Length mismatch (line count differs)
+- `"ok"` - Coverage data is current
+- `"missing"` - File missing (no longer exists on disk)
+- `"newer"` - Timestamp mismatch (file modified after coverage)
+- `"length_mismatch"` - Length mismatch (line count differs)
 
 ### Source Display
 
@@ -589,22 +764,22 @@ clp summary lib/api/client.rb  # Automatically uses options above
 # Environment sets -fJ; explicit CLI options still take precedence
 export COV_LOUPE_OPTS="-fJ"
 clp summary lib/api/client.rb  # Uses JSON (from env)
-clp summary lib/api/client.rb -fJ  # Explicit, same result
+clp summary lib/api/client.rb -f table  # Explicit override to table format
 ```
 
 **Examples:**
 ```sh
 # Default resultset location
-export COV_LOUPE_OPTS="--resultset build/coverage"
+export COV_LOUPE_OPTS="-r build/coverage"
 
 # Enable detailed error logging
 export COV_LOUPE_OPTS="--error-mode debug"
 
 # Paths with spaces
-export COV_LOUPE_OPTS='--resultset "/path with spaces/coverage"'
+export COV_LOUPE_OPTS='-r "/path with spaces/coverage"'
 
 # Multiple options
-export COV_LOUPE_OPTS="--resultset coverage --staleness error -fJ"
+export COV_LOUPE_OPTS="-r coverage -S -fJ"
 ```
 
 
@@ -614,11 +789,11 @@ export COV_LOUPE_OPTS="--resultset coverage --staleness error -fJ"
 ### Basic Coverage Check
 
 ```sh
-# Show all files sorted by lowest coverage first
+# Show all files sorted by highest coverage first (default)
 clp
 
-# Find the 5 files with worst coverage
-clp list | head -10
+# Find the 5 files with worst coverage (account for header/footer)
+clp list | tail -7
 ```
 
 ### Detailed File Investigation
@@ -631,7 +806,7 @@ clp summary lib/payments/refund_service.rb
 clp uncovered lib/payments/refund_service.rb
 
 # View uncovered code in context
-clp uncovered lib/payments/refund_service.rb --source uncovered --context-lines 3
+clp uncovered lib/payments/refund_service.rb -s uncovered -c 3
 
 # Get detailed hit counts
 clp detailed lib/payments/refund_service.rb
@@ -687,36 +862,36 @@ clp -g "lib/payments/**/*.rb" list
 
 ```sh
 # Check if coverage is stale (for CI/CD)
-clp --staleness error
+clp -S true
 
 # Check with specific file patterns
-clp --staleness error -g "lib/payments/**/*.rb,lib/ops/jobs/**/*.rb" list
+clp -S true -g "lib/payments/**/*.rb,lib/ops/jobs/**/*.rb" list
 
 # See which files are stale (don't error)
-clp list  # Stale files marked with !
+clp list  # Stale column shows missing/newer/length_mismatch/error markers
 ```
 
 ### Source Code Display
 
 ```sh
 # Show full source with coverage markers
-clp summary lib/api/client.rb --source full
+clp summary lib/api/client.rb -s full
 
 # Show only uncovered lines with context
-clp uncovered lib/api/client.rb --source uncovered
+clp uncovered lib/api/client.rb -s uncovered
 
 # More context around uncovered code
-clp uncovered lib/api/client.rb --source uncovered --context-lines 5
+clp uncovered lib/api/client.rb -s uncovered -c 5
 
 # Without colors (for logging)
-clp uncovered lib/api/client.rb --source full --no-color
+clp uncovered lib/api/client.rb -s full --color false
 ```
 
 ### CI/CD Integration
 
 ```sh
 # Fail build if coverage is stale
-clp --staleness error || exit 1
+clp -S true || exit 1
 
 # Generate JSON report for artifact
 clp -fJ list > artifacts/coverage-report.json
@@ -731,8 +906,8 @@ clp -R services/api -r services/api/coverage  # -R = --root, -r = --resultset
 # Verbose error output
 clp --error-mode debug summary lib/api/client.rb
 
-# Custom log file
-clp --log-file /tmp/simplecov-debug.log summary lib/api/client.rb
+# Custom log file (--log-file or -l)
+clp -l /tmp/simplecov-debug.log summary lib/api/client.rb
 
 # Check what resultset is being used
 clp --error-mode debug 2>&1 | grep resultset
@@ -741,7 +916,7 @@ clp --error-mode debug 2>&1 | grep resultset
 ## Exit Codes
 
 - `0` - Success
-- `1` - Error (file not found, coverage data missing, stale coverage with `--staleness error`, etc.)
+- `1` - Error (file not found, coverage data missing, stale coverage with `-S` / `--raise-on-stale`, etc.)
 
 ## Next Steps