Document overview and command reference in README

README.md

@@ -4,6 +4,59 @@ general usage. If you're feeling adventurous, you're welcome to build the projec
 yourself with the current list of [issues](https://github.com/mattprecious/stacker/issues) and
 [git-reflog](https://git-scm.com/docs/git-reflog).
 
+## Overview
+
+Stacker (`st`) is a command-line tool for working with **stacked branches** — small, dependent branches layered on top
+of one another, each with its own pull request. Instead of putting a large change into a single branch and PR, you split
+it into a stack of focused branches, keep building without waiting for review, and let Stacker keep the stack in order.
+
+Stacker maintains its own record of the parent/child relationship between branches, forming a tree rooted at your
+**trunk** (e.g. `main`). When a branch low in the stack changes — because you amended it, or it merged — Stacker
+restacks the branches above it by rebasing them in the correct order. A **trailing-trunk** workflow is also supported,
+where you branch off a separate base branch while still targeting trunk with your pull requests.
+
+Pull requests are created and updated directly through the GitHub API (authenticated via OAuth device code); Stacker
+does not shell out to the `gh` CLI.
+
+## Commands
+
+Run `st <command> --help` for the full set of options on any command. Most commands have a short alias, and aliases
+compose down the command tree, so `st branch checkout` can also be written `st b co` or simply `st bco`.
+
+### `repo` (`r`) — repository setup and maintenance
+* `init` — interactively select your trunk branch (and, optionally, a trailing trunk). Run this once before using any
+  other command.
+* `sync` (`s`) — pull trunk, then walk the tracked branches and offer to delete any whose pull request has been merged
+  or closed.
+
+### `branch` (`b`) — everyday branch operations
+* `create` (`c`) — create a new branch on top of the current one and start tracking it.
+* `track` (`tr`) / `untrack` (`ut`) — start or stop tracking an existing branch in the stack.
+* `checkout` (`co`) — check out a branch, chosen interactively from the stack or passed by name.
+* `up` (`u`) / `down` (`d`) — move one branch up or down the stack.
+* `top` (`t`) / `bottom` (`b`) — jump to the top or bottom of the current stack.
+* `rename` (`rn`) / `delete` (`dl`) — rename or delete a tracked branch.
+* `restack` (`r`) — rebase the current branch onto its parent.
+* `submit` (`s`) — push the current branch and open or update its pull request.
+
+### `upstack` (`us`) — the current branch and everything above it
+* `onto` (`o`) — re-parent the current branch onto a different branch, then restack everything above it.
+* `restack` (`r`) — restack the current branch and all of its descendants.
+
+### `downstack` (`ds`) — the current branch and everything below it
+* `edit` (`e`) — interactively reorder, untrack, remove, or delete branches in the current stack (down to
+  trunk), then re-parent and restack them.
+
+### `stack` (`s`) — the entire stack
+* `submit` (`s`) — push every branch in the current stack and open or update all of their pull requests.
+
+### `log` (`l`) — visualize the stack
+* `short` (`s`) — print the stack as a tree, marking any branches that need a restack.
+
+### `rebase` — recover from a restack that hit conflicts
+* `--continue` — resume the in-progress restack after resolving conflicts.
+* `--abort` — abort the in-progress restack.
+
 ## Development
 
 ### Building