docs(readme): show the checkout the action needs

[michen00]

What changes, and why

The first snippet in "As a GitHub Action" — the one a consumer copies first — had no checkout step:

- uses: michen00/markdown-prose-hooks@v0.4.0
  with:
    write: 'false'
    fail-on-change: 'true'

The action's default path builds its file list from git ls-files -z '*.md' '*.markdown' run in the workspace (action.yml:235). Outside a git work tree that finds nothing — and the step is written with set -uo pipefail rather than -e, with the command inside a process substitution, so the failure does not propagate:

$ cd /not-a-repo
$ bash -c 'set -uo pipefail; n=0
    while IFS= read -r -d "" f; do n=$((n+1)); done < <(git ls-files -z "*.md" 2>/dev/null)
    echo "files found: $n"; echo "exit: $?"'
files found: 0
exit: 0

So a gate spelled fail-on-change: 'true' passes by inspecting nothing — green, and green for a reason nobody looks at. That is the worst shape a copied gate can take.

The "Fixing instead of failing" recipe further down the same section already begins with - uses: actions/checkout@v7, so the two snippets disagreed and the shorter one is the one a reader takes first. It now matches.

The sentence about paths also says where "tracked" comes from, which is what makes the checkout load-bearing rather than boilerplate a reader might trim.

Corpus

The corpus is the specification, and both implementations answer to it. Tick what applies.

• This changes no behavior the corpus specifies.
• This changes what gets joined, and a case in corpus/ pins the new behavior. The case was written first and failed first.
• The change makes the tool join more than it did. The section above says what it will not eat.

Documentation of how to invoke the action. action.yml is unchanged — whether the silent-pass behaviour should itself be an error is a separate question, and this PR only stops the docs from walking a consumer into it.

Checks

• make check passes, or make test does and this touches no Rust.

make tidy, plus unwrap-markdown-prose-py --fail-on-change README.md.

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Great, no issues found!

Qodo reviewed your code and found no material issues that require review

Tip of the day

💡 Did you know, you can add REVIEW.md to your repo root and Qodo follows it on every PR

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[qodo-code-review]

PR Summary by Qodo

Document required checkout step for GitHub Action

📝 Documentation 🕐 Less than 5 minutes

AI Description

• Adds checkout to the primary GitHub Action example so tracked Markdown files are available.
• Explains that missing checkout silently produces an empty, passing inspection.

Diagram

sequenceDiagram
  actor W as GitHub Workflow
  participant C as Checkout Action
  participant R as Repository Workspace
  participant P as Prose Action
  W->>C: Run checkout
  C->>R: Populate repository
  W->>P: Run prose check
  P->>R: List tracked Markdown
  R-->>P: Return file paths

Loading

High-Level Assessment

Explicitly documenting actions/checkout is the optimal scoped fix because the action intentionally discovers tracked files from the workspace. Changing runtime behavior to fail outside a Git work tree is a separate implementation concern and should not replace correcting the copyable example.

Files changed (1) +2 / -1

Documentation (1) +2 / -1

README.mdRequire checkout in the primary GitHub Action example +2/-1

Require checkout in the primary GitHub Action example

• Adds 'actions/checkout@v7' before the prose action so default file discovery can access tracked Markdown files. Explains that omitting checkout causes the action to inspect no files while still exiting successfully.

README.md

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87.37%. Comparing base (1e9ac89) to head (8d4d09d).

Additional details and impacted files

@@           Coverage Diff           @@
##             main      #50   +/-   ##
=======================================
  Coverage   87.37%   87.37%           
=======================================
  Files           3        3           
  Lines         689      689           
=======================================
  Hits          602      602           
  Misses         87       87           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

🟢 Approval recommended

The change is documentation-only and corrects a concrete, high-impact usage footgun without altering runtime behavior.

Pull request overview

This PR updates the README’s “As a GitHub Action” usage guidance to reflect a required actions/checkout step, so the action’s default file discovery (via git ls-files in the workspace) actually finds and inspects tracked Markdown files.

Changes:

• Add an explicit actions/checkout@v7 step to the first GitHub Action snippet so consumers don’t accidentally run the action outside a git worktree.
• Expand the paths explanation to clarify that “tracked” comes from git ls-files, and that omitting checkout can lead to a silent no-op that still exits 0.

File summaries

File	Description
README.md	Adds the missing checkout step to the primary action snippet and clarifies why it’s required due to git ls-files-based discovery.

Review details

• Files reviewed: 1/1 changed files
• Comments generated: 0
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.