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:
+A lightweight skill for GitHub repos that block direct pushes to `main`, require pull requests, and expect release work to happen **after merge**.
-- reject direct pushes to `main`
+
-- require pull requests even when approvals are set to 0
+This repo exists to encode one practical workflow:
-- need releases to happen **after merge**, not while work is still only in an open PR
+
+> **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
+- assuming `approvals = 0` means direct push is allowed
-- discussing release updates before the relevant changes were merged
+- discussing release updates before the relevant changes are merged
-- re-discovering the same GitHub flow every time
+- 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
+- switch from local commits to branch + PR flow quickly
-- decide whether release work should wait until after merge
+- decide whether release work must wait until after merge
-- keep `package.json` version, git tag, and GitHub release from drifting apart
+- keep version / tag / release state from drifting apart
-- avoid repeating the same repo-rule mistakes
+- 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
+### Example 1: docs change in a protected repo
-- feature work in protected repos
+You update README locally, commit, try to push, and GitHub rejects direct push to `main`.
-- patch releases after merge
-- repos with branch protection / PR-only rules
 
-## 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.
+### Example 2: user says “update the release”
-It exists to encode one practical habit: stop bouncing off protected `main`, and stop releasing changes that have not landed yet.
+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

USAGE.md

@@ -0,0 +1,30 @@
+# Usage notes
+
+This repo is meant to stay lightweight.
+
+## Basic usage idea
+
+When working in a GitHub repo:
+1. inspect branch / status / tags / releases if needed
+2. assume PR-first if repo rules are unclear
+3. avoid release work until the relevant changes are merged
+
+## Mental checklist
+
+Before pushing:
+- Am I on `main`?
+- Does this repo allow direct push to `main`?
+- If I do not know, why am I not using a branch + PR?
+
+Before changing a release:
+- Are the intended changes already merged?
+- Does `package.json` version match the intended release?
+- Are git tags and GitHub releases in sync?
+
+## Core rule
+
+If uncertain, do the safer thing:
+- branch
+- PR
+- merge
+- release