docs: add screenshots

fixes #8

Author: omarkohl

README.md

@@ -35,8 +35,9 @@ repository. jip does **not** work with Git directly.
 
 ```bash
 # Make your changes as a stack of jj commits
-jj commit -m "feat: add data model"
-jj commit -m "feat: add migration"
+jj commit -m "feat: add user data model"
+jj commit -m "feat: add user store"
+jj commit -m "feat: add user API endpoint"
 
 # Create/update PRs for the stack
 jip send
@@ -45,14 +46,20 @@ jip send
 jj new <change-id>
 # ... make changes ...
 jj squash
-jip send
+jip s # alias for 'send'
 
-# After bottom PR is merged upstream
-jj git fetch
-jj rebase -o main
-jip send
+# After bottom PR is merged upstream, rebase the rest and send again
+jip s --rebase
 ```
 
+A stack of commits before sending:
+
+![jj log showing a stack of three commits](docs/images/jj-log-before-send.png)
+
+The resulting PR on GitHub with stack navigation:
+
+![GitHub PR showing stack navigation with links to all PRs in the stack](docs/images/pr-stack-navigation.png)
+
 ## Documentation
 
 - [Why commit-based workflow?](docs/why.md) — the philosophy behind jip

docs/images/independent-pr.png

@@ -5,15 +5,14 @@ created by jip. You don't need jip or jj installed to review them.
 
 ## What a stacked PR looks like
 
-Each PR in a stack has a description like:
+Each PR in a stack has a description listing all PRs with the current one
+highlighted:
 
-> **Stack:**
-> - PR #3: Add API endpoint **← you are here**
-> - PR #2: Add database migration
-> - PR #1: Add data model
+![GitHub PR showing stack navigation with links to all PRs in the stack](images/pr-stack-navigation.png)
 
-The PR diff shows only the changes in *that specific commit*, not the
-cumulative diff of the whole stack.
+The PR description tells you which commit to review. The 'Files changed' tab
+shows the cumulative diff from `main`, but you should **only** look at the
+highlighted commit (5670b0e in the screenshot above).
 
 ## How to review
 
@@ -42,14 +41,15 @@ reviewable change.
 
 ## When you want something changed
 
-Say you're reviewing a 4-PR stack and you request changes on PR #2:
+Say you're reviewing the 3-PR stack from the screenshot above and you request
+changes on PR #2 (the user store):
 
 1. The author fixes the commit for PR #2 and runs `jip send`.
 2. jip **posts a comment** on PR #2 showing exactly what changed since your
    last review (rebase noise is filtered out). You don't need to re-read the
    full diff — just read that comment.
-3. PRs #3 and #4 are rebased but their actual content didn't change, so their
-   diffs stay the same.
+3. PR #3 is rebased but its actual content didn't change, so its diff stays
+   the same.
 4. PR #1 is unaffected.
 
 ### What are these diff comments?
@@ -59,6 +59,12 @@ old and new version of the commit. Rebase changes are factored out, so you see
 only what the author actually changed in response to your review. (This is
 sometimes called an "interdiff" — a diff between two diffs.)
 
+![Interdiff comment showing exactly what changed since the last push](images/interdiff-comment.png)
+
+If a PR was only rebased without any actual content changes, jip notes that:
+
+![Comment indicating the PR was only rebased with no content changes](images/rebase-only-comment.png)
+
 ## Merging
 
 PRs created by jip are **normal GitHub PRs**. There is no special "land"

docs/images/interdiff-comment.png

@@ -49,94 +49,71 @@ jip s --upstream upstream
 
 ---
 
-## Multi-stack workflow: reformat, bugfix, feature, and docs
+## Multi-stack workflow: user feature and docs
 
-You need to make four changes to a project. Three are related (reformat →
-bugfix → feature), one is unrelated (docs). You decide to split them into two
-stacks.
+You need to make four changes to a project. Three are related (data model →
+store → API endpoint), one is unrelated (docs). You decide to split them into
+two stacks.
 
 ### Setting up the stacks
 
 ```bash
-# Stack 1: reformat → bugfix → feature
+# Stack 1: data model → store → API endpoint
 jj new main
-# ... run gofumpt, verify ...
-jj commit -m "style: reformat all Go files with gofumpt"
+# ... create user type ...
+jj commit -m "feat: add user data model"
 
-# ... fix the bug ...
-jj commit -m "fix: correct off-by-one in pagination"
+# ... create store ...
+jj commit -m "feat: add user store"
 
-# ... implement feature ...
-jj commit -m "feat: add cursor-based pagination"
+# ... create handler ...
+jj commit -m "feat: add user API endpoint"
 
 # Stack 2: unrelated docs change (branching from main, not from the stack above)
 jj new main
 # ... update docs ...
-jj commit -m "docs: update API examples for v2"
+jj commit -m "docs: update README with getting started section"
 ```
 
