fkclaude: bring the docs up to date with what was actually submitted

The review runbook still said "nothing has been pushed yet" and explained how to open the PRs.
They are open, so it now leads with their state - four PRs against oltaco, two changes prepared
and deliberately held back, and the separate MeshCore PR - and the submission section records how
it was done rather than how it would be.

Two things from that section are worth having written down. gh is not installed system-wide; a
portable copy sits at D:\FkDev\GHcli and authenticates from the Git Credential Manager token. And
gh pr edit fails on that token because it goes through GraphQL, which wants read:org even to change
a body - the REST path works with the plain repo scope.

Adds fcl_HowTo_release_and_ci.md for the release machinery, all of it established by running it on
the fork: the workflow builds on release creation only, so pull requests get no CI at all upstream;
the tag name lands in all 42 asset names, in INFO_UF2.TXT and in the BLE firmware revision string;
the workflow is taken from the tagged commit rather than the default branch, so CI changes can be
tested without touching master; and a fork's default_workflow_permissions is read, which lets every
board build and then fails the upload with "Resource not accessible by integration".

Also records the mistake that cannot be undone: #NN in a commit message on a fork creates a
permanent referenced event on the upstream PR, showing the commit subject. Two internal commits
leaked working notes into oltaco#47 and oltaco#50 that way. Rewriting the messages stops new ones; the existing
events stay, and the orphaned commits remain fetchable by SHA.

Author: fkallay1

fkclaude/fcl_HowTo_release_and_ci.md

@@ -0,0 +1,82 @@
+# Releases and CI - how the automation actually behaves
+
+Everything here was established by running it, on `fkallay1/Adafruit_nRF52_Bootloader_OTAFIX`
+(2026-07-28/29). Nothing was tried against `oltaco`.
+
+## What builds, and when
+
+`.github/workflows/githubci.yml` builds **on release creation only**:
+
+```yaml
+on:
+  #  pull_request:
+  #  push:
+  release:
+    types: [created]
+```
+
+`push` and `pull_request` are commented out, which has one consequence worth knowing before you
+send anything upstream: **pull requests get no CI at all there.** No maintainer sees a green
+check on our PRs, so the measured results written into the PR bodies are the only evidence
+offered.
+
+On a release it generates the board matrix from `src/boards/*` (14 boards today), builds each on
+a GitHub-hosted `ubuntu-latest` runner with ARM GCC 12.3.Rel1 - nothing runs locally - and
+attaches three files per board: `<board>_bootloader-*.zip`, `*.hex`, and
+`update-<board>_bootloader-*_nosd.uf2`. 14 x 3 = the 42 assets each upstream release has.
+
+## Cutting a release
+
+```sh
+GH=/d/FkDev/GHcli/bin/gh.exe
+export GH_TOKEN=$(printf "protocol=https\nhost=github.com\n\n" | git credential fill | sed -n 's/^password=//p')
+"$GH" release create <tag> -R fkallay1/Adafruit_nRF52_Bootloader_OTAFIX \
+  --target <branch> --title "<tag>" --notes "..."
+```
+
+Four things that will bite:
+
+**The tag names the artifacts.** The version comes from `git describe`, so it lands in all 42
+asset names *and* in `INFO_UF2.TXT` on the device *and* in `BLEDIS_FW_VERSION` (the Firmware
+Revision in the BLE Device Information Service). Tag the exact commit you mean - anywhere else
+and you get `-<n>-g<sha>` glued into every filename. Do not invent a version number: follow the
+upstream scheme, e.g. `0.9.2-OTAFIX2.2-BP1.3-dfu-recovery-v1`, which says what it is without
+claiming to be 0.9.3.
+
+**Releases are repo-level, their content is per-commit.** One list of releases for the repo, but
+each is pinned to a tag, and that tag can sit on any branch. Building a release from a feature
+branch is normal.
+
+**The workflow comes from the tagged commit, not from the default branch.** Measured: `master`
+pinned `checkout@v4` while the tagged branch pinned `@v7`, and `@v7` is what ran. So CI changes
+can be tested without touching `master`.
+
+**`default_workflow_permissions` must be `write`.** A fork defaults to `read`, and then every
+board builds fine and the last step dies with `Resource not accessible by integration` - which
+reads like a code failure and is not:
+
+```sh
+"$GH" api repos/OWNER/REPO/actions/permissions/workflow --method PUT -f default_workflow_permissions=write
+```
+
+Also: `release: types: [created]` does not reliably fire when you publish a saved **draft**.
+Create the release directly, not draft-then-publish.
+
+## The Node deprecation
+
+Every job used to carry `Node 20 is deprecated ... forced to run on Node.js 24`. That is a
+warning, not an error - the run is green and the assets appear. But when the fallback is
+withdrawn, as it was for Node 12 and 16, the steps will not start, and with `pull_request`
+disabled the first sign would be a release producing nothing.
+
+The actions were three majors behind, and the Node version does **not** track the major:
+
+| action | was | Node | now | Node |
+|---|---|---|---|---|
+| `actions/checkout` | v4 | node20 | v7 | node24 |
+| `actions/upload-artifact` | v4 | node20 | v7 | node24 (v5 is *still* node20 - v6 is the first that helps) |
+| `softprops/action-gh-release` | v1 | **node16** | v3 | node24 |
+
+Bumped on `feature/serial-dfu-auto-recovery` and verified by a release: 14 boards, 42 assets, and
+the annotation gone from every job. The same four-line change is staged for upstream as
+`feature/ci-node24-actions` - see `fkclaude/docs/upstream-prs/ci-node24-actions.*`.

