docs: add authentication section and initial changelog

Author: wbbradley

CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+## [0.2.0] - 2026-07-06
+
+First tagged release.
+
+### Added
+- Stacked-branch management: view your stack tree (`git stack` / `status`), create stacked
+  branches (`checkout`), restack onto parents (`restack`, with `-a`/`-f`/`-p` for recursive
+  ancestor restacking, fetch, and push), diff against parent (`diff`), re-parent a branch
+  (`mount`), and delete branches (`delete`).
+- Interactive TUI status mode with up/down navigation and a current-HEAD indicator.
+- GitHub integration: `sync` (push/pull local state, auto-prune merged or duplicate branches,
+  retarget PR bases on mount) and `pr create` (opens PRs with the correct base branch).
+- GitHub authentication via `git stack auth login` (OAuth device flow or `--pat` paste),
+  `auth status`, and `auth logout`.
+- Token resolution from `GITHUB_TOKEN`, `GH_TOKEN`, `git config github.token`, or the config
+  file at `~/.config/git-stack/github.yaml`.
+- Last-resort auth fallback: borrows the `gh` CLI's token (via `gh auth token`) when no other
+  source resolves, so users already logged in with `gh` need no separate setup.
+- Shell completions.
+
+### Security
+- Config and state files are written with `0600` permissions.

README.md

@@ -76,6 +76,27 @@ git stack delete <branch>    # remove a branch from the stack
 Note that `git stack sync` will automatically prune local branches that are duplicates of the remote
 branch, or have already been merged.
 
+## Authentication
+
+Commands that talk to GitHub (`sync`, `pr create`) need a token. Set one up with:
+
+```bash
+git stack auth login         # interactive OAuth device flow (recommended)
+git stack auth login --pat   # paste a personal access token instead
+git stack auth status        # show the active auth method
+git stack auth logout        # clear git-stack's stored tokens
+```
+
+git-stack resolves a token from the first source that provides one, in order:
+
+1. `GITHUB_TOKEN` environment variable
+2. `GH_TOKEN` environment variable
+3. `git config --get github.token`
+4. Config file (`~/.config/git-stack/github.yaml`): host-specific token, then PAT, then OAuth token
+5. The [`gh` CLI](https://cli.github.com/): if none of the above resolve and you've run `gh auth
+   login`, git-stack borrows `gh`'s token automatically (via `gh auth token`). Use `gh auth logout`
+   to sign out of `gh`.
+
 ## Workflow Example
 
 ```bash