doc: improve README

Author: RomarQ

README.md

@@ -1,10 +1,10 @@
 # Check Dependency Inheritance in Cargo Workspaces
 
-A Cargo subcommand that enforces dependency inheritance hygiene in Cargo workspaces. It detects crates that specify dependency versions directly instead of using [`workspace = true`](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#inheriting-a-dependency-from-a-workspace), flags version mismatches, and suggests candidates for workspace promotion.
+A Cargo subcommand that detects workspace dependency inheritance issues in Cargo workspaces. It finds crates that specify dependency versions directly instead of using [`workspace = true`](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#inheriting-a-dependency-from-a-workspace), flags version mismatches, and suggests candidates for workspace promotion.
 
 ## Why?
 
-Cargo workspaces support [dependency inheritance](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#inheriting-a-dependency-from-a-workspace),you declare shared dependency versions once in the root `Cargo.toml` under `[workspace.dependencies]`, and member crates reference them with `{ workspace = true }`. This prevents version drift and duplicated dependency specs across workspace members.
+Cargo workspaces support [dependency inheritance](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#inheriting-a-dependency-from-a-workspace), you declare shared dependency versions once in the root `Cargo.toml` under `[workspace.dependencies]`, and member crates reference them with `{ workspace = true }`. This prevents version drift and duplicated dependency specs across workspace members.
 
 However, **Cargo has no built-in lint** for detecting when a crate specifies a version directly instead of inheriting from the workspace. [Clippy issue #10306](https://github.com/rust-lang/rust-clippy/issues/10306) tracks this as a feature request but remains unimplemented.
 
@@ -30,7 +30,7 @@ error: `rand = "0.7"` in crates/bar/Cargo.toml has a different version than work
 
 ### 3. Candidate for workspace promotion (warning)
 
-A dependency appears in multiple crates but isn't declared in `[workspace.dependencies]`.
+A dependency appears in multiple crates but isn't declared in `[workspace.dependencies]`. This check helps you identify dependencies that should be centralized.
 
 ```
 warning: `serde_yaml` appears in 3 crates but is not in [workspace.dependencies]
@@ -40,6 +40,8 @@ warning: `serde_yaml` appears in 3 crates but is not in [workspace.dependencies]
   hint: consider adding `serde_yaml = "0.9"` to [workspace.dependencies]
 ```
 
+By default, this is reported as a **warning** and does not cause the tool to exit with a non-zero code. Use `--promotion-failure` to treat promotion candidates as errors.
+
 ## Installation
 
 ```bash
@@ -48,37 +50,51 @@ cargo install cargo-workspace-inheritance-check
 
 ## Usage
 
-Run from your workspace root:
+### Default behavior
+
+Running without any flags checks all workspace members against `[workspace.dependencies]` in the root `Cargo.toml`. It reports errors for dependencies not using inheritance ([checks 1 and 2](#what-it-checks)) and warnings for promotion candidates ([check 3](#3-candidate-for-workspace-promotion-warning)). The tool exits with code 1 if any **errors** are found, and 0 if there are only warnings or no issues.
 
 ```bash
-# Check workspace dependency inheritance
 cargo workspace-inheritance-check
+```
+
+### Options
 
-# Specify a different workspace root
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--path <PATH>` | Path to the workspace root | `.` |
+| `--promotion-threshold <N>` | Minimum number of crates a dependency must appear in before it is flagged as a promotion candidate. For example, `--promotion-threshold 3` means a dependency must appear in at least 3 crates to trigger a warning. | `2` |
+| `--promotion-failure` | Promote promotion candidate warnings to errors, causing the tool to exit with code 1 when candidates are found. Useful in CI when you want to enforce that all shared dependencies are declared in `[workspace.dependencies]`. | `false` |
+| `--format <FORMAT>` | Output format: `human` or `json` | `human` |
+| `--no-fail` | Always exit with code 0, regardless of errors found. Useful when you want to see the report without failing a CI pipeline. | `false` |
+
+### Examples
+
+```bash
+# Check a workspace at a specific path
 cargo workspace-inheritance-check --path /path/to/workspace
 
-# Set promotion threshold (default: 2)
+# Only flag dependencies used in 3+ crates as promotion candidates
 cargo workspace-inheritance-check --promotion-threshold 3
 
-# Treat promotion candidates as errors
+# Fail CI if any dependency could be promoted to workspace level
 cargo workspace-inheritance-check --promotion-failure
 
-# Output as JSON
+# Get machine-readable output
 cargo workspace-inheritance-check --format json
 
-# Don't fail on errors (always exit 0)
+# Report issues without failing
 cargo workspace-inheritance-check --no-fail
 ```
 
-### Options
+## Exit Codes
 
-| Flag | Description | Default |
-|------|-------------|---------|
-| `--path <PATH>` | Path to workspace root | `.` |
-| `--promotion-threshold <N>` | Min crate count before suggesting workspace promotion | `2` |
-| `--promotion-failure` | Treat promotion candidates as errors | `false` |
-| `--format <FORMAT>` | Output format: `human`, `json` | `human` |
-| `--no-fail` | Exit 0 even when errors are found | `false` |
+| Code | Meaning |
+|------|---------|
+| `0` | No errors found (warnings are OK unless `--promotion-failure` is set) |
+| `1` | Errors found (or promotion warnings promoted to errors via `--promotion-failure`) |
+
+`--no-fail` overrides the exit code to always be `0`.
 
 ## Ignore Rules
 
@@ -87,16 +103,18 @@ You can skip specific dependencies from being checked by adding ignore rules to
 ```toml
 [workspace.metadata.inheritance-check]
 ignore = [
-  # Ignore rand in a specific crate
+  # Ignore rand in a specific crate (e.g., it intentionally uses a different version)
   { dependency = "rand", member = "crates/bar" },
   # Ignore openssl in all crates
   { dependency = "openssl" },
 ]
 ```
 
+Ignored dependencies are skipped in both reporting and fixing.
+
 ## JSON Output
 
-Use `--format json` for machine-readable output, useful for integrating with other tools:
+Use `--format json` for machine-readable output, useful for integrating with other tools or custom CI scripts:
 
 ```json
 {
@@ -129,6 +147,13 @@ Use `--format json` for machine-readable output, useful for integrating with oth
   run: cargo workspace-inheritance-check
 ```
 
+To also enforce that shared dependencies are promoted to workspace level:
+
+```yaml
+- name: Check workspace dependency inheritance (strict)
+  run: cargo workspace-inheritance-check --promotion-failure
+```
+
 ## Dependency Sections Checked
 
 All dependency sections in member crates are checked: