docs: open the README with three examples: commits and branch, PR title, job summary

Author: shenxianpeng

README.md

@@ -27,97 +27,137 @@ request — message, branch, author, and optionally the PR title — against you
 `cchk.toml`, and reports the result in the job summary, as annotations on the
 diff and, if you want, as a PR comment.
 
-## Start with one check
+## Usage
+
+Three examples. Each is a complete workflow, e.g.
+`.github/workflows/commit-check.yml`; start with the one you need.
 
-Each of these is a complete workflow. Pick one, then turn on more checks when
-you need them.
+### 1. Commit messages and branch name
 
-**Pull request title only.** On a repository that squash-merges, the title
-becomes the commit on `main`, so it is the one message worth checking. With
-GitHub's default squash message, a pull request of a single commit lands that
-commit's message instead; set the squash commit message to "Pull request
-title" in the repository settings to make the title the one that lands:
+Both are checked by default, against
+[Conventional Commits](https://www.conventionalcommits.org/) and
+[Conventional Branch](https://conventionalbranch.org/), so the action needs no
+inputs:
 
 ```yaml
-name: PR Title
+name: Commit Check
 
 on:
   pull_request:
-    types: [opened, edited, synchronize, reopened]
 
 jobs:
-  pr-title:
+  commit-check:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
-      - uses: commit-check/commit-check-action@v2
         with:
-          message: false
-          branch: false
-          pr-title: true
+          fetch-depth: 0  # recommended: read the PR's commits from the clone
+      - uses: commit-check/commit-check-action@v2
 ```
 
-**Branch name only**, against [Conventional Branch](https://conventionalbranch.org/):
+> [!NOTE]
+> `fetch-depth: 0` is recommended, not required. A shallow clone holds only
+> GitHub's merge commit, so the action lists the pull request's commits
+> through the API — up to 250, with `pull-requests: read` — and fetches the
+> head commit for the author checks. If the commits cannot be listed, it warns
+> and checks HEAD alone; if the head commit cannot be fetched, it warns and
+> skips the author checks.
+
+### 2. Pull request title
+
+On a repository that squash-merges, the title becomes the commit on `main`, so
+it is the one message worth checking. With GitHub's default squash message, a
+pull request of a single commit lands that commit's message instead; set the
+squash commit message to "Pull request title" in the repository settings to
+make the title the one that lands:
 
 ```yaml
-name: Branch Name
+name: PR Title
 
 on:
   pull_request:
+    types: [opened, edited, synchronize, reopened]
 
 jobs:
-  branch-name:
+  pr-title:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
       - uses: commit-check/commit-check-action@v2
         with:
           message: false
+          branch: false
+          pr-title: true
 ```
 
-Both read the repository's `cchk.toml` if there is one, so a custom type list
-or an extra allowed branch name works without changing the workflow.
+### 3. Job summary
 
-## Usage
+Every run writes its report to the job summary; `job-summary` is on by
+default. A failing run opens with a count and a table of only what failed —
+each rule ID links to its documentation, each commit to itself — with the full
+tree one click away:
 
-Add a workflow, e.g. `.github/workflows/commit-check.yml`:
+> **Commit Check**
+>
+> ❌ **2 of 4 checks failed**
+>
+> | Scope | Checked value | Failed checks |
+> |---|---|---|
+> | [Commit 2/2 (5584f46)](https://github.com/acme/widgets/commit/5584f462cc3c947b2ba8d3d1a5735571803ee159) | `bad msg` | [CC001 message](https://commit-check.com/rules/#cc001) |
+> | Branch | `Feature/Add-Login` | [CC201 branch](https://commit-check.com/rules/#cc201) |
+>
+> <details>
+> <summary>Show all 4 checks</summary>
+>
+> ```text
+> Commit message
+>   ✔ PR title (feat: add login page)
+>   ✔ Commit 1/2 (d87faca) (feat: add login page)
+>   ✖ Commit 2/2 (5584f46) (1 failure)
+>       CC001 message
+>         value: bad msg
+>         The commit message should follow Conventional Commits.
+>         Suggest: Use <type>(<scope>): <description>
+> Branch
+>   ✖ Branch (1 failure)
+>       CC201 branch
+>         value: Feature/Add-Login
+>         The branch should follow Conventional Branch.
+>         Suggest: Rename the branch to "feature/Add-Login" (git branch -m feature/Add-Login)
+>         Fix: feature/Add-Login
+> ```
+>
+> </details>
+>
+> _commit-check &lt;version&gt; · [Rules reference](https://commit-check.com/rules/)_
 
-```yaml
-name: Commit Check
+The rest follow the same layout:
 
-on:
-  pull_request:
-    branches: 'main'
+- **Passed:** one line, `✅ All 3 checks passed`, with the tree folded away.
+- **Warned:** a rule under `warn` gets its own ⚠ row and counts as passed.
+- **Skipped:** a run where nothing was validated — typically a bot listed in
+  `ignore_authors` — reads `⊘`, never `✔`.
 
-jobs:
-  commit-check:
-    runs-on: ubuntu-latest
-    permissions:  # use permissions because use of pr-comments
+The step log prints the same tree, plus one annotation per finding on the
+Files changed tab. To post the same report on the pull request, edited in
+place on later runs, add `pr-comments: true` and grant the job
+`pull-requests: write`:
+
+```yaml
+    permissions:
       contents: read
       pull-requests: write
     steps:
       - uses: actions/checkout@v7
-        with:
-          # Recommended: the action then reads the PR's commits from the clone.
-          # With the default fetch-depth: 1 it asks the GitHub API instead.
-          fetch-depth: 0
       - uses: commit-check/commit-check-action@v2
         with:
-          # Commit messages and the branch name are checked by default;
-          # see Inputs for the rest.
           pr-comments: true
 ```
 
-> [!NOTE]
-> `fetch-depth: 0` is recommended, not required. A shallow clone holds only
-> GitHub's merge commit, so the action lists the pull request's commits
-> through the API — up to 250, with `pull-requests: read` — and fetches the
-> head commit for the author checks. If the commits cannot be listed, it warns
-> and checks HEAD alone; if the head commit cannot be fetched, it warns and
-> skips the author checks.
-
-Runs on `ubuntu-latest`, `macos-latest` and `windows-latest`. Self-hosted
-runners need a few tools — see [Good to know](#good-to-know).
+All three read the repository's `cchk.toml` if there is one, so a custom type
+list or an extra allowed branch name works without changing the workflow. The
+action runs on `ubuntu-latest`, `macos-latest` and `windows-latest`;
+self-hosted runners need a few tools — see [Good to know](#good-to-know).
 
 ## Inputs
 
@@ -156,57 +196,6 @@ Priority: inputs > environment variables > config file > defaults. A rule
 listed under the config's top-level `warn` is reported in full but never fails
 the run. Every key: [configuration reference](https://commit-check.com/configuration/).
 
-## What it looks like
-
-A failing run opens with a count and a table of only what failed — each rule ID
-links to its documentation, each commit to itself — with the full tree one
-click away:
-
-> **Commit Check**
->
-> ❌ **2 of 4 checks failed**
->
-> | Scope | Checked value | Failed checks |
-> |---|---|---|
-> | [Commit 2/2 (5584f46)](https://github.com/acme/widgets/commit/5584f462cc3c947b2ba8d3d1a5735571803ee159) | `bad msg` | [CC001 message](https://commit-check.com/rules/#cc001) |
-> | Branch | `Feature/Add-Login` | [CC201 branch](https://commit-check.com/rules/#cc201) |
->
-> <details>
-> <summary>Show all 4 checks</summary>
->
-> ```text
-> Commit message
->   ✔ PR title (feat: add login page)
->   ✔ Commit 1/2 (d87faca) (feat: add login page)
->   ✖ Commit 2/2 (5584f46) (1 failure)
->       CC001 message
->         value: bad msg
->         The commit message should follow Conventional Commits.
->         Suggest: Use <type>(<scope>): <description>
-> Branch
->   ✖ Branch (1 failure)
->       CC201 branch
->         value: Feature/Add-Login
->         The branch should follow Conventional Branch.
->         Suggest: Rename the branch to "feature/Add-Login" (git branch -m feature/Add-Login)
->         Fix: feature/Add-Login
-> ```
->
-> </details>
->
-> _commit-check &lt;version&gt; · [Rules reference](https://commit-check.com/rules/)_
-
-The rest follow the same layout:
-
-- **Passed:** one line, `✅ All 3 checks passed`, with the tree folded away.
-- **Warned:** a rule under `warn` gets its own ⚠ row and counts as passed.
-- **Skipped:** a run where nothing was validated — typically a bot listed in
-  `ignore_authors` — reads `⊘`, never `✔`.
-
-The step log prints the same tree, plus one annotation per finding on the
-Files changed tab. With `pr-comments: true` the same report is posted to the
-pull request, and later runs edit that one comment instead of adding more.
-
 ## Outputs
 
 ### `result`
@@ -332,8 +321,8 @@ repositories) or run the action on `pull_request_target` — both are covered in
 
 Dependabot pull requests are not forks, but their `pull_request` runs also get
 a read-only token by default. The `pull-requests: write` grant in the
-[usage example](#usage) is honoured for them; without it the action logs a
-`::warning::` on the 403 and leaves the report in the job summary. Adding
+[job summary example](#3-job-summary) is honoured for them; without it the
+action logs a `::warning::` on the 403 and leaves the report in the job summary. Adding
 `dependabot[bot]` to `ignore_authors` skips those pull requests altogether.
 
 </details>