docs: improve README and add usage notes

README.md

@@ -1,31 +1,41 @@
 # gh-pr-release-flow
 
-A lightweight GitHub workflow skill for repos that:
-- reject direct pushes to `main`
-- require pull requests even when approvals are set to 0
-- need releases to happen **after merge**, not while work is still only in an open PR
+A lightweight skill for GitHub repos that block direct pushes to `main`, require pull requests, and expect release work to happen **after merge**.
+
+This repo exists to encode one practical workflow:
+
+> **PR first, release after merge.**
 
 ## Why this exists
 
-We kept running into the same avoidable problems:
+A lot of GitHub workflow pain is repetitive, not interesting:
 - pushing to `main` and getting rejected by repo rules
-- assuming `approvals = 0` meant direct push was allowed
-- discussing release updates before the relevant changes were merged
-- re-discovering the same GitHub flow every time
+- assuming `approvals = 0` means direct push is allowed
+- discussing release updates before the relevant changes are merged
+- forgetting to check whether `package.json`, git tags, and GitHub releases are aligned
 
-This skill turns that repeated pain into a default workflow.
+This skill turns those repeated mistakes into a default operating habit.
 
-## What it helps with
+## What this skill helps with
 
 - detect when a repo is effectively PR-only
-- switch quickly from local commits to branch + PR flow
-- decide whether release work should wait until after merge
-- keep `package.json` version, git tag, and GitHub release from drifting apart
-- avoid repeating the same repo-rule mistakes
+- switch from local commits to branch + PR flow quickly
+- decide whether release work must wait until after merge
+- keep version / tag / release state from drifting apart
+- stop repeating the same protected-branch mistakes
+
+## When to use it
+
+Use this skill when you are working in a GitHub repo and any of these are true:
+- direct push to `main` may be blocked
+- the repo uses branch protection / PR-only rules
+- you need to open a PR after local work
+- you need to decide whether a release should happen now or wait for merge
+- you keep re-learning the same GitHub publishing flow from scratch
 
 ## Default policy
 
-If repo rules are unclear, prefer:
+If repo rules are unknown, prefer this order:
 1. local commit
 2. branch
 3. push branch
@@ -33,16 +43,50 @@ If repo rules are unclear, prefer:
 5. merge
 6. release
 
-In other words: **PR first, release after merge**.
+In short: **PR first, release after merge**.
 
-## Suggested use cases
+## Example situations
 
-- docs updates that still must go through PR
-- feature work in protected repos
-- patch releases after merge
-- repos with branch protection / PR-only rules
+### Example 1: docs change in a protected repo
+You update README locally, commit, try to push, and GitHub rejects direct push to `main`.
 
-## Notes
+Correct move:
+- keep the local commit
+- create a branch
+- push the branch
+- open a PR
 
-This is intentionally a narrow workflow skill, not a general GitHub encyclopedia.
-It exists to encode one practical habit: stop bouncing off protected `main`, and stop releasing changes that have not landed yet.
+### Example 2: user says “update the release”
+Before touching the release:
+- check whether the intended changes are already merged
+- inspect current version, tags, and releases
+- if changes are still only in an open PR, wait or explicitly create a prerelease/draft
+
+### Example 3: approvals are set to 0
+That still does **not** prove direct push is allowed.
+Branch protection may still require PRs.
+
+## What this skill does not try to be
+
+This is **not** a general GitHub encyclopedia.
+It is intentionally narrow:
+- protected branch / PR-first repos
+- release-after-merge workflow
+- practical decision rules
+
+## Repo contents
+
+- `SKILL.md` — the actual skill instructions for agent use
+- `README.md` — human-readable overview and examples
+
+## Suggested next improvements
+
+Future iterations can add:
+- PR body examples
+- release notes examples
+- repo-rule detection checklist
+- examples for patch vs minor release decisions
+
+## License
+
+MIT