Improve README: explain chapters concept, add prerequisites & troubleshooting

[ringku1]

Hi team — really like the chapters approach to reviewing PRs. While
setting up the CLI, I noticed the README jumps straight into
install/usage without explaining what a "chapter" actually is, and
doesn't cover prerequisites or common troubleshooting steps.

This PR adds:

• A one-line explanation of chapters up front
• A prerequisites section
• A troubleshooting section for the most likely setup issues,
  including the --pr / gh requirement

I left one honest note about agent compatibility rather than guessing —
happy to update it once that's confirmed on your end.

I'm a software engineer who does developer documentation work — if
this is useful, I'd be glad to help with more of your docs:
https://ringku1.github.io/technical-writing-portfolio/

---

---

Summary by cubic

Clarifies the README by defining what “chapters” are and adding a short prerequisites list. Adds troubleshooting for common setup issues (including gh requirement for --pr, base branch selection, and empty diff cases) and notes agent compatibility via the skills convention.

^{Written for commit c7084ca. Summary will update on new commits.}

[stage-review]

Ready to review this PR? Stage has broken it down into 2 individual chapters for you:

	Title
1	Define chapters concept and list prerequisites
2	Add troubleshooting guide and agent compatibility notes

_{Chapters generated by Stage for commit c7084ca on Jul 3, 2026 7:40am UTC.}

[cubic-dev-ai]

2 issues found across 1 file

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="README.md">

<violation number="1" location="README.md:120">
P1: Troubleshooting gives incorrect recovery advice: `--ref staged` will produce an empty diff when everything is already committed, and mischaracterizes the default diff scope as always scanning the working tree rather than auto-detecting between working-tree and committed modes.</violation>

<violation number="2" location="README.md:132">
P2: Public README contains an internal editorial note addressed to the maintainers rather than end users.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P1: Troubleshooting gives incorrect recovery advice: --ref staged will produce an empty diff when everything is already committed, and mischaracterizes the default diff scope as always scanning the working tree rather than auto-detecting between working-tree and committed modes.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At README.md, line 120:

<comment>Troubleshooting gives incorrect recovery advice: `--ref staged` will produce an empty diff when everything is already committed, and mischaracterizes the default diff scope as always scanning the working tree rather than auto-detecting between working-tree and committed modes.</comment>

<file context>
@@ -100,6 +111,26 @@ dist/**
+Re-run `npx skills add ReviewStage/stage-cli` to confirm it installed cleanly, and restart your agent — most agents only pick up newly registered skills after a restart.
+
+**Stage says there's nothing to review.**
+By default it looks for staged, unstaged, and untracked changes. If everything's already committed, use `--ref staged` or diff against a specific commit with `--compare`.
+
+**It picked the wrong base branch.**
</file context>

Suggested change

	By default it looks for staged, unstaged, and untracked changes. If everything's already committed, use `--ref staged` or diff against a specific commit with `--compare`.
	+By default it auto-detects whether to review uncommitted changes (staged, unstaged, and untracked) or committed changes against the base branch. If the wrong scope is detected, use `--ref work` to force a working-tree review, or diff against specific commits with `--compare`.

[cubic-dev-ai]

P2: Public README contains an internal editorial note addressed to the maintainers rather than end users.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At README.md, line 132:

<comment>Public README contains an internal editorial note addressed to the maintainers rather than end users.</comment>

<file context>
@@ -100,6 +111,26 @@ dist/**
+
+Stage runs on the `skills` convention for AI coding agents, so support depends on whether your agent implements that convention. If `npx skills add` doesn't complete, or `/stage-chapters` doesn't show up as a command afterward, check your agent's own docs for skills or plugin support.
+
+*(Note to the Stage team: this is the one thing I couldn't verify from outside the project — worth explicitly listing which agents you've tested against, since "works with any AI agent" is the first thing a new user will want confirmed.)*
+
 <img width="1840" height="1196" alt="Stage CLI" src="https://raw.githubusercontent.com/ReviewStage/stage-cli/main/assets/screenshot.png" />
</file context>

Suggested change

	*(Note to the Stage team: this is the one thing I couldn't verify from outside the project — worth explicitly listing which agents you've tested against, since "works with any AI agent" is the first thing a new user will want confirmed.)*
	+(For a list of confirmed compatible agents, see the project documentation or open an issue if your agent isn't listed.)