@silverassist/agents-toolkit 2.5.0 → 2.6.0

package/templates/shared/skills/domain-driven-design/SKILL.md

@@ -25,9 +25,9 @@ This skill provides guidelines for organizing code following Domain-Driven Desig
 
 ### ❌ DON'T
 
-- Create generic folders like "helpers", "services", "utils" at root level
+- Create generic folders like `src/helpers/`, `src/services/`, or `src/utils/` directly under `src/` (a scoped `src/lib/utils/` for minimal cross-domain primitives is allowed)
 - Mix different domain concerns in the same folder
-- Create deeply nested folder structures (max 3 levels)
+- Create folder hierarchies deeper than 3 levels below `src/` (e.g., `src/components/auth/login-form/` is allowed; `src/components/auth/login-form/subform/` is not)
 - Use abbreviations in folder names
 
 ## Project Structure
@@ -228,7 +228,7 @@ Ask these questions to identify domains:
 ### ❌ Generic Folder Anti-Patterns
 
 ```
-# ❌ BAD: Generic folders
+# ❌ BAD: Generic folders at src/ root
 src/
 ├── components/
 ├── helpers/        # What kind of helpers?
@@ -237,6 +237,11 @@ src/
 └── types/          # Types should live with their domain
 ```
 
+### Shared TypeScript Types
+
+- If a type is used by **3 or more domains**, place it in `src/lib/types/` — the shared-types exception lives under the allowed `src/lib/` scope, **not** a generic `src/types/` root (which the anti-pattern above forbids). Export it from that folder's own barrel (`src/lib/types/index.ts`) and import it as `@/lib/types`. A centrally shared primitive has **no owning domain**, so do not route it through a domain barrel — that would invert the intended dependency direction (domains → shared, never shared → a domain).
+- Otherwise, **colocate the type with its primary domain** (e.g., `src/lib/payment/types.ts`, `src/components/auth/types.ts`) and re-export it through that domain's barrel when other domains need it.
+
 ### ✅ Domain-Oriented Structure
 
 ```

package/templates/shared/skills/github-review-management/SKILL.md

@@ -0,0 +1,215 @@
+---
+name: github-review-management
+description: Fetch, reply to, resolve, and close GitHub pull-request review threads with the gh CLI and GraphQL API. Use when handling Copilot or human PR reviews end-to-end.
+---
+
+# Silver Assist — GitHub Review Management
+
+Reference knowledge for clearing GitHub pull-request reviews programmatically. This skill
+backs the `/resolve-github-reviews` prompt: it explains the data model, which API does what,
+the exact commands, and the Copilot-specific edge cases. Use it when a PR has review threads
+(Copilot or human) that need to be addressed, replied to, resolved, and verified to `0`.
+
+## When to Use
+
+- A PR has open Copilot or human review comments to clear before merge
+- You need to **resolve** review threads (not just reply) — which REST cannot do
+- Debugging why a reply or resolve call fails (404 on replies, permissions on the mutation)
+- Handling Copilot suppressed / low-confidence notes or `isOutdated` threads
+- Automating the "reply → resolve → assert 0 unresolved" loop across per-commit review rounds
+
+## The data model (get this right first)
+
+GitHub exposes three distinct things — conflating them is the usual source of bugs:
+
+| Concept | What it is | API surface |
+|---------|-----------|-------------|
+| **Review (submission)** | The top-level verdict on a PR: `APPROVED` / `CHANGES_REQUESTED` / `COMMENTED` | `gh pr review`, REST `/pulls/{n}/reviews` |
+| **Review comment** | A single inline comment anchored to a file/line (has a `databaseId`) | REST `/pulls/{n}/comments` |
+| **Review thread** | An inline comment **plus its replies**, carrying the `isResolved` flag | **GraphQL `reviewThreads` only** |
+
+Only **threads** have `isResolved`, and **only GraphQL can flip it**. The REST comments API
+lists and replies to comments but has no concept of resolving.
+
+## Which API does what
+
+| Operation | API | Command |
+|-----------|-----|---------|
+| List unresolved threads | GraphQL | `reviewThreads(first:100){ nodes{ id isResolved path line comments(first:1){ nodes{ databaseId } } } }` |
+| Reply to a thread | REST | `POST /pulls/{n}/comments/{comment_id}/replies` |
+| Reply fallback (404) | REST | `POST /pulls/{n}/comments` with `in_reply_to={comment_id}` |
+| Acknowledge suppressed notes | REST | `gh pr comment {n} --body "…"` (PR-level) |
+| **Resolve a thread** | **GraphQL** | `resolveReviewThread(input:{threadId:$id})` |
+| Verify 0 unresolved | GraphQL | re-query `reviewThreads`, count `isResolved == false` |
+
+## Resolve locations
+
+```bash
+REPO_SLUG=$(gh repo view --json nameWithOwner -q .nameWithOwner)   # owner/repo
+OWNER=${REPO_SLUG%/*}; REPO=${REPO_SLUG#*/}
+PR=$(gh pr view --json number -q .number)                          # current branch's PR
+```
+
+## 1. List unresolved threads (paginated)
+
+A PR can have more than 100 threads, so a single `first:100` page is not enough. Walk the
+connection with `pageInfo { endCursor hasNextPage }` and collect every node before filtering.
+
+```bash
+> /tmp/review-threads.jsonl
+CURSOR=null
+while : ; do
+  # First page: there is no cursor yet ($CURSOR is the string "null"). Passing it as
+  # `-f after="null"` would send the literal string "null" — an invalid cursor, not a
+  # "start from the beginning" signal. Omit `after` on this pass so the query starts at the
+  # beginning; pass the real endCursor afterward. (gh's typed `-F after=null` instead sends
+  # a real GraphQL null.)
+  if [ "$CURSOR" = "null" ]; then
+    AFTER_ARGS=()
+  else
+    AFTER_ARGS=(-f after="$CURSOR")
+  fi
+  PAGE=$(gh api graphql -F owner="$OWNER" -F repo="$REPO" -F pr="$PR" "${AFTER_ARGS[@]}" -f query='
+    query($owner:String!, $repo:String!, $pr:Int!, $after:String) {
+      repository(owner:$owner, name:$repo) {
+        pullRequest(number:$pr) {
+          reviewThreads(first:100, after:$after) {
+            pageInfo { endCursor hasNextPage }
+            nodes {
+              id
+              isResolved
+              isOutdated
+              path
+              line
+              comments(first:1) { nodes { databaseId body author { login } } }
+            }
+          }
+        }
+      }
+    }')
+  # Fail fast: a GraphQL/auth/network error must not be mistaken for "no threads".
+  if ! echo "$PAGE" | jq -e '.data.repository.pullRequest.reviewThreads' >/dev/null 2>&1; then
+    echo "ERROR: GraphQL request failed or returned an unexpected shape:" >&2
+    echo "$PAGE" >&2
+    exit 1
+  fi
+  echo "$PAGE" | jq -c '.data.repository.pullRequest.reviewThreads.nodes[]' >> /tmp/review-threads.jsonl
+  HAS_NEXT=$(echo "$PAGE" | jq -r '.data.repository.pullRequest.reviewThreads.pageInfo.hasNextPage')
+  CURSOR=$(echo "$PAGE" | jq -r '.data.repository.pullRequest.reviewThreads.pageInfo.endCursor')
+  [ "$HAS_NEXT" = "true" ] || break
+done
+
+jq -r '
+  select(.isResolved == false)
+  | "\(.id)\t\(.comments.nodes[0].databaseId)\t\(.path):\(.line)"
+' /tmp/review-threads.jsonl
+```
+
+Each row gives `threadId` (to resolve) and `commentId` = `databaseId` (to reply). A `null`
+`databaseId` marks a suppressed note — see below.
+
+## 2. Reply to a thread
+
+```bash
+# Primary: reply directly on the thread.
+gh api "repos/$OWNER/$REPO/pulls/$PR/comments/$COMMENT_ID/replies" \
+  -f body="Fixed in <sha>: <what changed>."
+
+# Fallback when the replies endpoint 404s: link via in_reply_to.
+gh api "repos/$OWNER/$REPO/pulls/$PR/comments" \
+  -f body="Fixed in <sha>: <what changed>." \
+  -F in_reply_to="$COMMENT_ID"
+```
+
+## 3. Resolve the thread (GraphQL — the only way)
+
+```bash
+gh api graphql -f id="$THREAD_ID" -f query='
+  mutation($id:ID!) {
+    resolveReviewThread(input:{threadId:$id}) {
+      thread { isResolved }
+    }
+  }'
+```
+
+Batch all addressed threads:
+
+```bash
+for THREAD_ID in $THREAD_IDS; do
+  gh api graphql -f id="$THREAD_ID" -f query='mutation($id:ID!){ resolveReviewThread(input:{threadId:$id}){ thread { isResolved } } }'
+done
+```
+
+> To reopen a thread (rarely needed), the counterpart mutation is `unresolveReviewThread`.
+
+## 4. Verify 0 unresolved (the close-the-loop check)
+
+```bash
+> /tmp/review-threads-remaining.jsonl
+CURSOR=null
+while : ; do
+  if [ "$CURSOR" = "null" ]; then
+    AFTER_ARGS=()
+  else
+    AFTER_ARGS=(-f after="$CURSOR")
+  fi
+  PAGE=$(gh api graphql -F owner="$OWNER" -F repo="$REPO" -F pr="$PR" "${AFTER_ARGS[@]}" -f query='
+    query($owner:String!, $repo:String!, $pr:Int!, $after:String) {
+      repository(owner:$owner, name:$repo) {
+        pullRequest(number:$pr) {
+          reviewThreads(first:100, after:$after) {
+            pageInfo { endCursor hasNextPage }
+            nodes { isResolved }
+          }
+        }
+      }
+    }')
+  # Fail fast: a GraphQL/auth/network error must not be mistaken for "0 remaining".
+  if ! echo "$PAGE" | jq -e '.data.repository.pullRequest.reviewThreads' >/dev/null 2>&1; then
+    echo "ERROR: GraphQL request failed or returned an unexpected shape:" >&2
+    echo "$PAGE" >&2
+    exit 1
+  fi
+  echo "$PAGE" | jq -c '.data.repository.pullRequest.reviewThreads.nodes[]' >> /tmp/review-threads-remaining.jsonl
+  HAS_NEXT=$(echo "$PAGE" | jq -r '.data.repository.pullRequest.reviewThreads.pageInfo.hasNextPage')
+  CURSOR=$(echo "$PAGE" | jq -r '.data.repository.pullRequest.reviewThreads.pageInfo.endCursor')
+  [ "$HAS_NEXT" = "true" ] || break
+done
+
+REMAINING=$(jq -s '[.[] | select(.isResolved == false)] | length' /tmp/review-threads-remaining.jsonl)
+if [ "$REMAINING" -eq 0 ]; then
+  echo "✅ all resolved"
+else
+  echo "❌ $REMAINING remaining"
+  exit 1
+fi
+```
+
+> If `isResolved` remains `false` immediately after a successful `resolveReviewThread`
+> mutation, wait 2–3 seconds and re-query — GitHub's GraphQL API can exhibit brief
+> consistency lag after bulk resolves, so a thread already resolved server-side may
+> still report as open on the next read.
+
+## Copilot-specific handling
+
+- **Suppressed / low-confidence notes** — Copilot posts some findings without an inline comment
+  (`databaseId` is `null`), so there is **no inline comment to reply to**. The thread itself still
+  has an `id` and is resolvable — acknowledge the note with a single PR-level comment
+  (`gh pr comment`), then resolve the thread by its `id` like any other.
+- **`isOutdated` threads** — when the underlying code moves, the thread is flagged `isOutdated`
+  but remains **unresolved**. It never clears itself; resolve it explicitly once handled.
+- **Per-commit review rounds** — Copilot re-reviews after each push, potentially opening new
+  threads. Re-run list → reply → resolve → verify until the count is `0`. Trigger a fresh pass
+  with `gh pr comment $PR --body "@copilot review"` (unquoted `$PR` — it is the integer PR
+  number set earlier via `gh pr view --json number -q .number`, and `gh pr comment` takes
+  it as a positional argument, not a string flag value).
+
+## Common failures
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Resolve mutation returns a permissions error | Token lacks `repo` scope | Re-auth: `gh auth refresh -s repo` |
+| `POST …/replies` → 404 | Thread doesn't accept direct replies | Use `in_reply_to` fallback |
+| Reply "works" but thread stays open | Replied via REST, never resolved | Run the GraphQL `resolveReviewThread` |
+| `pr` variable rejected by GraphQL | Passed as a string | Use `-F pr="$PR"` (typed) not `-f pr=...` |
+| Count never reaches 0 | New round opened threads | Re-run the loop after each push |

package/templates/shared/skills/nextjs-caching/SKILL.md

@@ -5,7 +5,7 @@ description: Caching strategy for Next.js (App Router) frontends consuming the C
 
 # Next.js Caching Skill
 
-Canonical caching strategy for Silver Side Next.js (App Router) frontends. Use it when touching data
+Canonical caching strategy for Silver Assist Side Next.js (App Router) frontends. Use it when touching data
 fetching, route segment configs, the asset/page proxy, image config, or the on-demand revalidate
 route — and when diagnosing "why isn't this page cached / why is it serving stale".
 
@@ -18,8 +18,14 @@ route — and when diagnosing "why isn't this page cached / why is it serving st
 ## Core principle
 
 **Cache by intent (read vs. mutation), never by the HTTP method.** Some reads must use `POST` because
-they take a body (e.g. CCDS `geo-search`). They still have to cache like a `GET`. Mutations must never
-cache. Getting this wrong silently turns a static page into a per-request dynamic render.
+they take a body (e.g. CCDS `geo-search`). Their *data* still has to cache like a `GET` — send
+`next: { revalidate, tags }`, never `no-store`. Mutations must never cache.
+
+**But caching the data is not the same as making the page static.** A POST read caches its response
+cross-request, yet Next.js still renders the *route* dynamically (`private, no-store`). The data-fetch
+cache (layer 2) and the route's static/dynamic classification (layers 1/5) are **independent** — see
+the two sections below. This is the WEB-1069 gotcha and the reason city/community pages needed an edge
+override even though their fetches were already cached.
 
 ---
 
@@ -41,20 +47,54 @@ whole route into **dynamic rendering**, which emits `cache-control: private, no-
 
 ---
 
-## How Next.js 16 actually decides (the rule behind the rule)
-
-From `next/dist/server/lib/patch-fetch.js`:
-
-- `fetch` is **not cached by default**. A non-`GET` method is "uncacheable" **only when no explicit
-  cache config is provided**. Concretely, a POST is auto-no-cached only when it has no `next`/`cache`
-  options *and* the segment `revalidate` is `0`.
-- Therefore **a `POST` IS cached cross-request when you pass an explicit `next: { revalidate }`** (and
-  the segment isn't `revalidate: 0`). This is why the WordPress GraphQL POST caches fine.
-- The **request body is part of the cache key** (`incremental-cache` → `generateCacheKey` hashes
-  `init.body`), so different filter bodies cache independently and never collide.
-
-**Implication:** you do **not** need `unstable_cache` or a proxy header override to cache POST reads.
-Just send `next: { revalidate, tags }`.
+## POST reads: the data caches, but the route stays dynamic (the key gotcha)
+
+Two independent facts, both true:
+
+1. **The data fetch caches.** From `next/dist/server/lib/patch-fetch.js`: a `fetch` is uncacheable
+   only when it has no `next`/`cache` options *and* the segment `revalidate` is `0`. So a POST **with**
+   `next: { revalidate }` IS cached cross-request — the **request body is part of the cache key**
+   (`generateCacheKey` hashes `init.body`), so different filter bodies cache independently. This is
+   real and bounds origin/CCDS load; it is why the WordPress GraphQL POST caches fine.
+
+2. **The route still renders dynamically.** Empirically (WEB-1069, Next 16), a page whose data comes
+   from a POST read prerenders as `ƒ` (Dynamic) and serves `cache-control: private, no-store` — **even
+   with** `next: { revalidate, tags }` on the fetch. Next treats the POST as request-time data for
+   prerendering, so ISR (layer 1) never engages. GET reads do not have this problem — they ISR
+   natively (`s-maxage`, `x-nextjs-cache: HIT`).
+
+**Implication:** `next: { revalidate, tags }` on a POST read is **necessary** (data cache) but **not
+sufficient** to make the page CDN-cacheable. You must additionally pick a rendering/edge strategy
+(next section). `revalidate` + `tags` alone will NOT flip a POST-read page from `private, no-store` to
+`public`.
+
+## Making a POST-read page cacheable (rendering / edge layer)
+
+Pick one (ordered by risk, lowest first):
+
+1. **CDN edge override (current, lowest risk).** `src/proxy.ts` matches the city/community paths and
+   sets `Cache-Control: public, s-maxage=2592000, stale-while-revalidate=2592000` — the **same**
+   header the ISR pages emit (see `expireTime` under ISR tiers), so the CDN policy is uniform across
+   static and dynamic routes. The origin stays dynamic; the CDN caches the deterministic-per-URL
+   response. Per-repo regex, no build-time risk — this is what WEB-1069 shipped. **Requires:** a
+   per-repo path regex in `src/proxy.ts` that matches exactly the routes you want cached **and**
+   those routes must be **public and deterministic per URL** — no auth-, cookie-, or session-
+   dependent output. A `public` edge cache serves one stored response to *every* visitor, so a
+   personalized route matched here would leak one user's content to others. Never match
+   authenticated or personalized paths.
+2. **`export const dynamic = "force-static"` (interim).** Forces the POST read to `force-cache` and
+   prerenders the route as real ISR (confirmed via `prerender-manifest.json`). Removed in WEB-1058
+   because a CCDS failure at build time cached a **blank page**; safer now that reads throw on 5xx at
+   runtime (a failed revalidation keeps the last good cache), but full prerender is sensitive to
+   null/bad records. **Requires:** the page is fully null-safe (every field access guarded); the read
+   throws on failure **at build/prerender time too** (not only during runtime revalidation) so a failed
+   read aborts generation instead of prerendering a cacheable blank/error page — the exact WEB-1058
+   regression; AND the client throws on 5xx at runtime (so ISR keeps the previous version instead of
+   caching an error). Re-validate this per repository before adopting the strategy.
+3. **`cacheComponents: true` + `use cache` (strategic).** Wrap the POST read in `use cache` so its data
+   lands in the static shell (PPR). Next-recommended long term; larger migration. **Requires:** a
+   deliberate PPR migration for the whole route segment; do **not** mix ad hoc with route-segment
+   `export const revalidate` (the two models conflict).
 
 ---
 
@@ -76,7 +116,7 @@ export async function fetchData<T>({
   method = "GET",
   body = null,
   revalidateTag,
-  revalidate = 86400, // 24h time-based fallback; pair with tags for surgical invalidation
+  revalidate = 2592000, // 30d time-based fallback; pair with tags for surgical invalidation
   mutation = false,
 }: FetchOptions): Promise<T | null> {
   const isMutation = mutation || method === "PUT" || method === "DELETE";
@@ -116,18 +156,33 @@ await fetch(WP_API_URL, {
 
 ## ISR revalidate tiers
 
-| Route type | `export const revalidate` |
-|------------|---------------------------|
-| Listing / index | `2592000` (30d) — webhook handles freshness |
-| Detail / city / community (`[slug]`) | `86400` (24h) |
-| State / advisor landing | `604800` (7d) |
-| WP catch-all (`[[...uri]]`) | `604800` (7d) |
+CCDS/WP data changes rarely and is refreshed on-demand via webhooks + tags, so the time-based default
+is intentionally **long** (WEB-1069):
+
+| Route / config | Value |
+|----------------|-------|
+| CCDS reads (client default) | `2592000` (30d) |
+| WordPress GraphQL reads (`WP_CACHE_DURATIONS`) | `2592000` (30d) |
+| Listing / detail / city / community / state / landing / WP catch-all | `2592000` (30d) |
+| `next.config` `expireTime` (CDN stale window) | `5184000` (60d) → emits `s-maxage=2592000, stale-while-revalidate=2592000` |
+| `next.config` image `minimumCacheTTL` | `31536000` (1y) — optimized images are content-hashed, never change |
 
 - Every cacheable route exports `revalidate`. Do **not** add it to form/personalized routes.
-- Prefer `export const revalidate` over `dynamic = "force-static"`: a failed ISR revalidation then
+- **`expireTime` sets the CDN stale window.** Next emits `s-maxage=<revalidate>,
+  stale-while-revalidate=<expireTime − revalidate>` for ISR pages, so `expireTime` **must be ≥ the
+  largest `revalidate`** or the stale window is invalid (the WEB-1069 bug: `expireTime: 86400` under a
+  30d revalidate). Set it to `5184000` (60d) so a 30d page yields the same header the proxy sets on
+  dynamic pages: `s-maxage=2592000, stale-while-revalidate=2592000`.
+- The long default is safe because a missed webhook still self-heals within 30d; use `tags` for
+  immediate surgical invalidation. Shorter tiers (24h/7d) are appropriate per-route when the data
+  source updates more frequently than the 30d default — for example, sources that update daily or
+  weekly. Sources that update less frequently than 30d should keep the default.
+- Default to `export const revalidate` over `dynamic = "force-static"`: a failed ISR revalidation then
   preserves the last good cache instead of overwriting it with a broken page. Pair with a client that
   **throws on 5xx at runtime** (so ISR keeps the previous version) but returns an error during the
-  build phase (so `generateStaticParams` can skip a bad entry without failing the build).
+  build phase (so `generateStaticParams` can skip a bad entry without failing the build). `force-static`
+  is still a valid POST-read option (see "Making a POST-read page cacheable") **once** the page is
+  fully null-safe and the throw-on-5xx guard is in place.
 
 ---
 
@@ -142,17 +197,24 @@ revalidateTag(tag);                  // granular per-state / per-city tags
 if (invalidateCDN) await invalidateCloudFrontPaths([path]);
 ```
 
+If `invalidateCloudFrontPaths` throws, log the error and surface it to the caller — do **not**
+silently swallow it. The Next.js cache will be fresh but the CDN will serve stale until its TTL
+expires; an operator must retry the CloudFront invalidation manually.
+
 ---
 
 ## Anti-patterns
 
-- ❌ `next: method === "GET" ? {...} : { revalidate: 0 }` — leaves POST reads uncached → the route
-  renders dynamically (`private, no-store`). This is the exact regression that broke city pages.
+- ❌ `next: method === "GET" ? {...} : { revalidate: 0 }` — leaves POST reads uncached (origin hit
+  every render). Note: even a *correctly* cached POST read still renders the route dynamically — that
+  needs an edge override, not just `next` options (see "Making a POST-read page cacheable").
 - ❌ Bare `fetch(url, { method: "POST", body })` for a read — refetched from origin every render.
 - ❌ `next: { tags }` with no `revalidate` — holds stale data or doesn't cache at runtime.
 - ❌ Caching a mutation (`submit`, lead, `PUT`/`DELETE`/`PATCH`).
 - ❌ Treating `React.cache()` as cross-request caching (it's request-scoped dedup only).
-- ❌ `dynamic = "force-static"` on a page whose revalidation can fail (caches a broken page).
+- ❌ `dynamic = "force-static"` on a page that is **not** fully null-safe or lacks throw-on-5xx — a bad
+  CCDS record/response at build time caches a broken/blank page (the WEB-1058 regression). It is a
+  valid option only once those guards exist.
 - ❌ Mixing `cacheComponents: true` (`"use cache"`) with route-segment `export const revalidate` —
   that is a separate, deliberate migration; do not introduce it ad hoc.
 
@@ -180,5 +242,12 @@ curl -sI https://<host>/<care-type>/<state>/<city> | grep -i cache-control
 ```
 
 In the build output, `●` (or "Static"/"ISR") means prerendered; `ƒ` ("Dynamic") means it renders per
-request — a POST-read page should be the former. `next.config` `logging.fetches.fullUrl: true` shows
-per-fetch cache decisions in dev.
+request. Which one to expect depends on the strategy chosen in "Making a POST-read page cacheable":
+strategy **2** (`force-static`) prerenders fully, so it shows `●`; strategy **3** (`use cache` / PPR)
+shows `●` only when the whole route is static — if dynamic holes remain it renders as a **partial
+prerender** and Next marks it `◐` (partial), which is still correct output, so do not reject it.
+Strategy **1** (CDN edge override) intentionally leaves the route as `ƒ` — the page is CDN-cached at
+the edge even though Next classifies it as dynamic. Because the symbol alone is ambiguous across
+strategies, verify with the `curl -sI … | grep -i cache-control` check above and defer to the
+installed Next.js version's build-output legend rather than the symbol. `next.config`
+`logging.fetches.fullUrl: true` shows per-fetch cache decisions in dev.

package/templates/shared/skills/release-management/SKILL.md

@@ -41,7 +41,7 @@ plugin-slug/
 
 ### Key Principles
 
-1. **Unified scripts** — `build-release.sh` and `release.yml` are identical across all 6 plugins.
+1. **Unified scripts** — `build-release.sh` and `release.yml` are structurally identical across all 6 plugins. The only permitted per-plugin variation is the Silver Assist package validation block at the end of `build-release.sh` (see [Validation Checks](#validation-checks)), which may omit checks for packages the plugin does not depend on.
 2. **Selective copy** — Only runtime files go into the ZIP (no tests, docs, dev configs).
 3. **Auto-detection** — The build script finds the main plugin file, slug, and version automatically.
 4. **Checksums** — Every ZIP gets MD5 and SHA-256 checksums.
@@ -80,13 +80,21 @@ git push origin v1.3.6
 
 ### Step 1: Update All Versions
 
-Use whichever version script the plugin has:
+**Selection is driven by which script the plugin ships — each plugin ships exactly one variant**,
+and `release.yml` auto-detects the same way (it runs `update-version.sh` if present, else
+`update-version-simple.sh`). Manual runs and CI therefore stay consistent *because only one script
+exists per plugin*; never ship both, or CI's preference for `update-version.sh` would silently
+diverge from a manual `update-version-simple.sh` run.
+
+- Full variant (`update-version.sh`): `acf-clone-fields`, `silver-assist-post-revalidate`, `silver-assist-security`.
+- Simple variant (`update-version-simple.sh`): `contact-form-to-api`, `leadgen-app-form`, `nextjs-graphql-hooks`.
+- New plugin: ship **only** `update-version-simple.sh` unless it genuinely needs the full variant.
 
 ```bash
 # Full variant (acf-clone-fields, silver-assist-post-revalidate, silver-assist-security)
 ./scripts/update-version.sh 1.2.0 --no-confirm --force
 
-# Simple variant (contact-form-to-api, leadgen-app-form, nextjs-graphql-hooks)
+# Simple variant (contact-form-to-api, leadgen-app-form, nextjs-graphql-hooks, new plugins by default)
 ./scripts/update-version-simple.sh 1.2.0 --no-confirm --force
 ```
 
@@ -165,7 +173,7 @@ gh run watch <run-id> --exit-status
 
 ## Unified Build Script (`scripts/build-release.sh`)
 
-This script is **identical** across all Silver Assist plugins. When setting up a new plugin, copy it verbatim.
+This script is **structurally identical** across all Silver Assist plugins. When setting up a new plugin, copy it and change only the dependency-specific asset-validation checks a plugin does not need — the single allowed per-plugin variation, documented below (see the Silver Assist package-asset table and [Key Principles](#key-principles)). Everything else must remain identical; copying it verbatim for a plugin that lacks one of those dependencies would leave an invalid validation check that fails its release build.
 
 ### What It Does
 
@@ -406,7 +414,7 @@ The build script validates these Silver Assist package assets exist in the final
 | Settings Hub CSS | `vendor/silverassist/wp-settings-hub/assets/css/settings-hub.css` |
 | GitHub Updater JS | `vendor/silverassist/wp-github-updater/assets/js/check-updates.js` |
 
-If the plugin does NOT use these packages, remove the corresponding validation checks.
+If the plugin does NOT depend on one of these packages, omit only that package's validation check when creating the plugin's `build-release.sh`. This is the single allowed per-plugin variation of the script (see [Key Principles](#key-principles)); everything else must remain identical to the template above.
 
 ---
 
@@ -429,6 +437,14 @@ on:
         description: 'Version to release (e.g. 1.2.0). Leave empty to use plugin file version.'
         required: false
 
+# Note: `workflow_dispatch` still performs a REAL release — the "Create GitHub Release"
+# step below publishes the release and creates the `v<version>` tag if it does not
+# already exist. It is NOT a dry run. Use it only to release a version whose source is
+# already committed on the checked-out ref: the "Update version" step edits files inside
+# the CI checkout without committing them back, so an uncommitted bump would ship a ZIP
+# that differs from the repository. For a true dry run, run the build steps in a separate
+# non-publishing workflow that omits the "Create GitHub Release" step.
+
 permissions:
   contents: write
 
@@ -457,6 +473,10 @@ jobs:
           else
             VERSION=$(grep -o 'Version: [0-9]\+\.[0-9]\+\.[0-9]\+' *.php 2>/dev/null | head -1 | cut -d' ' -f2)
           fi
+          if [ -z "$VERSION" ]; then
+            echo "::error::Could not detect version: no tag, no manual input, and no Version: header found in root PHP files."
+            exit 1
+          fi
           echo "version=$VERSION" >> $GITHUB_OUTPUT
           echo "🏷️ Version: $VERSION"
 

package/templates/shared/skills/testing-patterns/SKILL.md

@@ -75,6 +75,24 @@ jest.mock('stripe', () => ({
 
 ## Server Action Testing Pattern
 
+### Mocking `next/navigation`
+
+Server Actions that call `redirect()` or use routing helpers require `next/navigation` to be mocked, since it is not available in the Jest test environment.
+
+```typescript
+// Mock next/navigation BEFORE imports.
+// redirect() must THROW like the real implementation — Next signals a redirect by throwing
+// NEXT_REDIRECT to terminate the action's control flow. A plain `jest.fn()` no-op would let
+// code after redirect() keep running, producing outcomes impossible in production. Throw a
+// sentinel and assert on it (e.g. `await expect(action()).rejects.toThrow(/NEXT_REDIRECT/)`).
+jest.mock('next/navigation', () => ({
+  redirect: jest.fn((url) => {
+    throw new Error(`NEXT_REDIRECT: ${url}`);
+  }),
+  useRouter: jest.fn(() => ({ push: jest.fn() })),
+}));
+```
+
 ### Basic Server Action Test
 
 ```typescript
@@ -113,6 +131,26 @@ describe('submitWizardToSalesforce', () => {
     expect(result.success).toBe(true);
     expect(result.leadId).toBeDefined();
   });
+
+  it('should return failure state when the API rejects', async () => {
+    // Simulate an error thrown by the mocked dependency
+    mockCreateLead.mockRejectedValue(new Error('API error'));
+
+    const formData = new FormData();
+    formData.append('email', 'test@example.com');
+    formData.append('firstName', 'John');
+
+    const result = await submitWizardToSalesforce(
+      { success: false, message: '', timestamp: 0 },
+      formData
+    );
+
+    // Assert the error path for THIS action: it catches the API failure and returns a
+    // failure state. Match the action's own contract — actions that instead throw (e.g.
+    // via redirect(), see the mock above) must be asserted with `rejects.toThrow(...)`.
+    expect(result.success).toBe(false);
+    expect(result.message).toContain('error');
+  });
 });
 ```