docs: record render-diagram export + release-pipeline gotchas

CLAUDE.md

@@ -124,6 +124,11 @@ Releases are automated via GitHub Actions on push to main (`.github/workflows/re
 - **Preview locally:** `devflow release` shows what the next release would be
 - **Manual bump:** `devflow version-bump <version>` updates all version files locally
 
+**Release pipeline gotchas (fixed in v0.2.0 — do not reintroduce):**
+- `bump-version.sh` runs under `set -o pipefail`. `check_version_consistency` (lib/watch.sh) greps each command file for a `[devflow v]` badge; that grep pipeline MUST be guarded with `|| true` — no command carries the badge, so an unguarded grep returns 1 and `set -e` aborts the whole release silently (right after "All version files updated", before `make release`).
+- release.yml must create an **annotated** tag (`git tag -a "v$X" -m ...`). `git push --follow-tags` does NOT push lightweight tags, which leaves `gh release create` failing with "tag exists locally but has not been pushed".
+- To release an already-merged commit that used `[skip release]`: `gh workflow run release.yml -f bump_override=<minor|patch|major>` (the dispatch override bypasses the skip / "none" detection).
+
 ### Auto-Reinstall
 
 When `devflow watch setup` is run in the devflow source repo, it offers an auto-reinstall opt-in:

devflow-plugin/commands/render-diagram.md

@@ -71,4 +71,12 @@ When the diagram belongs in a doc (spec, ADR, walkthrough, README):
 
 Never embed the raw `.excalidraw` JSON in prose, and never rely on a markdown embed for in-session display — that is what Step 4's Read is for.
 
+## Maintenance notes (export pipeline)
+
+`devflow visualizations render` → `lib/excalidraw-export.cjs` depends on three GLOBAL npm packages: `canvas`, `excalidraw-to-svg`, `@resvg/resvg-js`. If you touch this path:
+- **node ≥ 25 requires `canvas@3+`** — `canvas@2` has no node-25 prebuilt (source build fails); `canvas@3.2.3+` ships a prebuilt binary.
+- **`excalidraw-to-svg` reads `@excalidraw/utils` via a CWD-relative path** (`./node_modules/@excalidraw/utils/dist/excalidraw-utils.min.js`); with globally-installed deps the CLI passes `EXCAL_NODE_MODULES=$(npm root -g)` and the script `chdir`s to the dir whose `node_modules` holds it.
+- **Global deps resolve via `NODE_PATH` — CommonJS `require` only, NOT ESM `import`** (this is why the script is `.cjs`).
+- Don't suppress the `getContext` error — it signals a missing/misconfigured `canvas` (a real failure), unlike the cosmetic "Could not load img" jsdom warnings which are filtered.
+
 $ARGUMENTS

devflow-plugin/skills/render-diagram/SKILL.md

@@ -72,4 +72,12 @@ When the diagram belongs in a doc (spec, ADR, walkthrough, README):
 
 Never embed the raw `.excalidraw` JSON in prose, and never rely on a markdown embed for in-session display — that is what Step 4's Read is for.
 
+## Maintenance notes (export pipeline)
+
+`devflow visualizations render` → `lib/excalidraw-export.cjs` depends on three GLOBAL npm packages: `canvas`, `excalidraw-to-svg`, `@resvg/resvg-js`. If you touch this path:
+- **node ≥ 25 requires `canvas@3+`** — `canvas@2` has no node-25 prebuilt (source build fails); `canvas@3.2.3+` ships a prebuilt binary.
+- **`excalidraw-to-svg` reads `@excalidraw/utils` via a CWD-relative path** (`./node_modules/@excalidraw/utils/dist/excalidraw-utils.min.js`); with globally-installed deps the CLI passes `EXCAL_NODE_MODULES=$(npm root -g)` and the script `chdir`s to the dir whose `node_modules` holds it.
+- **Global deps resolve via `NODE_PATH` — CommonJS `require` only, NOT ESM `import`** (this is why the script is `.cjs`).
+- Don't suppress the `getContext` error — it signals a missing/misconfigured `canvas` (a real failure), unlike the cosmetic "Could not load img" jsdom warnings which are filtered.
+
 $ARGUMENTS

skills/render-diagram/SKILL.md

@@ -72,4 +72,12 @@ When the diagram belongs in a doc (spec, ADR, walkthrough, README):
 
 Never embed the raw `.excalidraw` JSON in prose, and never rely on a markdown embed for in-session display — that is what Step 4's Read is for.
 
+## Maintenance notes (export pipeline)
+
+`devflow visualizations render` → `lib/excalidraw-export.cjs` depends on three GLOBAL npm packages: `canvas`, `excalidraw-to-svg`, `@resvg/resvg-js`. If you touch this path:
+- **node ≥ 25 requires `canvas@3+`** — `canvas@2` has no node-25 prebuilt (source build fails); `canvas@3.2.3+` ships a prebuilt binary.
+- **`excalidraw-to-svg` reads `@excalidraw/utils` via a CWD-relative path** (`./node_modules/@excalidraw/utils/dist/excalidraw-utils.min.js`); with globally-installed deps the CLI passes `EXCAL_NODE_MODULES=$(npm root -g)` and the script `chdir`s to the dir whose `node_modules` holds it.
+- **Global deps resolve via `NODE_PATH` — CommonJS `require` only, NOT ESM `import`** (this is why the script is `.cjs`).
+- Don't suppress the `getContext` error — it signals a missing/misconfigured `canvas` (a real failure), unlike the cosmetic "Could not load img" jsdom warnings which are filtered.
+
 $ARGUMENTS