fix: stash

Author: cdcabrera

cspell.config.json

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

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

@@ -34,6 +34,10 @@ Copy this checklist and track progress:
    - GitHub: `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 any patch-specific notes if present.
 4. List **potentially breaking**, **other fixes**, **performance**, and **locales** sections from the release.
+5. **Implementation Audit (Conditional)**: If the release notes are ambiguous or if the upgrade involves a minor/major version bump, perform a targeted search of `node_modules/zod/src/` to verify:
+   - Persistence of internal brands (`_def`, `_zod`).
+   - Stability of "loose" or "passthrough" logic.
+   - Compatibility of the `v3` interop layer within the `v4` package.
 
 ### Step 2: Repo guidelines
 
@@ -130,6 +134,7 @@ Reply with:
 
 ## Quick PF MCP facts
 
+- **Zod is Required for SDK Routing**: Any tool registered with the MCP SDK MUST have a Zod instance for its `inputSchema` (even a minimal one like `z.any()`) to ensure the SDK passes user arguments correctly to the handler. Without it, handlers receive only a context object.
 - Internal tools **require** Zod or raw Zod shapes; JSON Schema is converted via `src/server.schema.ts`.
 - Core APIs: `fromJSONSchema`, `toJSONSchema`, `z.looseObject`, raw shapes with `.optional()` — not `z.undefined()`, `z.tuple()`, `.merge()`.
 - MCP SDK peer: `zod ^3.25 || ^4.0`.

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

@@ -55,6 +55,14 @@ 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
+
+| Source | Frequency | Objective |
+| :--- | :--- | :--- |
+| **Release Notes** | Always | Identify public API changes and security fixes. |
+| **Package Metadata** | Always | Verify peer dependencies and entry points. |
+| **Source Code Audit** | Minor/Major Bumps | Validate internal state and undocumented behavioral shifts. |
+
 ## Report template
 
 Save as: **`YYYYMMDD-zod{version}-update-report.md`** (repo root).
@@ -205,6 +213,7 @@ Use these as patterns when mapping **your** target release notes. Re-grep the co
 | Release note | Used in PF MCP? | Impact | Priority | Recommended fix |
 |--------------|-----------------|--------|----------|-----------------|
 | `fromJSONSchema()` metadata / cyclic input handling | Yes — `jsonSchemaToZod` | Low positive — plugin conversion may differ | None | Monitor plugin edge cases; no code change if tests pass |
+| **Metadata retention (round-trip preservation)** | Yes — `fromJSONSchema` / `toJSONSchema` | Low — snapshots may include extra keys | None | Update snapshots if custom keys are now preserved; no code change |
 | `z.record()` key transforms | No | None | None | None |
 | Skip `__proto__` in object catchall | Indirect — object parsing in tools/options | Low positive | None | None |
 | Empty union construction | Indirect — via JSON Schema conversion | Low positive — safer conversion | None | None |
@@ -244,6 +253,11 @@ No release-note item maps to APIs used in PF MCP hot paths; unit, e2e, and audit
 | Plugin authoring | Note in `docs/development.md`: prefer JSON Schema or Zod 4.x aligned with server |
 ```
 
+## Architecture
+
+### 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)
 
 To support a diverse plugin ecosystem, PatternFly MCP maintains a "Compatibility-First" approach for Zod schema detection.