docs: add upstream-PR workflow + lnbits branch-model reference

Two new docs under docs/:

- upstream-prs.md — how to send a PR upstream using the
  ~/dev/upstream-prs/ worktree flow. Opens with a "Primer" section
  for anyone new to forks / pull requests (the three remote roles —
  upstream / github-fork / origin — explained as a table), then the
  per-project prerequisites, the prb/prc helper-driven workflow, and
  a "Common pitfalls" section.

- lnbits-upstream-flow.md — reference for how lnbits/lnbits actually
  moves: the dev/main branch split, the squash-merge PR convention,
  the non-FF release merge from dev into main, and how to read the
  history with --first-parent. Adapted from internal aiolabs notes
  with the fork-versioning specifics stripped; closing section is
  generic guidance for anyone maintaining their own long-lived fork.

README links both from a new "Further reading" section. The prior
"Contributing" section is retitled "Contributing to this scaffold"
to avoid colliding with the new upstream-PR doc on the term.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

docs/upstream-prs.md

@@ -0,0 +1,138 @@
+# Contributing back to upstream
+
+How to send fixes or features upstream (to projects like `lnbits/lnbits`)
+using the worktree-based PR flow built into this scaffold's dev-env
+layer.
+
+> **New to forks and pull requests?** Skim the [Primer](#primer) first.
+> Otherwise jump to [Workflow](#workflow).
+
+## Primer
+
+GitHub, Forgejo, Gitea, and similar services host *git repositories*.
+To contribute to a project you don't own:
+
+1. **Fork** the upstream repo via the web UI ("Fork" button). This
+   creates `<host>/<your-user>/<repo>` — your personal copy.
+2. **Branch** off your fork's `main` (or whichever branch upstream
+   accepts PRs against). Make your change.
+3. **Push** the branch to your fork.
+4. **Open a Pull Request** from your fork's branch into the upstream.
+5. **Iterate** — maintainers review, you push follow-up commits to the
+   same branch and the PR updates automatically.
+6. **Maintainer merges** — usually as a single squashed commit on
+   upstream's target branch.
+7. **Delete the branch** on both sides once merged.
+
+The three roles a remote can play in your local clone:
+
+| Remote name | What it points at | Read or write? |
+|---|---|---|
+| `upstream` | The canonical project you're contributing to | Read (you fetch from it) |
+| `github-fork` (or `fork`) | Your personal copy you push to | Write (you push to it) |
+| `origin` | Optional: a private mirror you control (forgejo / gitea / codeberg / sourcehut) | Read + write |
+
+This scaffold's `settings.nix` declares all three via `git.remotes`;
+the bootstrap script wires them into the local bare repo so every
+worktree sees the same set automatically. See
+[remotes.md](remotes.md) for topology patterns.
+
+## Prerequisites (per project)
+
+1. **Fork** the upstream repo on the relevant host.
+2. **Set your fork URL** in `settings.nix`:
+
+   ```nix
+   git.remotes.fork = "https://github.com/<your-username>/lnbits";
+   ```
+
+   Use the SSH form (`git@github.com:<your-username>/lnbits.git`) if
+   you've set up SSH push.
+
+3. **Bootstrap** (or re-bootstrap). The (planned) bootstrap script
+   adds the `github-fork` remote to the bare repo at
+   `~/dev/repos/lnbits.git`.
+
+Verify the remotes are wired:
+
+```sh
+git -C ~/dev/repos/lnbits.git remote -v
+```
+
+Expected at minimum:
+
+```
+upstream      https://github.com/lnbits/lnbits (fetch / push)
+github-fork   https://github.com/<your-user>/lnbits (fetch / push)
+```
+
+If `origin` is set, it points at your private remote (forgejo etc.).
+
+## Workflow
+
+### 1. Create the PR branch
+
+```sh
+prb lnbits fix-invoice-validation
+```
+
+The (planned) `prb` helper:
+
+- `git fetch upstream`
+- creates branch `fix-invoice-validation` off `upstream/main`
+- adds a worktree at `~/dev/upstream-prs/lnbits-fix-invoice-validation`
+- sets the worktree's push target to your fork (`github-fork`)
+
+### 2. Make changes
+
+```sh
+cd ~/dev/upstream-prs/lnbits-fix-invoice-validation
+# … edit, test, commit …
+git commit -am "Fix invoice validation for zero-amount invoices"
+```
+
+### 3. Push to your fork + open the PR
+
+```sh
+git push -u github-fork fix-invoice-validation
+```
+
+git prints a URL to open the PR. Alternatively, with the GitHub CLI:
+
+```sh
+gh pr create --base main --head <your-username>:fix-invoice-validation
+```
+
+(Use the project's preferred target branch — for `lnbits/lnbits` it's
+`dev`, not `main`. See [lnbits-upstream-flow.md](lnbits-upstream-flow.md).)
+
+### 4. Iterate on review
+
+Push more commits to the same branch — the PR updates automatically.
+Don't force-push unless you've squashed/rebased deliberately.
+
+### 5. After merge — clean up
+
+```sh
+prc lnbits fix-invoice-validation
+```
+
+The (planned) `prc` helper removes the worktree and prunes the local
+branch. On the web UI, click "Delete branch" on the merged PR to
+remove your fork's copy too.
+
+## Common pitfalls
+
+- **PR target branch.** Many projects (including `lnbits/lnbits`)
+  accept PRs against `dev`, not `main`. Read the project's
+  CONTRIBUTING file or its branch-model reference before opening.
+- **Stale branches on your fork.** They accumulate forever if you
+  don't clean up. `prc` handles the local side; the web UI handles
+  the fork side.
+- **Commits drifting onto your fork's `main`.** Keep your fork's
+  `main` strictly in lockstep with `upstream/main`. All feature
+  work lives in branches.
+- **Wrong remote when pushing.** If `git push` defaults to `upstream`
+  (because that's `origin`), you'll get an access-denied error. The
+  worktree's tracking remote should be `github-fork`; if not, set it:
+  `git branch --set-upstream-to=github-fork/<branch>`.