fix: refine

Author: cdcabrera

guidelines/skills/add-docs-links/SKILL.md

@@ -7,7 +7,9 @@ description: Maintains the PatternFly MCP documentation catalog in src/docs.json
 
 ## When to use
 
-User wants to **add**, **change**, or **remove** rows in `src/docs.json`, or fix broken / unreachable catalog links. They may paste **any GitHub URL** (blob or raw); you convert blob → raw, pick refs, verify reachability, shape entries, update `meta` and `generated`, and run tests.
+- User wants to **add**, **change**, or **remove** rows in `src/docs.json`, or fix broken / unreachable catalog links
+- User provides a GitHub URL (blob or raw) to register in the catalog — convert blob → raw, pick refs, verify reachability, shape entries, update `meta` and `generated`, and run tests
+- User asks to update or fix `docs.json` entries, contribute to the docs catalog, or align with docs.json tests and CI audit
 
 For **edits or removals**: find the row by `path` and/or its `docs` key; update `meta` / `generated`; run tests. Same rules as adds: whitelist, unique `path`, and `src/__tests__/docs.json.test.ts` (including `baseHashes`).
 
@@ -20,7 +22,7 @@ For **edits or removals**: find the row by `path` and/or its `docs` key; update
    - New ref for an existing repo: resolve SHA (e.g. commits API) or use a stable tag.
 
 2. **Whitelist**
-   - `path` must match `patternflyOptions.urlWhitelist` in `src/options.defaults.ts`. See [reference.md](reference.md#url-whitelist-allowed-domains). Use **https** only. Do not widen the whitelist in a catalog-only PR.
+   - `path` must match `patternflyOptions.urlWhitelist` in `src/options.defaults.ts`. See [reference.md — URL whitelist](reference.md#url-whitelist-allowed-domains). Use **https** only. Do not widen the whitelist in a catalog-only PR.
 
 3. **Reachability**
    - Response must be 2xx (e.g. `curl -sI -o /dev/null -w "%{http_code}" "<url>"`). If not, fix ref or path; do not add a dead link.
@@ -47,6 +49,10 @@ For **edits or removals**: find the row by `path` and/or its `docs` key; update
 
 **CI:** `.github/workflows/audit.yml` on PRs that touch `src/docs.json` or `tests/audit/**`.
 
+## Additional resources
+
+- [reference.md](reference.md) — entry format, top-level structure, URL whitelist, duplicate check, ref lookup, unit test constraints, example entry
+
 ## Quick checks
 
 - [ ] Blob → raw; ref reused per repo when possible.

guidelines/skills/add-docs-links/reference.md

@@ -1,4 +1,4 @@
-# docs.json Reference
+# Add docs links — Reference (PatternFly MCP)
 
 ## File location
 

guidelines/skills/review-zod-integration/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: review-zod-integration
-description: Reviews Zod dependency upgrades for PatternFly MCP—maps release notes to codebase usage, runs tests, and writes a dated update report with impact tables and prioritized fixes. Use when bumping zod, reviewing zod integration, assessing Zod breaking changes, generating a zod update report, or reviewing Dependabot/Renovate zod PRs.
+description: Reviews Zod dependency upgrades for PatternFly MCP—maps release notes to codebase usage, runs tests, and writes a dated update report with impact tables and prioritized fixes. Use when bumping zod, on review zod, zod upgrade, zod integration review, assessing Zod breaking changes, generating a zod update report, or reviewing Dependabot/Renovate zod PRs.
 ---
 
 # Review Zod Integration (PatternFly MCP)
@@ -62,6 +62,10 @@ description: Reviews Zod dependency upgrades for PatternFly MCP—maps release n
 
 Domain context (SDK routing, schema pipeline, peer range): [reference.md — Quick PF MCP facts](reference.md#quick-pf-mcp-facts).
 
+## Additional resources
+
+- [reference.md](reference.md) — grep patterns, key files, priority rules, compatibility policy, report template, example impact rows, architecture notes
+
 ## Quick checks
 
 - [ ] Versions (from → to) and release notes captured (or offline limitation noted)

guidelines/skills/review-zod-integration/reference.md

@@ -1,4 +1,4 @@
-# Review Zod Integration — Reference (PatternFly MCP)
+# Review Zod integration — Reference (PatternFly MCP)
 
 ## Quick PF MCP facts
 
@@ -70,7 +70,7 @@ If release notes only mention these, impact is usually **None**:
 | `zod` | Direct production dep; use native `fromJSONSchema` / `toJSONSchema` (not `zod-to-json-schema` in app code) |
 | `@modelcontextprotocol/sdk` | Depends on / peers `zod ^3.25 \|\| ^4.0` |
 
-## Audit Depth Policy
+## Audit depth policy
 
 | Source | Frequency | Objective |
 | :--- | :--- | :--- |
@@ -271,19 +271,19 @@ No release-note item maps to APIs used in PF MCP hot paths; unit, e2e, and audit
 
 ## Architecture
 
-### SDK Routing Trigger
+### SDK routing trigger
 The MCP SDK requires `inputSchema` to be a Zod instance to route `(args, context)` to tool handlers. We rehydrate minimal Zod in the parent process (via `normalizeInputSchema`) specifically to trigger this signature, while keeping genuine validation in the isolated child process.
 
-## Compatibility Policy (Zod Detection)
+## Compatibility policy (Zod detection)
 
 To support a diverse plugin ecosystem, PatternFly MCP maintains a "Compatibility-First" approach for Zod schema detection.
 
-### Preservation Rules:
+### Preservation rules
 1. **Never Remove `_def` Detection**: Even when pinned to Zod 4+, the `isZodSchema` function in `src/server.schema.ts` must keep the `_def` check to support plugins using Zod v3.
 2. **Additive Detection**: When Zod introduces new public APIs (like `.def` in v4.4), add detection for them *alongside* existing internal brands (`_zod`, `_def`).
 3. **Exceptions**: Legacy detection should only be removed if the Zod release notes indicate that a legacy property (e.g., `_def`) has been repurposed in a way that causes false positives or crashes in the current version.
 
-### Updated P2 Recommendations (Recurring):
+### Updated P2 recommendations (recurring)
 These items MUST be included in the "Recommended Fixes (P2)" section of the report for any Zod 4.4+ review to ensure long-term health, even if they are not strictly required for the current bump to "pass."
 
 - **DO**: Add detection for the public `.def` property (Zod 4.4+).