From c7084caf978bd0454ac1525332eadae3c74966c8 Mon Sep 17 00:00:00 2001
From: Ringku <100481036+ringku1@users.noreply.github.com>
Date: Wed, 1 Jul 2026 12:31:48 +0600
Subject: [PATCH] Enhance README with chapters and troubleshooting info
Added sections explaining chapters, prerequisites, troubleshooting, and agent compatibility.
---
README.md | 31 +++++++++++++++++++++++++++++++
1 file changed, 31 insertions(+)
diff --git a/README.md b/README.md
index 18f7d0a..19807a2 100644
--- a/README.md
+++ b/README.md
@@ -25,6 +25,17 @@
+## What's a chapter?
+
+Instead of reviewing a pull request as one long, undifferentiated diff, Stage groups related changes into "chapters" — for example, one chapter for a new API integration, another for a schema migration, another for test cleanup. Each chapter comes with a short summary of what changed and what's actually risky, so you know where to focus before reading line by line.
+
+## Prerequisites
+
+- Node.js 18 or later
+- A local git repository with changes to review
+- An AI coding agent that supports the `skills` convention (see [Which agents work with this?](#which-agents-work-with-this))
+- Optional: the [GitHub CLI](https://cli.github.com/) (`gh`), only needed for `--pr` to review a pull request by number or URL
+
## Install
```bash
@@ -100,6 +111,26 @@ dist/**
Ignored files still appear in the "Other changes" chapter so nothing is silently hidden. Comments (`#`), blank lines, and negation patterns (`!`) are supported — last matching pattern wins.
+## Troubleshooting
+
+**`/stage-chapters` isn't recognized in my agent.**
+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.**
+Auto-detection looks for `main` or `master`. If your default branch is named differently, pass it explicitly: `--base your-branch-name`.
+
+**`--pr` isn't working.**
+This requires the [GitHub CLI](https://cli.github.com/) installed and authenticated (`gh auth login`). Confirm `gh` works on its own first — Stage relies on it to fetch PR data.
+
+## Which agents work with this?
+
+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.)*
+
## License