@silverassist/agents-toolkit 2.5.1 → 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".
 
@@ -76,15 +76,25 @@ Pick one (ordered by risk, lowest first):
    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.
+   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 — keep the page fully null-safe and validate per repo before adopting.
+   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 — do **not** mix ad
-   hoc with route-segment `export const revalidate`.
+   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).
 
 ---
 
@@ -164,7 +174,9 @@ is intentionally **long** (WEB-1069):
   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 fine per-route if a source is volatile.
+  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
@@ -185,6 +197,10 @@ 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
@@ -226,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');
+  });
 });
 ```
 

package/templates/shared/skills/tsdoc-standards/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: tsdoc-standards
+description: Write and enforce TSDoc (not JSDoc) in TypeScript. Use when adding or reviewing doc comments on functions, components, interfaces, or file headers. Covers allowed tags, forbidden JSDoc patterns, and templates.
+---
+
+# Silver Assist — TSDoc Standards
+
+This skill is the deep reference for writing and reviewing documentation comments in
+TypeScript. All doc comments follow the **[TSDoc](https://tsdoc.org/)** standard — **not
+JSDoc**. The enforced, always-on rules live in `tsdoc-standards.instructions.md`
+(`applyTo: "**/*.{ts,tsx}"`); this skill adds the *why*, expanded examples, and a review
+checklist for on-demand use.
+
+## When to Use
+
+- Adding doc comments to functions, Server Actions, React components, hooks, or utilities
+- Documenting interfaces, types, enums, or module/file headers
+- Reviewing a PR and deciding whether a comment is TSDoc-correct
+- Migrating an existing file from JSDoc (`{type}` braces, `@template`, `@module`) to TSDoc
+- Answering "which tag do I use for X?" or "is `@fileoverview` allowed?"
+
+## Why TSDoc, not JSDoc
+
+TypeScript already carries the type information. JSDoc duplicates it in `{braces}`, which:
+
+- **Drifts** — the `{string}` in the comment and the `: string` in the signature diverge over time.
+- **Is redundant** — editors and `tsc` read the real types; the comment adds nothing.
+- **Breaks API extractors** — tools like [API Extractor](https://api-extractor.com/) and the
+  TSDoc parser reject JSDoc-only tags (`@typedef`, `@callback`, `@fileoverview`).
+
+TSDoc keeps prose in the comment and types in the code — one source of truth for each.
+
+## Core Rules (with rationale)
+
+### 1. No type annotations in `@param` / `@returns`
+
+The type is in the signature; the comment describes *meaning*, not *type*.
+
+```typescript
+// ❌ JSDoc — the {string} duplicates the signature
+/** @param {string} slug - Community slug */
+
+// ✅ TSDoc — hyphen required after the name; no braces
+/** @param slug - Community slug */
+```
+
+### 2. `@typeParam` for generics (not `@template`)
+
+```typescript
+// ❌ @template is a JSDoc/Closure tag
+/** @template T */
+
+// ✅ TSDoc generic parameter
+/** @typeParam T - The item shape returned by the fetcher */
+```
+
+### 3. `@packageDocumentation` for file/module headers (not `@module`)
+
+Place it in the **first** comment of the file. It marks module-level docs for extractors.
+
+```typescript
+/**
+ * @packageDocumentation
+ * CCDS geo-search utilities for state, city, and community lookups.
+ */
+```
+
+### 4. Document interface members inline (not `@property`)
+
+Each member gets its own leading comment — it shows on hover for that specific field.
+
+```typescript
+interface Community {
+  /** The community name. */
+  name: string;
+  /** The city where the community is located. */
+  city: string;
+  /** @defaultValue `false` */
+  featured?: boolean;
+}
+```
+
+### 5. Overloaded functions — document each overload signature
+
+For overloaded functions, place the TSDoc comment on **each overload signature individually**.
+Do **not** place it on the implementation signature — tooling (editors, `tsc`, API extractors)
+will not surface it to consumers, who only see the overload signatures.
+
+```typescript
+// ✅ TSDoc on each overload; implementation signature is undocumented
+/**
+ * Fetches a community by its slug.
+ *
+ * @param slug - The community slug
+ * @returns The matching community, or `undefined`
+ */
+export function getCommunity(slug: string): Community | undefined;
+/**
+ * Fetches a community by its numeric ID.
+ *
+ * @param id - The community ID
+ * @returns The matching community, or `undefined`
+ */
+export function getCommunity(id: number): Community | undefined;
+export function getCommunity(key: string | number): Community | undefined {
+  // implementation
+}
+```
+
+## Allowed Tags — quick reference
+
+| Tag | Format | Notes |
+|-----|--------|-------|
+| `@param` | `@param name - Description` | Hyphen required; no type braces |
+| `@returns` | `@returns Description` | No type braces |
+| `@remarks` | Block | Extended description / side effects |
+| `@example` | Block | Fenced code (` ```typescript `) |
+| `@throws` | Block | Documented exceptions |
+| `@see` | Block | Cross-reference or URL |
+| `@deprecated` | Block | Add migration guidance |
+| `@defaultValue` | Block | Default of a property |
+| `@typeParam` | `@typeParam T - Description` | Generic parameter |
+| `@packageDocumentation` | Modifier | First comment in the file |
+| `{@link symbol}` | Inline | Hyperlink to a symbol |
+
+> `@param` / `@returns` are **optional** — add them only when they add clarity (non-obvious
+> params, complex return shapes). Never add them to interfaces, types, or constants.
+
+## Templates
+
+### Server Action
+
+````typescript
+/**
+ * Submits the contact form and sends a notification email.
+ *
+ * @remarks
+ * Validates server-side, creates a DB record, dispatches email.
+ *
+ * @param formData - Submitted form data from the contact page
+ *
+ * @throws When the email service is unavailable
+ */
+export async function submitContactForm(formData: FormData): Promise<void> {}
+````
+
+### React Component
+
+````typescript
+/**
+ * Renders a responsive community card with name and location.
+ *
+ * @returns The community card JSX element
+ *
+ * @example
+ * ```tsx
+ * <CommunityCard community={community} className="mt-4" />
+ * ```
+ */
+export function CommunityCard({ community, className }: CommunityCardProps) {
+  return <article className={className}>{community.name}</article>;
+}
+````
+
+### Utility Function
+
+````typescript
+/**
+ * Formats a date string for display.
+ *
+ * @param dateString - ISO 8601 date string
+ * @returns Human-readable date (e.g., "January 15, 2025")
+ *
+ * @example
+ * ```typescript
+ * formatDate("2025-01-15"); // "January 15, 2025"
+ * ```
+ */
+export function formatDate(dateString: string): string {
+  return new Date(dateString).toLocaleDateString("en-US", { dateStyle: "long" });
+}
+````
+
+### Generic Utility (`@typeParam`)
+
+````typescript
+/**
+ * Returns the first element matching the predicate, or `undefined`.
+ *
+ * @typeParam T - The element type of the array
+ * @param items - The array to search
+ * @param predicate - Returns `true` for the desired element
+ * @returns The first matching element, or `undefined` if none match
+ */
+export function findFirst<T>(items: T[], predicate: (item: T) => boolean): T | undefined {
+  return items.find(predicate);
+}
+````
+
+## Forbidden Patterns → Fixes
+
+| ❌ Forbidden (JSDoc) | ✅ TSDoc fix |
+|----------------------|--------------|
+| `@param {string} name` | `@param name` |
+| `@returns {boolean} …` | `@returns …` |
+| `@template T` | `@typeParam T` |
+| `@module path/to/mod` | `@packageDocumentation` |
+| `@fileoverview …` | `@packageDocumentation` |
+| `@typedef {Object} X` | Define a TypeScript `interface`/`type` |
+| `@callback X` | Define a TypeScript function type |
+| `@type {X}` | Annotate the value: `const x: X = …` |
+| `@property {T} name` | Inline `/** … */` on the interface member |
+| `@function` / `@async` / `@class` / `@enum` | Remove — redundant with TypeScript |
+
+## Review Checklist
+
+When reviewing doc comments, confirm:
+
+- [ ] No `{type}` braces in `@param` / `@returns`.
+- [ ] `@param name - Description` uses the hyphen and matches the actual parameter name.
+- [ ] Generics use `@typeParam`, not `@template`.
+- [ ] File-level docs use `@packageDocumentation` in the first comment, not `@module` / `@fileoverview`.
+- [ ] Interface/type members are documented inline, not via `@property`.
+- [ ] No redundant `@function` / `@async` / `@class` / `@enum` / `@typedef` / `@callback` / `@type`.
+- [ ] `@param` / `@returns` are present only where they add real clarity.