feat(skills): pf-4236 zod integration reports (#206)

* review-zod-integration, review zod release notes, audit use, propose updates
* add-docs-links, minor alignment updates for skill consistency

Author: cdcabrera

.gitignore

@@ -61,3 +61,6 @@ coverage/
 # agent
 .archive
 .agent
+reports/
+.output.txt
+poc/

cspell.config.json

@@ -12,10 +12,12 @@
     "onsessioninitialized",
     "onsessionclosed",
     "patternfly",
+    "prefault",
     "rereview",
     "rsort",
     "sparkline",
     "streamable",
+    "treeify",
     "unrepresentable",
     "unsub"
   ]

guidelines/README.md

@@ -19,6 +19,7 @@ Agent-specific guidelines for the PatternFly MCP project, optimized for machine
 ### Skills
 
 - [Add docs links](./skills/add-docs-links/SKILL.md) - Add documentation links to `src/docs.json` in a structured way (format, duplicate check, URL confirmation, tests)
+- [Review Zod integration](./skills/review-zod-integration/SKILL.md) - Review Zod dependency bumps, map release notes to PF MCP, run tests, write `reports/YYYYMMDD-HHMMSS-zod-{semver}-update-report.md` (UTC)
 
 **Note:** `guidelines/skills/` is the canonical location for skills. Repo symlinks point here so agents can discover them: `.agents/skills` (Cursor), `.claude/skills` (Claude). The `.agent/` directory (no “s”) is reserved for each developer’s local work and is off limits—do not use it for shared skills or guidelines.
 
@@ -36,6 +37,7 @@ Agents should use these phrases as signals to consult specific documentation and
 | **"review development guide"**      | Review `docs/development.md` for CLI, API, and plugin authoring.                                                                                       |
 | **"create an example tool plugin"** | Review `guidelines/agent_coding.md`, `docs/development.md`, `docs/examples/*`, and `src/*` for context, coding standards, and existing example formats. |
 | **"add documentation links"** / **"add doc entries"** / **"register docs"** / **"update docs.json"** / **"contribute to docs.json"** | Follow `guidelines/skills/add-docs-links/SKILL.md`: docs.json format, duplicate check, raw URL confirmation, then run unit tests and update meta. |
+| **"review zod"** / **"zod upgrade"** / **"zod integration review"** / **"zod update report"** | Follow `guidelines/skills/review-zod-integration/SKILL.md`: release notes vs codebase, tests, report at `reports/YYYYMMDD-HHMMSS-zod-{semver}-update-report.md` (UTC). |
 | **"troubleshoot server"** / **"debug server"** | Review `docs/usage.md#troubleshooting` and the PatternFly MCP server resource `patternfly://context` |
 
 ## Guidelines Processing Order

guidelines/agent_coding.md