-Your jj log now looks like:
+Your jj log now shows two independent stacks branching from main:
 
-```
-@  yyozkxuu alice@example.com 2026-02-26 21:18:04 beb5c864
-│  (empty) (no description set)
-○  vuzkwnuw alice@example.com 2026-02-26 21:18:04 9df5376f
-│  docs: update API examples for v2
-│ ○  prmxnnou alice@example.com 2026-02-26 21:18:04 06d70097
-│ │  feat: add cursor-based pagination
-│ ○  plxqtqrq alice@example.com 2026-02-26 21:18:04 5ec21ca9
-│ │  fix: correct off-by-one in pagination
-│ ○  tolsvlnw alice@example.com 2026-02-26 21:18:04 0268aba3
-├─╯  style: reformat all Go files with gofumpt
-○  tznkmxxk alice@example.com 2026-02-26 21:17:54 main 62073074
-│  initial commit
-◆  zzzzzzzz root() 00000000
-```
+![jj log showing two independent stacks branching from main](images/multi-stack-jj-log.png)
 
 ### Sending both stacks
 
 ```bash
 # Send both stacks at once (tips of each stack, jip resolves ancestors)
-jip s prm vu
+jip s qnv ppx
 ```
 
 jip creates 4 PRs total: 3 for stack 1 (each building on the previous), 1 for
 the docs change.
 
 ### Review feedback comes in
 
-The reviewer approves the reformat PR and merges it. They request changes to
-the bugfix and want a small tweak to the feature.
+The reviewer requests changes to the user store (PR #2) — they want a `List`
+method added.
 
 ```bash
-# Fix the bugfix commit
-jj new plx
-# ... make changes ...
-jj squash
-
-# Fix the feature commit
-jj new prm
-# ... make changes ...
+# Fix the user store commit
+jj new pkn
+# ... add List method ...
 jj squash
 
-# Fetch the merged reformat PR and rebase
-jj git fetch
-jj rebase -o main
-
 # Update all PRs (jip posts comments showing what changed)
-jip s prm vu
+jip s qnv ppx
 
 # Or combine rebase + send in one step
-jip s --rebase prm vu
+jip s --rebase qnv ppx
 ```
 
-The reformat PR is already merged, so jip skips it. The bugfix PR now targets
-`main` directly (since its parent was merged). The feature PR is rebased on
-top. Reviewers see comments showing exactly what changed.
+The user store PR (#2) gets a comment showing the added `List` method. The API
+endpoint PR (#3) is rebased but its content didn't change. The data model PR
+(#1) is unaffected. Reviewers see comments showing exactly what changed.
 
 ### Continuing the cycle
 
-The reviewer approves and merges the bugfix PR:
+The reviewer approves and merges the data model PR (#1):
 
 ```bash
 jj git fetch
@@ -148,8 +125,8 @@ jip s -x main::
 jip s -x --rebase main::
 ```
 
-Now only the feature PR remains, targeting `main` directly. The stack
-shortened itself one PR at a time.
+Now the user store PR targets `main` directly. The stack shortened itself one
+PR at a time.
 
 Meanwhile the docs PR was reviewed and merged independently — it was never
 part of the same stack.
@@ -193,6 +170,10 @@ jj squash
 jip s
 ```
 
+jip posts a comment on the updated PR showing exactly what changed:
+
+![Interdiff comment showing exactly what changed since the last push](images/interdiff-comment.png)
+
 ### How do I add a new commit to an existing stack?
 
 Use `jj new` to insert a commit at the right position:
@@ -226,3 +207,5 @@ on GitHub. The remaining commit's PR is updated normally.
 
 Yes. If your revset resolves to a single commit, jip creates a single PR with
 no stack navigation in the description.
+
+![A single-commit PR with no stack navigation](images/independent-pr.png)