fkclaude/fcl_HowTo_review_upstream_prs.md

@@ -1,8 +1,24 @@
-# How to review the four upstream PRs before they are sent
+# The upstream submissions - what is out there, and how to follow up
 
-Everything for the review is in **`fkclaude/docs/upstream-prs/`** - one `.diff` (the code) and
-one `.msg.md` (the commit message, which is also the PR description) per PR. Nothing has been
-pushed yet; the branches exist only locally.
+**Submitted 2026-07-28.** The four bootloader PRs are open against `oltaco`, and two further
+changes are prepared but deliberately not sent. Current state:
+
+| what | where | status |
+|---|---|---|
+| recover serial/USB DFU after a failed flash | [oltaco #47](https://github.com/oltaco/Adafruit_nRF52_Bootloader_OTAFIX/pull/47) | open, `mergeable=clean` |
+| reboot when a started transfer goes silent | [oltaco #48](https://github.com/oltaco/Adafruit_nRF52_Bootloader_OTAFIX/pull/48) | open, `mergeable=clean` |
+| accept a new session after an interrupted transfer | [oltaco #49](https://github.com/oltaco/Adafruit_nRF52_Bootloader_OTAFIX/pull/49) | open, `mergeable=clean` |
+| serial reboot command (`DFU_REBOOT_PACKET`) | [oltaco #50](https://github.com/oltaco/Adafruit_nRF52_Bootloader_OTAFIX/pull/50) | open, `mergeable=clean` |
+| CI onto Node 24 actions | branch `feature/ci-node24-actions` | **prepared, not sent** |
+| touch 2400 for UF2 mode | `adafruit/Adafruit_TinyUSB_Arduino`, branch in the scratchpad | **prepared, not sent** |
+| serial CLI lockup (a separate project) | [meshcore-dev #2978](https://github.com/meshcore-dev/MeshCore/pull/2978) | open since 2026-07-18, nudged |
+
+Each PR cross-references the other three in order of importance, and #47/#48 are linked to
+upstream issues #40 and #41 with `Related to` - deliberately not `Fixes`, since neither issue is
+fully answered. Comments explaining what is and is not covered are posted under both issues.
+
+Everything for reading them is in **`fkclaude/docs/upstream-prs/`** - one `.diff` (the code) and
+one `.msg.md` (the commit message, which is also the PR description) per change.
 
 Related: `fkclaude/fcl_readme_dfu_recovery.md` (what the changes do), `fkclaude/scripts/README.md`
 (the test rig), `fkclaude/docs/2026-07-28-dfu-recovery-investigation.md` (how it was diagnosed,
@@ -143,30 +159,50 @@ transiently (the PR 2 stall timeout is the backstop), and the nRF52832 path is c
 this fork - no board here selects a non-nRF52840 MCU - so PR 2's effect on it is argued
 arithmetically, not measured.
 
-## Step 5 - when you approve, this is what gets run
+## Step 5 - how these were submitted, and how to follow up
 
-Nothing below has been run yet.
+`gh` is **not installed system-wide**; a portable copy lives at `D:\FkDev\GHcli\bin\gh.exe`
+(v2.96.0, plain zip, no installer). It authenticates from the Git Credential Manager token:
 
 ```sh
-for b in dfu-recover-on-usb dfu-stall-timeout dfu-retry-after-abort dfu-serial-reboot-command; do
-  git push -u origin feature/$b
-done
-
-gh pr create --repo oltaco/Adafruit_nRF52_Bootloader_OTAFIX --base dev \
+GH=/d/FkDev/GHcli/bin/gh.exe
+export GH_TOKEN=$(printf "protocol=https\nhost=github.com\n\n" | git credential fill | sed -n 's/^password=//p')
+"$GH" pr create -R oltaco/Adafruit_nRF52_Bootloader_OTAFIX --base dev \
   --head fkallay1:feature/dfu-recover-on-usb \
-  --title "dfu: recover serial/USB DFU automatically after a failed flash" \
-  --body-file fkclaude/docs/upstream-prs/dfu-recover-on-usb.msg.md
+  --title "$(git log -1 --format=%s feature/dfu-recover-on-usb)" \
+  --body-file fkclaude/docs/upstream-prs/dfu-recover-on-usb.body
 ```
 
-...and the same for the other three. Two notes on the `gh` calls:
+Two things that cost time and are worth keeping:
 
-- `--body-file` would include the subject line as the first line of the body. Strip it, or pass
-  `--title` and a body file without the first two lines.
-- Open PR 1 first and reference it from the others, so the maintainer sees the intended reading
-  order.
+- The body must not repeat the title. Split the commit message: `--format=%s` for the title,
+  `--format=%b` for the body.
+- **`gh pr edit` fails on this token** - it goes through GraphQL, which demands the `read:org`
+  scope even to change a body. The REST path works with the plain `repo` scope:
+  `gh api repos/OWNER/REPO/pulls/N --method PATCH --input payload.json`.
 
-## If you want a change
+To push a change to an open PR, commit on the branch and push normally - the PR follows the
+branch. The branches are regenerated from pristine `upstream/dev` by a script rather than
+edited in place, so a wording or code change means rebuilding that one branch; the other three
+keep their SHAs.
+
+## A mistake worth not repeating
+
+**Never write `#NN` in a commit message on a branch pushed to this fork.** The fork is in
+`oltaco`'s fork network, so GitHub turns every `#NN` in a pushed commit into a `referenced`
+event on that upstream PR, with the commit subject on display. Two internal `fkclaude:` commits
+mentioning `#47` and `#50` therefore leaked working notes into the timelines of PR #47 and #50.
+
+It cannot be undone. Rewriting the messages and force-pushing stops *new* references, but the
+events already recorded stay - GitHub keeps them after the commit becomes unreachable, the
+orphaned commit is still fetchable by SHA so the link still opens it, and the REST API has no
+endpoint to delete a timeline event. Only GitHub Support can purge that.
+
+Write `PR 50`, not `#50`. Check before pushing:
+
+```sh
+git log --format=%B origin/master..HEAD | grep -oE '#[0-9]+'
+```
 
-Say which PR and what should differ. The branches are regenerated from pristine `upstream/dev`
-by a script rather than edited in place, so a wording or code change means rebuilding that one
-branch - the other three keep their SHAs.
+File *content* is safe - a `#NN` inside a committed document creates nothing. Only commit
+messages, PR/issue bodies and comments autolink.

fkclaude/fcl_readme_dfu_recovery.md

@@ -2,8 +2,10 @@
 
 What our bootloader changes do, how the device behaves after them, and how to flash them.
 
-- Reviewing/submitting the upstream PRs: `fkclaude/fcl_HowTo_review_upstream_prs.md`
+- State of the upstream submissions, and how to follow up: `fkclaude/fcl_HowTo_review_upstream_prs.md`
+- Releases and CI, and the traps in both: `fkclaude/fcl_HowTo_release_and_ci.md`
 - Script reference for the test rig: `fkclaude/scripts/README.md`
+- Testing on a board with no debugger: `fkclaude/docs/2026-07-28-xiao-no-debugger-testing.md`
 - How it was diagnosed, including the dead ends: `fkclaude/docs/2026-07-28-dfu-recovery-investigation.md`
 - Original design brief: `esp32-s3_USBIP/fkclaude/docs/2026-07-27-bootloader-dfu-recovery-design.md`