@@ -155,7 +155,7 @@ Centralized utilities in `server.helpers.ts`, `server.schema.ts`, and `server.ge
 - **Helpers**: Use `stringJoin.newline()`, `freezeObject()`, `timeoutFunction()`, and `mergeObjects()`.
 - **Schemas**: Use `normalizeInputSchema(schema)` to convert JSON Schema or Zod shapes into valid Zod instances.
 - **Type Guards**: Use `isPlainObject()`, `isZodSchema()`, and `isErrorLike()` for runtime narrowing.
-- **Zod Detection**: Robustly detect Zod schemas by checking for internal brands: `_def` for Zod v3 and `_zod` for Zod v4. Avoid relying solely on `parse()` or `safeParse()` methods.
+- **Zod Detection**: Robustly detect Zod schemas by checking for the public `.def` property (Zod v4+) or internal brands: `_zod` (v4) and `_def` (v3). Avoid relying solely on `parse()` or `safeParse()` methods.
 - **Immutability**: Options and Session objects are **frozen**; use `structuredClone()` before modification.
 
 ### 3.5 Validation and Sanitization

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

@@ -0,0 +1,77 @@
+---
+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, 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)
+
+## When to use
+
+- User bumps or proposes bumping **`zod`** in `package.json`
+- User asks for a **Zod upgrade review**, **integration review**, or **impact analysis**
+- Dependabot/Renovate PR for `zod`
+- User wants a report comparing **Zod release notes** to this codebase
+
+## Workflow
+
+1. **Versions and release notes**
+   - Read `package.json`, `package-lock.json`, and `node_modules/zod/package.json` if installed.
+   - Note **previous** version from `git log -1 -- package.json` or the bump PR/commit.
+   - Fetch release notes for the target minor/major (release page, GitHub API, packaged changelog, or any fetch tool): `https://github.com/colinhacks/zod/releases/tag/v{VERSION}`.
+   - For patch bumps within the same minor (e.g. 4.4.1 → 4.4.3), use the **minor** release notes (e.g. v4.4.0) plus patch-specific notes when present.
+   - **Offline fallback:** If release notes cannot be retrieved, state that limitation and continue from `package.json`, lockfile, and the inventory/audit steps only.
+   - Extract **potentially breaking**, **other fixes**, **performance**, and **locales** sections.
+   - If notes are ambiguous or the bump is minor/major, follow [reference.md — Audit depth policy](reference.md#audit-depth-policy) (prefer `node_modules/zod/src/` when shipped; otherwise published entry points from `package.json` `exports`).
+
+2. **Repo guidelines**
+   - Read (do not paste into the report): `CONTRIBUTING.md`, `guidelines/agent_coding.md`, `guidelines/agent_testing.md`, `docs/development.md`.
+
+3. **Codebase inventory**
+   - Run all commands in [reference.md — Grep patterns](reference.md#grep-patterns). Read [reference.md — Key files](reference.md#key-files).
+   - Record **used** vs **not used** per release-note item.
+   - Apply [reference.md — Compatibility policy (Zod detection)](reference.md#compatibility-policy-zod-detection): new detection must be **additive**; do not remove `_def` or v3 paths unless release notes show a concrete conflict.
+
+4. **Impact matrix**
+   - For **every** release-note bullet (breaking, fixes, performance, locales), add one row to the report tables. Columns: **Release note**, **Used in PF MCP?** (Yes / No / Indirect — cite file or grep), **Impact** (None / Low / Medium / High), **Priority**, **Recommended fix** (or `None`). Priority rules: [reference.md — Priority rules](reference.md#priority-rules-pf-mcp).
+   - Always include [reference.md — Updated P2 recommendations (Recurring)](reference.md#updated-p2-recommendations-recurring) in the report **Recommended fixes** section, even when tests pass.
+   - Row patterns: [reference.md — Example impact rows](reference.md#example-impact-rows-pf-mcp).
+
+5. **Tests**
+   From repo root:
+
+   ```bash
+   npm run test:types
+   npx jest --selectProjects unit
+   npm run test:integration
+   npm run test:audit
+   ```
+
+   - Record pass/fail counts. Full `npm test` may fail on `auditor/` ESLint—treat as pre-existing unless the bump touched `auditor/`.
+   - **P0 (tests/types/runtime break):** Document failures in the report. Apply only minimal fixes needed to verify bump safety, re-run tests, and note any changes. Update snapshots only when output change is correct (`jest -u` scoped to affected files).
+   - **P1 / P2:** Do not change code during this review—list fixes in the report only.
+
+6. **Write the report**
+   - **Directory:** `reports/` at repository root (gitignored). Run `mkdir -p reports` if needed; do not delete prior reports.
+   - **Filename:** `YYYYMMDD-HHMMSS-zod-{semver}-update-report.md` (`YYYYMMDD-HHMMSS` = report timestamp in **UTC**, 24-hour, no separators in the time part; `{semver}` = target version without `v`, e.g. `reports/20260522-143045-zod-4.4.3-update-report.md`).
+   - Use [reference.md — Report template](reference.md#report-template). Do not commit unless the user asks.
+
+7. **User summary**
+   - Report path; **executive summary verdict table** from the report (code changes required, documentation updates required, risk level—do not collapse to a single line); P0/P1/P2 counts; link to release notes.
+   - Ask: *"Would you like me to proceed with the recommended P1/P2 fixes listed in the report?"*
+   - Do not modify the codebase further until the user explicitly grants permission (except minimal P0 fixes from step 5).
+
+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 read; inventory grep run; compatibility policy applied
+- [ ] Every release-note bullet mapped with priority
+- [ ] Recurring P2s in report consolidated fixes
+- [ ] `test:types`, unit, `test:integration`, `test:audit` recorded
+- [ ] Report at `reports/YYYYMMDD-HHMMSS-zod-{semver}-update-report.md` (UTC)
+- [ ] User asked before any P1/P2 code changes