@pyreon/mcp 0.13.1 → 0.14.0

package/lib/index.js

@@ -3,7 +3,9 @@ import Ajv from "ajv";
 import _addFormats from "ajv-formats";
 import { ZodOptional, z } from "zod";
 import process$1 from "node:process";
-import { detectReactPatterns, diagnoseError, generateContext, migrateReactCode } from "@pyreon/compiler";
+import { auditTestEnvironment, detectPyreonPatterns, detectReactPatterns, diagnoseError, formatTestAudit, generateContext, migrateReactCode } from "@pyreon/compiler";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
 
 //#region ../../../node_modules/.bun/zod@4.3.6/node_modules/zod/v3/helpers/util.js
 var util;
@@ -426,7 +428,8 @@ const handleResult = (ctx, result) => {
 			success: false,
 			get error() {
 				if (this._error) return this._error;
-				this._error = new ZodError$1(ctx.common.issues);
+				const error = new ZodError$1(ctx.common.issues);
+				this._error = error;
 				return this._error;
 			}
 		};
@@ -2114,9 +2117,10 @@ var ZodObject$1 = class ZodObject$1 extends ZodType$1 {
 	_getCached() {
 		if (this._cached !== null) return this._cached;
 		const shape = this._def.shape();
+		const keys = util.objectKeys(shape);
 		this._cached = {
 			shape,
-			keys: util.objectKeys(shape)
+			keys
 		};
 		return this._cached;
 	}
@@ -4050,38 +4054,30 @@ const _encode = (_Err) => (schema, value, _ctx) => {
 	const ctx = _ctx ? Object.assign(_ctx, { direction: "backward" }) : { direction: "backward" };
 	return _parse(_Err)(schema, value, ctx);
 };
-const encode$1 = /* @__PURE__ */ _encode($ZodRealError);
 const _decode = (_Err) => (schema, value, _ctx) => {
 	return _parse(_Err)(schema, value, _ctx);
 };
-const decode$1 = /* @__PURE__ */ _decode($ZodRealError);
 const _encodeAsync = (_Err) => async (schema, value, _ctx) => {
 	const ctx = _ctx ? Object.assign(_ctx, { direction: "backward" }) : { direction: "backward" };
 	return _parseAsync(_Err)(schema, value, ctx);
 };
-const encodeAsync$1 = /* @__PURE__ */ _encodeAsync($ZodRealError);
 const _decodeAsync = (_Err) => async (schema, value, _ctx) => {
 	return _parseAsync(_Err)(schema, value, _ctx);
 };
-const decodeAsync$1 = /* @__PURE__ */ _decodeAsync($ZodRealError);
 const _safeEncode = (_Err) => (schema, value, _ctx) => {
 	const ctx = _ctx ? Object.assign(_ctx, { direction: "backward" }) : { direction: "backward" };
 	return _safeParse(_Err)(schema, value, ctx);
 };
-const safeEncode$1 = /* @__PURE__ */ _safeEncode($ZodRealError);
 const _safeDecode = (_Err) => (schema, value, _ctx) => {
 	return _safeParse(_Err)(schema, value, _ctx);
 };
-const safeDecode$1 = /* @__PURE__ */ _safeDecode($ZodRealError);
 const _safeEncodeAsync = (_Err) => async (schema, value, _ctx) => {
 	const ctx = _ctx ? Object.assign(_ctx, { direction: "backward" }) : { direction: "backward" };
 	return _safeParseAsync(_Err)(schema, value, ctx);
 };
-const safeEncodeAsync$1 = /* @__PURE__ */ _safeEncodeAsync($ZodRealError);
 const _safeDecodeAsync = (_Err) => async (schema, value, _ctx) => {
 	return _safeParseAsync(_Err)(schema, value, _ctx);
 };
-const safeDecodeAsync$1 = /* @__PURE__ */ _safeDecodeAsync($ZodRealError);
 
 //#endregion
 //#region ../../../node_modules/.bun/zod@4.3.6/node_modules/zod/v4/core/regexes.js
@@ -6326,32 +6322,6 @@ function _check(fn, params) {
 	ch._zod.check = fn;
 	return ch;
 }
-/* @__NO_SIDE_EFFECTS__ */
-function describe$2(description) {
-	const ch = new $ZodCheck({ check: "describe" });
-	ch._zod.onattach = [(inst) => {
-		const existing = globalRegistry.get(inst) ?? {};
-		globalRegistry.add(inst, {
-			...existing,
-			description
-		});
-	}];
-	ch._zod.check = () => {};
-	return ch;
-}
-/* @__NO_SIDE_EFFECTS__ */
-function meta$2(metadata) {
-	const ch = new $ZodCheck({ check: "meta" });
-	ch._zod.onattach = [(inst) => {
-		const existing = globalRegistry.get(inst) ?? {};
-		globalRegistry.add(inst, {
-			...existing,
-			...metadata
-		});
-	}];
-	ch._zod.check = () => {};
-	return ch;
-}
 
 //#endregion
 //#region ../../../node_modules/.bun/zod@4.3.6/node_modules/zod/v4/core/to-json-schema.js
@@ -7139,8 +7109,6 @@ function object$1(shape, params) {
 		...normalizeParams(params)
 	});
 }
-const describe$1 = describe$2;
-const meta$1 = meta$2;
 
 //#endregion
 //#region ../../../node_modules/.bun/@modelcontextprotocol+sdk@1.29.0/node_modules/@modelcontextprotocol/sdk/dist/esm/server/zod-compat.js
@@ -7954,8 +7922,6 @@ function refine(fn, _params = {}) {
 function superRefine(fn) {
 	return _superRefine(fn);
 }
-const describe = describe$2;
-const meta = meta$2;
 function preprocess(fn, schema) {
 	return pipe(transform(fn), schema);
 }
@@ -9239,7 +9205,7 @@ function isTerminal(status) {
 }
 
 //#endregion
-//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.1+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/Options.js
+//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.2+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/Options.js
 const ignoreOverride = Symbol("Let zodToJsonSchema decide on which parser to use");
 const defaultOptions = {
 	name: void 0,
@@ -9274,7 +9240,7 @@ const getDefaultOptions = (options) => typeof options === "string" ? {
 };
 
 //#endregion
-//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.1+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/Refs.js
+//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.2+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/Refs.js
 const getRefs = (options) => {
 	const _options = getDefaultOptions(options);
 	const currentPath = _options.name !== void 0 ? [
@@ -9300,7 +9266,7 @@ const getRefs = (options) => {
 };
 
 //#endregion
-//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.1+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/errorMessages.js
+//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.2+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/errorMessages.js
 function addErrorMessage(res, key, errorMessage, refs) {
 	if (!refs?.errorMessages) return;
 	if (errorMessage) res.errorMessage = {
@@ -9314,7 +9280,7 @@ function setResponseValueAndErrors(res, key, value, errorMessage, refs) {
 }
 
 //#endregion
-//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.1+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/getRelativePath.js
+//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.2+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/getRelativePath.js
 const getRelativePath = (pathA, pathB) => {
 	let i = 0;
 	for (; i < pathA.length && i < pathB.length; i++) if (pathA[i] !== pathB[i]) break;
@@ -9322,7 +9288,7 @@ const getRelativePath = (pathA, pathB) => {
 };
 
 //#endregion
-//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.1+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/any.js
+//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.2+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/any.js
 function parseAnyDef(refs) {
 	if (refs.target !== "openAi") return {};
 	const anyDefinitionPath = [
@@ -9335,7 +9301,7 @@ function parseAnyDef(refs) {
 }
 
 //#endregion
-//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.1+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/array.js
+//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.2+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/array.js
 function parseArrayDef(def, refs) {
 	const res = { type: "array" };
 	if (def.type?._def && def.type?._def?.typeName !== ZodFirstPartyTypeKind.ZodAny) res.items = parseDef(def.type._def, {
@@ -9352,7 +9318,7 @@ function parseArrayDef(def, refs) {
 }
 
 //#endregion
-//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.1+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/bigint.js
+//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.2+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/bigint.js
 function parseBigintDef(def, refs) {
 	const res = {
 		type: "integer",
@@ -9384,25 +9350,25 @@ function parseBigintDef(def, refs) {
 }
 
 //#endregion
-//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.1+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/boolean.js
+//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.2+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/boolean.js
 function parseBooleanDef() {
 	return { type: "boolean" };
 }
 
 //#endregion
-//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.1+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/branded.js
+//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.2+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/branded.js
 function parseBrandedDef(_def, refs) {
 	return parseDef(_def.type._def, refs);
 }
 
 //#endregion
-//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.1+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/catch.js
+//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.2+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/catch.js
 const parseCatchDef = (def, refs) => {
 	return parseDef(def.innerType._def, refs);
 };
 
 //#endregion
-//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.1+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/date.js
+//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.2+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/date.js
 function parseDateDef(def, refs, overrideDateStrategy) {
 	const strategy = overrideDateStrategy ?? refs.dateStrategy;
 	if (Array.isArray(strategy)) return { anyOf: strategy.map((item, i) => parseDateDef(def, refs, item)) };
@@ -9437,7 +9403,7 @@ const integerDateParser = (def, refs) => {
 };
 
 //#endregion
-//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.1+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/default.js
+//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.2+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/default.js
 function parseDefaultDef(_def, refs) {
 	return {
 		...parseDef(_def.innerType._def, refs),
@@ -9446,13 +9412,13 @@ function parseDefaultDef(_def, refs) {
 }
 
 //#endregion
-//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.1+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/effects.js
+//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.2+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/effects.js
 function parseEffectsDef(_def, refs) {
 	return refs.effectStrategy === "input" ? parseDef(_def.schema._def, refs) : parseAnyDef(refs);
 }
 
 //#endregion
-//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.1+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/enum.js
+//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.2+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/enum.js
 function parseEnumDef(def) {
 	return {
 		type: "string",
@@ -9461,7 +9427,7 @@ function parseEnumDef(def) {
 }
 
 //#endregion
-//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.1+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/intersection.js
+//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.2+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/intersection.js
 const isJsonSchema7AllOfType = (type) => {
 	if ("type" in type && type.type === "string") return false;
 	return "allOf" in type;
@@ -9504,7 +9470,7 @@ function parseIntersectionDef(def, refs) {
 }
 
 //#endregion
-//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.1+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/literal.js
+//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.2+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/literal.js
 function parseLiteralDef(def, refs) {
 	const parsedType = typeof def.value;
 	if (parsedType !== "bigint" && parsedType !== "number" && parsedType !== "boolean" && parsedType !== "string") return { type: Array.isArray(def.value) ? "array" : "object" };
@@ -9519,7 +9485,7 @@ function parseLiteralDef(def, refs) {
 }
 
 //#endregion
-//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.1+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/string.js
+//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.2+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/string.js
 let emojiRegex = void 0;
 /**
 * Generated from the regular expressions found here as of 2024-05-22:
@@ -9765,7 +9731,7 @@ function stringifyRegExpWithFlags(regex, refs) {
 }
 
 //#endregion
-//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.1+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/record.js
+//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.2+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/record.js
 function parseRecordDef(def, refs) {
 	if (refs.target === "openAi") console.warn("Warning: OpenAI may not support records in schemas! Try an array of key-value pairs instead.");
 	if (refs.target === "openApi3" && def.keyType?._def.typeName === ZodFirstPartyTypeKind.ZodEnum) return {
@@ -9813,7 +9779,7 @@ function parseRecordDef(def, refs) {
 }
 
 //#endregion
-//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.1+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/map.js
+//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.2+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/map.js
 function parseMapDef(def, refs) {
 	if (refs.mapStrategy === "record") return parseRecordDef(def, refs);
 	return {
@@ -9845,7 +9811,7 @@ function parseMapDef(def, refs) {
 }
 
 //#endregion
-//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.1+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/nativeEnum.js
+//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.2+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/nativeEnum.js
 function parseNativeEnumDef(def) {
 	const object = def.values;
 	const actualValues = Object.keys(def.values).filter((key) => {
@@ -9859,7 +9825,7 @@ function parseNativeEnumDef(def) {
 }
 
 //#endregion
-//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.1+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/never.js
+//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.2+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/never.js
 function parseNeverDef(refs) {
 	return refs.target === "openAi" ? void 0 : { not: parseAnyDef({
 		...refs,
@@ -9868,7 +9834,7 @@ function parseNeverDef(refs) {
 }
 
 //#endregion
-//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.1+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/null.js
+//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.2+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/null.js
 function parseNullDef(refs) {
 	return refs.target === "openApi3" ? {
 		enum: ["null"],
@@ -9877,7 +9843,7 @@ function parseNullDef(refs) {
 }
 
 //#endregion
-//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.1+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/union.js
+//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.2+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/union.js
 const primitiveMappings = {
 	ZodString: "string",
 	ZodNumber: "number",
@@ -9934,7 +9900,7 @@ const asAnyOf = (def, refs) => {
 };
 
 //#endregion
-//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.1+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/nullable.js
+//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.2+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/nullable.js
 function parseNullableDef(def, refs) {
 	if ([
 		"ZodString",
@@ -9975,7 +9941,7 @@ function parseNullableDef(def, refs) {
 }
 
 //#endregion
-//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.1+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/number.js
+//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.2+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/number.js
 function parseNumberDef(def, refs) {
 	const res = { type: "number" };
 	if (!def.checks) return res;
@@ -10008,7 +9974,7 @@ function parseNumberDef(def, refs) {
 }
 
 //#endregion
-//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.1+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/object.js
+//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.2+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/object.js
 function parseObjectDef(def, refs) {
 	const forceOptionalIntoNullable = refs.target === "openAi";
 	const result = {
@@ -10068,7 +10034,7 @@ function safeIsOptional(schema) {
 }
 
 //#endregion
-//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.1+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/optional.js
+//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.2+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/optional.js
 const parseOptionalDef = (def, refs) => {
 	if (refs.currentPath.toString() === refs.propertyPath?.toString()) return parseDef(def.innerType._def, refs);
 	const innerSchema = parseDef(def.innerType._def, {
@@ -10083,7 +10049,7 @@ const parseOptionalDef = (def, refs) => {
 };
 
 //#endregion
-//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.1+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/pipeline.js
+//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.2+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/pipeline.js
 const parsePipelineDef = (def, refs) => {
 	if (refs.pipeStrategy === "input") return parseDef(def.in._def, refs);
 	else if (refs.pipeStrategy === "output") return parseDef(def.out._def, refs);
@@ -10106,13 +10072,13 @@ const parsePipelineDef = (def, refs) => {
 };
 
 //#endregion
-//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.1+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/promise.js
+//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.2+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/promise.js
 function parsePromiseDef(def, refs) {
 	return parseDef(def.type._def, refs);
 }
 
 //#endregion
-//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.1+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/set.js
+//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.2+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/set.js
 function parseSetDef(def, refs) {
 	const schema = {
 		type: "array",
@@ -10128,7 +10094,7 @@ function parseSetDef(def, refs) {
 }
 
 //#endregion
-//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.1+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/tuple.js
+//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.2+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/tuple.js
 function parseTupleDef(def, refs) {
 	if (def.rest) return {
 		type: "array",
@@ -10162,25 +10128,25 @@ function parseTupleDef(def, refs) {
 }
 
 //#endregion
-//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.1+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/undefined.js
+//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.2+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/undefined.js
 function parseUndefinedDef(refs) {
 	return { not: parseAnyDef(refs) };
 }
 
 //#endregion
-//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.1+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/unknown.js
+//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.2+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/unknown.js
 function parseUnknownDef(refs) {
 	return parseAnyDef(refs);
 }
 
 //#endregion
-//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.1+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/readonly.js
+//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.2+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parsers/readonly.js
 const parseReadonlyDef = (def, refs) => {
 	return parseDef(def.innerType._def, refs);
 };
 
 //#endregion
-//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.1+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/selectParser.js
+//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.2+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/selectParser.js
 const selectParser = (def, typeName, refs) => {
 	switch (typeName) {
 		case ZodFirstPartyTypeKind.ZodString: return parseStringDef(def, refs);
@@ -10224,7 +10190,7 @@ const selectParser = (def, typeName, refs) => {
 };
 
 //#endregion
-//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.1+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parseDef.js
+//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.2+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/parseDef.js
 function parseDef(def, refs, forceResolution = false) {
 	const seenItem = refs.seen.get(def);
 	if (refs.override) {
@@ -10274,7 +10240,7 @@ const addMeta = (def, refs, jsonSchema) => {
 };
 
 //#endregion
-//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.1+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/zodToJsonSchema.js
+//#region ../../../node_modules/.bun/zod-to-json-schema@3.25.2+3c5d820c62823f0b/node_modules/zod-to-json-schema/dist/esm/zodToJsonSchema.js
 const zodToJsonSchema = (schema, options) => {
 	const refs = getRefs(options);
 	let definitions = typeof options === "object" && options.definitions ? Object.entries(options.definitions).reduce((acc, [name, schema]) => ({
@@ -12750,7 +12716,129 @@ var StdioServerTransport = class {
 
 //#endregion
 //#region package.json
-var version = "0.13.1";
+var version = "0.14.0";
+
+//#endregion
+//#region src/anti-patterns.ts
+const CATEGORY_MAP = {
+	"Reactivity Mistakes": "reactivity",
+	"JSX Mistakes": "jsx",
+	"Context & Provider Mistakes": "context",
+	"Architecture Mistakes": "architecture",
+	"Testing Mistakes": "testing",
+	"Lifecycle & Cleanup Mistakes": "lifecycle",
+	"Documentation Mistakes": "documentation"
+};
+const ANTI_PATTERN_CATEGORIES = [
+	"reactivity",
+	"jsx",
+	"context",
+	"architecture",
+	"testing",
+	"lifecycle",
+	"documentation"
+];
+function normaliseCategory(heading) {
+	return CATEGORY_MAP[heading.trim()] ?? null;
+}
+function splitSections(doc) {
+	const lines = doc.split("\n");
+	const sections = [];
+	let currentHeading = null;
+	let currentBody = [];
+	for (const line of lines) {
+		const headingMatch = /^## (.+)$/.exec(line);
+		if (headingMatch) {
+			if (currentHeading !== null) sections.push({
+				heading: currentHeading,
+				body: currentBody.join("\n")
+			});
+			currentHeading = headingMatch[1];
+			currentBody = [];
+		} else if (currentHeading !== null) currentBody.push(line);
+	}
+	if (currentHeading !== null) sections.push({
+		heading: currentHeading,
+		body: currentBody.join("\n")
+	});
+	return sections;
+}
+function splitBullets(sectionBody) {
+	const lines = sectionBody.split("\n");
+	const bullets = [];
+	let current = [];
+	for (const line of lines) if (/^- \*\*/.test(line)) {
+		if (current.length > 0) bullets.push(current.join("\n").trim());
+		current = [line];
+	} else if (current.length > 0) current.push(line);
+	if (current.length > 0) bullets.push(current.join("\n").trim());
+	return bullets.filter((b) => b.length > 0);
+}
+function parseBullet(bullet) {
+	const nameMatch = /^- \*\*([^*]+)\*\*/.exec(bullet);
+	if (!nameMatch) return null;
+	const name = nameMatch[1].trim();
+	const afterName = bullet.slice(nameMatch[0].length);
+	const detectorMatch = /`?\[detector:\s*([a-z0-9\-\/ ]+)\]`?/i.exec(afterName);
+	const detectorCodes = [];
+	if (detectorMatch) for (const code of detectorMatch[1].split("/")) {
+		const c = code.trim();
+		if (c) detectorCodes.push(c);
+	}
+	let description = afterName;
+	if (detectorMatch) description = description.replace(detectorMatch[0], "");
+	description = description.replace(/^[\s:]+/, "").trim();
+	return {
+		name,
+		description,
+		detectorCodes
+	};
+}
+function parseAntiPatterns(doc) {
+	const sections = splitSections(doc);
+	const entries = [];
+	for (const { heading, body } of sections) {
+		const category = normaliseCategory(heading);
+		if (!category) continue;
+		for (const bullet of splitBullets(body)) {
+			const parsed = parseBullet(bullet);
+			if (!parsed) continue;
+			entries.push({
+				name: parsed.name,
+				category,
+				categoryHeading: heading,
+				description: parsed.description,
+				detectorCodes: parsed.detectorCodes
+			});
+		}
+	}
+	return entries;
+}
+/** Format a list of entries into a single Markdown block suitable for MCP. */
+function formatAntiPatterns(entries, filterCategory) {
+	if (entries.length === 0) return filterCategory === "all" ? "No anti-patterns found. Check that `.claude/rules/anti-patterns.md` is reachable." : `No anti-patterns found in category '${filterCategory}'. Valid categories: ${ANTI_PATTERN_CATEGORIES.join(", ")}, all.`;
+	const byCategory = /* @__PURE__ */ new Map();
+	for (const entry of entries) {
+		if (!byCategory.has(entry.category)) byCategory.set(entry.category, []);
+		byCategory.get(entry.category).push(entry);
+	}
+	const parts = [];
+	const header = filterCategory === "all" ? `# Pyreon Anti-Patterns (${entries.length} total, ${byCategory.size} categor${byCategory.size === 1 ? "y" : "ies"})` : `# Pyreon Anti-Patterns — ${filterCategory} (${entries.length})`;
+	parts.push(header);
+	parts.push("");
+	parts.push("Each entry is a known mistake documented at `.claude/rules/anti-patterns.md`. Entries tagged `[detector: <code>]` are caught statically by the MCP `validate` tool — the rest require a human / AI review. Read them BEFORE writing new code, not during code review.");
+	parts.push("");
+	for (const [, catEntries] of byCategory) {
+		parts.push(`## ${catEntries[0].categoryHeading} (${catEntries.length})`);
+		parts.push("");
+		for (const entry of catEntries) {
+			const tag = entry.detectorCodes.length > 0 ? ` \`[detector: ${entry.detectorCodes.join(" / ")}]\`` : "";
+			parts.push(`- **${entry.name}**${tag}: ${entry.description}`);
+		}
+		parts.push("");
+	}
+	return parts.join("\n").trimEnd();
+}
 
 //#endregion
 //#region src/api-reference.ts
@@ -13330,17 +13418,47 @@ useHead({ title: "My Page", meta: [{ name: "description", content: "..." }] })
 useHead(() => ({
   title: \`\${username()} — Profile\`,
   meta: [{ property: "og:title", content: username() }]
-}))`
+}))`,
+		notes: "Register head tags from any component in the tree. Pass a static `UseHeadInput` object for one-shot registration, or a `() => UseHeadInput` thunk for reactive re-registration when signal reads inside the thunk change. Calling `useHead()` outside a `HeadProvider` ancestor (CSR) or `renderWithHead()` invocation (SSR) is a silent no-op — it does not throw. See also: HeadProvider, renderWithHead.",
+		mistakes: `- Using \`\${...}\` in a \`titleTemplate\` string — the placeholder is \`%s\` (or pass a function form \`(title) => …\`)
+- Calling \`useHead()\` outside any \`HeadProvider\` / \`renderWithHead()\` boundary — silent no-op, the entries simply go nowhere
+- Wrapping the input in \`computed()\` instead of a thunk — pass a plain \`() => ({...})\` arrow; \`useHead\` registers its own effect
+- Expecting \`<\/script>\` inside an inline script body to render verbatim — the SSR escaper rewrites it as \`<\/script>\` to prevent breaking out of the inline tag`
 	},
 	"head/HeadProvider": {
-		signature: "<HeadProvider>{children}</HeadProvider>",
-		example: `// Client-side setup:
+		signature: "(props: HeadProviderProps) => VNodeChild",
+		example: `<HeadProvider>{children}</HeadProvider>
+
+// Client-side setup:
 mount(
   <HeadProvider>
     <App />
   </HeadProvider>,
   document.getElementById("app")!
-)`
+)`,
+		notes: "Client-side context provider that collects every `useHead()` call from descendants and syncs the resolved tags into the live `document.head` element. Mount once near the application root. Auto-creates a `HeadContextValue` when no `context` prop is passed; nested providers each own an independent context. See also: useHead, renderWithHead, createHeadContext.",
+		mistakes: `- Mounting two \`HeadProvider\` instances at sibling roots — each owns an independent context, so a \`useHead()\` deeper in tree A is invisible to tree B
+- Forgetting to mount \`HeadProvider\` and expecting \`useHead()\` to still update \`document.head\` — silent no-op outside a provider`
+	},
+	"head/renderWithHead": {
+		signature: "renderWithHead(app: VNode): Promise<{ html: string; head: string; htmlAttrs: string; bodyAttrs: string }>",
+		example: `import { renderWithHead } from '@pyreon/head'
+
+const { html, head, htmlAttrs, bodyAttrs } = await renderWithHead(<App />)
+const doc = \`<!doctype html><html\${htmlAttrs}><head>\${head}</head><body\${bodyAttrs}>\${html}</body></html>\``,
+		notes: "SSR companion to `HeadProvider`. Renders the app to HTML via `renderToString` while collecting every `useHead()` call from the tree, then serializes the resolved tags into a single `head` string plus separate `htmlAttrs` / `bodyAttrs` strings. Async components that call `useHead()` in their body work — the renderer awaits suspended subtrees before serialization. See also: useHead, HeadProvider.",
+		mistakes: `- Awaiting \`renderWithHead\` and then NOT splicing \`head\` into the \`<head>\` element — every \`useHead()\` call quietly disappears
+- Forgetting to interpolate \`htmlAttrs\` / \`bodyAttrs\` (the leading space is included in each string) — \`htmlAttrs.lang\` and \`bodyAttrs.class\` set via \`useHead\` won\'t reach the DOM`
+	},
+	"head/createHeadContext": {
+		signature: "() => HeadContextValue",
+		example: `import { createHeadContext, HeadContext } from '@pyreon/head'
+
+const ctx = createHeadContext()
+provide(HeadContext, ctx)
+// ... render tree that calls useHead() ...
+const { tags, htmlAttrs, bodyAttrs } = ctx.resolve()`,
+		notes: "Manual factory for a `HeadContextValue` — only needed when wiring up a custom SSR pipeline that bypasses `renderWithHead`, or when running multiple isolated head contexts in the same process. The value exposes `add` / `remove` / `resolve` / `resolveTitleTemplate` / `resolveHtmlAttrs` / `resolveBodyAttrs` for full programmatic control. See also: HeadProvider, renderWithHead."
 	},
 	"server/createHandler": {
 		signature: "createHandler(options: HandlerOptions): (req: Request) => Promise<Response>",
@@ -13351,7 +13469,12 @@ export default createHandler({
   routes,
   clientEntry: "/src/entry-client.ts",
   mode: "stream",  // or "string"
-})`
+})`,
+		notes: "Build a production SSR handler from your `App`, `routes`, and optional template / client entry / middleware. The template is precompiled once at handler-creation (split into 4 parts to skip three string scans per request); a missing `<!--pyreon-app-->` placeholder throws at creation time, not per request. Middleware runs before render with `ctx.locals` for cross-middleware data passing — return a `Response` to short-circuit the chain. `mode: \"stream\"` uses `renderToStream` so Suspense boundaries flush out-of-order; `mode: \"string\"` uses `renderToString` (default). See also: prerender, island, useRequestLocals.",
+		mistakes: `- Omitting \`<!--pyreon-app-->\` from the custom template — throws at handler-creation, not per request
+- Returning a \`Response\` from middleware and expecting downstream middleware to still run — the chain short-circuits on the first \`Response\`
+- Reading \`ctx.locals\` from inside the component without \`useRequestLocals()\` — the component tree only sees locals when bridged through that hook
+- Forgetting to escape user data inserted into a custom template — \`createHandler\` only escapes its own loader-data injection (\`<\/script>\` → \`<\/script>\`); your template content is your responsibility`
 	},
 	"server/island": {
 		signature: "island(loader: () => Promise<ComponentFn>, options: { name: string; hydrate?: HydrationStrategy }): ComponentFn",
@@ -13360,7 +13483,12 @@ export default createHandler({
   { name: "SearchBar", hydrate: "visible" }
 )
 
-// Hydration strategies: "load" | "idle" | "visible" | "media" | "never"`
+// Hydration strategies: "load" | "idle" | "visible" | "media" | "never"`,
+		notes: "Wrap a lazily-loaded component in a `<pyreon-island>` boundary with a hydration strategy. The rest of the page stays HTML-only; only the island fetches its JS bundle and hydrates. Strategies: `\"load\"` (immediate), `\"idle\"` (`requestIdleCallback`), `\"visible\"` (IntersectionObserver), `\"media(query)\"` (matchMedia), `\"never\"` (HTML-only, no JS). Props passed to islands are JSON-serialized — non-JSON values (functions, symbols, undefined, children) are stripped. See also: createHandler, hydrateIslands.",
+		mistakes: `- Passing function props (event handlers, callbacks) — silently stripped during JSON serialization, the island sees \`undefined\`
+- Passing children to an island — stripped; islands cannot render arbitrary descendant trees from props
+- Forgetting to call \`hydrateIslands({ Name: () => import("./Path") })\` on the client — islands render as HTML and never hydrate
+- Using a duplicate \`name\` across two islands — the client-side registry collapses them, only one loader will fire`
 	},
 	"server/prerender": {
 		signature: "prerender(options: PrerenderOptions): Promise<PrerenderResult>",
@@ -13368,7 +13496,11 @@ export default createHandler({
   handler,
   paths: ["/", "/about", "/blog/1", "/blog/2"],
   outDir: "./dist",
-})`
+})`,
+		notes: "Static-site generator built on `createHandler`. Walks the `paths` array (or async generator), invokes the handler for each path, and writes the rendered HTML to `outDir/<path>.html`. The `onPage(path, html)` callback fires per page so callers can post-process or stream output. Validates `outDir` against path traversal (`../` segments are rejected). Errors per-page are collected in the result, not thrown. See also: createHandler.",
+		mistakes: `- Passing a relative \`outDir\` and being surprised when it resolves against \`process.cwd()\` — pass an absolute path for predictability
+- Expecting per-page errors to throw — they\'re collected in \`result.errors\`; check the array after \`await\`
+- Generating thousands of paths without batching — the function processes the array sequentially; if you need parallelism, batch the \`paths\` array yourself`
 	},
 	"runtime-dom/mount": {
 		signature: "mount(root: VNodeChild, container: Element): () => void",
@@ -14554,7 +14686,7 @@ lint({
     "pyreon/no-window-in-ssr": { exemptPaths: ["src/foundation/"] },
   },
 })`,
-		notes: "Programmatic API. 59 rules across 12 categories. Auto-loads .pyreonlintrc.json. Presets: recommended, strict, app, lib. Per-rule options via tuple form in config (`[\"error\", { exemptPaths: [...] }]`) or `ruleOptionsOverrides`. Wrong-typed options surface on `result.configDiagnostics`. Uses oxc-parser with AST caching."
+		notes: "59 rules across 12 categories. Auto-loads `.pyreonlintrc.json`. Presets: `recommended`, `strict`, `app`, `lib`. Per-rule options via tuple form in config (`[\"error\", { exemptPaths: [...] }]`) or `ruleOptionsOverrides`. Wrong-typed options surface on `result.configDiagnostics`. Uses `oxc-parser` with AST caching. See also: lintFile, getPreset, AstCache."
 	},
 	"lint/lintFile": {
 		signature: "lintFile(filePath: string, sourceText: string, rules: Rule[], config: LintConfig, cache?: AstCache, configDiagnosticsSink?: ConfigDiagnostic[]): LintFileResult",
@@ -14564,17 +14696,17 @@ const cache = new AstCache()
 const config = getPreset("recommended")
 const configSink: ConfigDiagnostic[] = []
 const result = lintFile("app.tsx", source, allRules, config, cache, configSink)`,
-		notes: "Low-level single-file API. Optional AstCache for repeat runs (FNV-1a hash keyed). Optional `configDiagnosticsSink` collects malformed-option diagnostics; without it they print to stderr."
+		notes: "Low-level single-file API. Optional `AstCache` for repeat runs (FNV-1a hash keyed). Optional `configDiagnosticsSink` collects malformed-option diagnostics; without it they print to stderr. See also: lint, AstCache."
 	},
 	"lint/cli": {
-		signature: "pyreon-lint [--preset name] [--fix] [--format text|json|compact] [--quiet] [--watch] [--list] [--config path] [--ignore path] [--rule id=severity] [--rule-options id='{json}'] [path...]",
+		signature: `pyreon-lint [--preset name] [--fix] [--format text|json|compact] [--quiet] [--watch] [--list] [--config path] [--ignore path] [--rule id=severity] [--rule-options id='{json}'] [path...]`,
 		example: `pyreon-lint --preset strict --quiet    # CI mode
 pyreon-lint --fix                       # auto-fix
 pyreon-lint --watch src/                # watch mode
 pyreon-lint --list                      # list all 59 rules
 pyreon-lint --format json               # machine-readable
 pyreon-lint --rule-options 'pyreon/no-window-in-ssr={"exemptPaths":["src/foundation/"]}' src/`,
-		notes: "CLI entry. Config: .pyreonlintrc.json (reference schema/pyreonlintrc.schema.json for IDE autocomplete), package.json 'pyreonlint' field. Ignore: .pyreonlintignore + .gitignore. Watch: fs.watch recursive with 100ms debounce. `--rule-options id='{json}'` passes per-rule options on a single run."
+		notes: `CLI entry. Config: \`.pyreonlintrc.json\` (reference \`schema/pyreonlintrc.schema.json\` for IDE autocomplete) or \`package.json\`'s \`'pyreonlint'\` field. Ignore: \`.pyreonlintignore\` + \`.gitignore\`. Watch: \`fs.watch\` recursive with 100ms debounce. \`--rule-options id='{json}'\` passes per-rule options on a single run. See also: lint.`
 	},
 	"lint/no-process-dev-gate": {
 		signature: "rule: pyreon/no-process-dev-gate (architecture, error, auto-fixable)",
@@ -14586,7 +14718,7 @@ if (__DEV__) console.warn('hello')
 // @ts-ignore — provided by Vite/Rolldown at build time
 const __DEV__ = import.meta.env?.DEV === true
 if (__DEV__) console.warn('hello')`,
-		notes: "The `typeof process !== 'undefined' && process.env.NODE_ENV !== 'production'` pattern works in vitest (Node, `process` is defined) but is silently dead code in real Vite browser bundles because Vite does NOT polyfill `process` for the client. Every `console.warn` gated on the broken constant never fires for real users in dev mode — unit tests pass while users get nothing. Use `import.meta.env.DEV` instead — Vite/Rolldown literal-replace it at build time, prod tree-shakes the warning to zero bytes, and vitest sets it to `true` automatically. Server-only packages (`zero`, `core/server`, `core/runtime-server`, `vite-plugin`, `cli`, `lint`, `mcp`, `storybook`, `typescript`) and test files are exempt. Reference implementation: `packages/fundamentals/flow/src/layout.ts:warnIgnoredOptions`. The rule has an auto-fix that replaces the broken expression with `import.meta.env?.DEV === true`.",
+		notes: `The \`typeof process !== 'undefined' && process.env.NODE_ENV !== 'production'\` pattern works in vitest (Node, \`process\` is defined) but is silently dead code in real Vite browser bundles because Vite does NOT polyfill \`process\` for the client. Every \`console.warn\` gated on the broken constant never fires for real users in dev mode — unit tests pass while users get nothing. Use \`import.meta.env.DEV\` instead — Vite/Rolldown literal-replace it at build time, prod tree-shakes the warning to zero bytes, and vitest sets it to \`true\` automatically. Server-only packages (\`zero\`, \`core/server\`, \`core/runtime-server\`, \`vite-plugin\`, \`cli\`, \`lint\`, \`mcp\`, \`storybook\`, \`typescript\`) and test files are exempt. Reference implementation: \`packages/fundamentals/flow/src/layout.ts:warnIgnoredOptions\`. The rule has an auto-fix that replaces the broken expression with \`import.meta.env?.DEV === true\`. See also: require-browser-smoke-test.`,
 		mistakes: `- Copying the \`typeof process !== 'undefined' && process.env.NODE_ENV !== 'production'\` pattern from existing codebases — it works in Node but is dead in browser bundles
 - Trying to test with \`delete globalThis.process\` — vitest's own \`import.meta.env\` depends on \`process\`, so deleting it breaks the FIXED gate too (not because the gate is wrong, but because vitest can't resolve it)
 - Adding \`process: { env: { ... } }\` polyfills to vite.config.ts as a workaround — fix the source instead
@@ -14606,7 +14738,7 @@ if (__DEV__) console.warn('hello')`,
     ]
   }
 }`,
-		notes: "Locks in the durability of the T1.1 browser smoke harness (PRs #224, #227, #229, #231). Every browser-categorized package MUST ship at least one `*.browser.test.{ts,tsx}` file under `src/`. Without this rule, new browser packages can quietly ship without smoke coverage and we drift back to the world before T1.1 — happy-dom silently masks environment-divergence bugs (PR #197 mock-vnode metadata drop, PR #200 `typeof process` dead code, multi-word event delegation bug). Default browser-package list mirrors `.claude/rules/test-environment-parity.md`. The rule fires once per package on its `src/index.ts`, walks the package directory looking for `*.browser.test.*`, and reports if none are found. Off in `app` preset because apps don't ship as packages with smoke obligations.",
+		notes: `Locks in the durability of the T1.1 browser smoke harness (PRs #224, #227, #229, #231). Every browser-categorized package MUST ship at least one \`*.browser.test.{ts,tsx}\` file under \`src/\`. Without this rule, new browser packages can quietly ship without smoke coverage and we drift back to the world before T1.1 — happy-dom silently masks environment-divergence bugs (PR #197 mock-vnode metadata drop, PR #200 \`typeof process\` dead code, multi-word event delegation bug). Default browser-package list mirrors \`.claude/rules/test-environment-parity.md\`. The rule fires once per package on its \`src/index.ts\`, walks the package directory looking for \`*.browser.test.*\`, and reports if none are found. Off in \`app\` preset because apps don't ship as packages with smoke obligations. See also: no-process-dev-gate.`,
 		mistakes: `- Adding a new browser-running package without a browser test — the rule will fail your PR
 - Hardcoding the browser-package list in the rule — the list lives in \`.claude/rules/browser-packages.json\` (single source of truth), not in the rule source
 - Disabling the rule globally — use \`exemptPaths\` to exempt specific packages still under construction
@@ -14618,11 +14750,84 @@ if (__DEV__) console.warn('hello')`,
 //   "which Pyreon packages are missing browser smoke coverage?"
 // Tool walks packages/, matches against .claude/rules/browser-packages.json,
 // returns a coverage report.`,
-		notes: "Companion to the `pyreon/require-browser-smoke-test` lint rule. Reports which browser-categorized Pyreon packages have at least one `*.browser.test.{ts,tsx}` file under `src/`. Uses the same `.claude/rules/browser-packages.json` single source of truth as the rule + the CI script. Lets an AI agent check coverage before writing a new browser package (so it adds a smoke test in the same PR) instead of discovering the failure when CI runs. Falls back with a clear message if the JSON isn't present (e.g. consumer apps that don't ship the Pyreon monorepo layout).",
+		notes: `Companion to the \`pyreon/require-browser-smoke-test\` lint rule. Reports which browser-categorized Pyreon packages have at least one \`*.browser.test.{ts,tsx}\` file under \`src/\`. Uses the same \`.claude/rules/browser-packages.json\` single source of truth as the rule + the CI script. Lets an AI agent check coverage before writing a new browser package (so it adds a smoke test in the same PR) instead of discovering the failure when CI runs. Falls back with a clear message if the JSON isn't present (e.g. consumer apps that don't ship the Pyreon monorepo layout). See also: audit_test_environment.`,
 		mistakes: `- Using the tool's output as a substitute for running the CI script — this tool only checks file existence, not the self-expiring-exemption check that \`bun run lint:browser-smoke\` performs`
 	},
+	"mcp/get_api": {
+		signature: "tool: get_api({ package: string; symbol: string }) → APIEntry",
+		example: `// Agent-side
+get_api({ package: 'flow', symbol: 'createFlow' })
+get_api({ package: '@pyreon/router', symbol: 'useTypedSearchParams' })`,
+		notes: `Look up any Pyreon API by \`package\` (e.g. \`"flow"\` or \`"@pyreon/flow"\`) and \`symbol\` (e.g. \`"createFlow"\`). Returns the canonical signature, example, foot-gun catalogue, and cross-references — drawn from \`api-reference.ts\`, which is regenerated from each package\'s \`manifest.ts\`. The single agent-facing entry point for "what does this API do and how do I avoid the common mistakes." See also: validate, get_pattern.`
+	},
+	"mcp/validate": {
+		signature: "tool: validate({ code: string; filename?: string }) → Diagnostics[]",
+		example: `validate({ code: \`
+function MyComp(props) {
+  const { value } = props          // → props-destructured
+  return <For each={items}>{...}</For>  // → for-missing-by
+}
+\` })`,
+		notes: "Two AST-based detectors run in parallel: `detectReactPatterns` flags \"coming from React\" mistakes (`useState`, `useEffect`, `className`, `onChange` on inputs, React-package imports), and `detectPyreonPatterns` flags \"using Pyreon wrong\" mistakes (`<For>` missing `by`, props destructured at component signature, `typeof process` dev gates, raw `addEventListener`, `Date.now() + Math.random()` IDs). Diagnostics are merged + sorted by line / column for top-down reading. See also: get_anti_patterns, migrate_react."
+	},
+	"mcp/migrate_react": {
+		signature: "tool: migrate_react({ code: string; filename?: string }) → MigrationResult",
+		example: `migrate_react({ code: \`
+import { useState, useEffect } from 'react'
+function Counter() {
+  const [count, setCount] = useState(0)
+  useEffect(() => { console.log(count) }, [count])
+  return <button onClick={() => setCount(count + 1)}>{count}</button>
+}
+\` })`,
+		notes: "Convert React code to idiomatic Pyreon. Handles `useState` → `signal()`, `useEffect` → `effect()`, `className` → `class`, `onChange` → `onInput`, `useMemo` → `computed()`, React imports → Pyreon imports. Reports per-edit fixable diagnostics so callers can apply or review. See also: validate."
+	},
+	"mcp/diagnose": {
+		signature: "tool: diagnose({ error: string }) → DiagnoseResult",
+		example: `diagnose({ error: 'Cannot redefine property X on object [object Object]' })
+// → cause: configurable: false on a getter; fix: set configurable: true`,
+		notes: "Parse a Pyreon runtime / build error message into structured fix information: probable cause, recommended fix, related docs, and the `.claude/rules/anti-patterns.md` entry (if any) the error matches. Useful when an agent sees a stack trace and wants to skip the \"search the codebase for similar errors\" step. See also: validate, get_anti_patterns."
+	},
+	"mcp/get_routes": {
+		signature: "tool: get_routes() → Route[]",
+		example: `get_routes()
+// → [{ path: '/', name: 'home', hasLoader: true, params: [] }, ...]`,
+		notes: "List every route in the current project — path, loader presence, guards, params, and named-route name. Walks the project source from `process.cwd()` down. Cached per server instance with auto-invalidation on `cwd` change. See also: get_components."
+	},
+	"mcp/get_components": {
+		signature: "tool: get_components() → ComponentInfo[]",
+		example: `get_components()
+// → [{ name: 'Button', file: 'src/Button.tsx', props: ['onClick', 'children'], signals: ['count'] }, ...]`,
+		notes: "List every component in the current project with its props and signal usage. Same scanner as `get_routes`. Useful for an agent before generating new code that needs to reference existing components. See also: get_routes."
+	},
+	"mcp/get_pattern": {
+		signature: "tool: get_pattern({ name?: string }) → PatternBody | string[]",
+		example: `get_pattern({ name: 'controllable-state' })
+// → full canonical pattern body
+get_pattern({})
+// → [{ name: 'controllable-state', summary: '...' }, ...]`,
+		notes: "Fetch a canonical \"how do I do X\" pattern body from `docs/patterns/`. Eight foundational patterns ship: `dev-warnings`, `controllable-state`, `ssr-safe-hooks`, `signal-writes`, `keyed-lists`, `reactive-context`, `event-listeners`, `form-fields`. Omit `name` to list available patterns. Drop a new `docs/patterns/<slug>.md` file to add one — picked up on next call. See also: get_anti_patterns."
+	},
+	"mcp/get_anti_patterns": {
+		signature: `tool: get_anti_patterns({ category?: 'reactivity' | 'jsx' | 'context' | 'architecture' | 'testing' | 'lifecycle' | 'documentation' | 'all' }) → AntiPattern[]`,
+		example: `get_anti_patterns({ category: 'reactivity' })
+// → ['Bare signal in JSX text', 'Stale closures', 'Destructuring props', ...]`,
+		notes: "Browse the anti-patterns catalog parsed from `.claude/rules/anti-patterns.md`. Each entry surfaces its `[detector: <code>]` tag inline so an agent can pair the catalog entry with the live static detector exposed by `validate`. Optional `category` filter; default returns all categories. See also: validate, get_pattern."
+	},
+	"mcp/get_changelog": {
+		signature: "tool: get_changelog({ package?: string; limit?: number; includeDependencyUpdates?: boolean; since?: string }) → ChangelogEntry[]",
+		example: `get_changelog({ package: 'flow', limit: 5 })
+get_changelog({ package: '@pyreon/router', since: '0.12.0' })`,
+		notes: "Recent release notes for any `@pyreon/*` package without scraping `git log`. Parses `packages/**/CHANGELOG.md` into version entries (`{ version, changes[], dependencyUpdates[], empty }`) and returns the N most recent substantive versions (default 5). Filters out ceremonial version bumps (pure dependency-update releases with no user-facing body) by default — opt back in with `includeDependencyUpdates: true`. `since: \"0.12.0\"` returns the delta from a known floor — useful when an agent knows the version it was trained against. See also: get_api."
+	},
+	"mcp/audit_test_environment": {
+		signature: `tool: audit_test_environment({ minRisk?: 'high' | 'medium' | 'low'; limit?: number }) → AuditReport`,
+		example: `audit_test_environment({ minRisk: 'medium', limit: 10 })
+// → grouped report with HIGH / MEDIUM / LOW sections`,
+		notes: `Scan every \`*.test.{ts,tsx}\` under \`packages/\` for the mock-vnode anti-pattern that caused PR #197\'s silent metadata drop. Files are classified HIGH / MEDIUM / LOW based on the balance of mock-vnode literals + helpers + helper-call sites vs real \`h()\` calls + \`@pyreon/core\` import. Three context-aware skips (helper-def vs binding discrimination, type-guard call-arg skip, template-string fixture mask) keep the false-positive rate low. Run before merging a new test file or after a framework change. See also: get_browser_smoke_status.`
+	},
 	"ui-core/PyreonUI": {
-		signature: "PyreonUI(props: { theme?: Theme; mode?: 'light' | 'dark' | 'system'; inversed?: boolean; children: VNodeChild }): VNodeChild",
+		signature: `(props: { theme?: Theme; mode?: 'light' | 'dark' | 'system'; inversed?: boolean; children: VNodeChild }) => VNodeChild`,
 		example: `import { PyreonUI } from "@pyreon/ui-core"
 import { enrichTheme } from "@pyreon/unistyle"
 
@@ -14634,18 +14839,22 @@ const theme = enrichTheme({ colors: { primary: "#3b82f6" } })
 
 // mode="system" auto-detects OS dark mode via prefers-color-scheme
 // inversed flips the resolved mode (light↔dark)`,
-		notes: "Unified provider replacing 3 separate providers (theme, mode, config). Calls init() internally. mode='system' uses matchMedia('(prefers-color-scheme: dark)') and reactively updates.",
-		mistakes: `- Using ThemeProvider + ModeProvider + ConfigProvider separately → Use PyreonUI instead
-- Forgetting enrichTheme() → raw theme objects miss default breakpoints/spacing`
+		notes: `Unified provider replacing the previous theme / mode / config split (3 nested providers became 1). Accepts an enriched \`theme\` object (merge with defaults via \`enrichTheme()\`), a \`mode\` of \`'light' | 'dark' | 'system'\`, and an optional \`inversed\` flip. When \`mode='system'\`, the provider subscribes to \`matchMedia('(prefers-color-scheme: dark)')\` and re-resolves the mode reactively. Calls \`init()\` internally so consumers don\'t need to wire it up themselves. Whole-theme swaps (user-preference themes) propagate through the styler resolver and re-resolve CSS without remounting the VNode. See also: useMode, enrichTheme, init.`,
+		mistakes: `- Using \`ThemeProvider\` + \`ModeProvider\` + \`ConfigProvider\` separately — \`PyreonUI\` is the single replacement covering all three
+- Forgetting \`enrichTheme()\` — raw theme objects miss default breakpoints / spacing / unit utilities
+- Destructuring \`props\` inside the provider — components run once; destructuring captures values at setup. Read \`props.mode\` lazily inside reactive scopes
+- Re-augmenting the \`ThemeDefault\` / \`StylesDefault\` interfaces in your app — \`@pyreon/ui-theme\` already augments them; double-augmentation throws TS2320`
 	},
 	"ui-core/useMode": {
-		signature: "useMode(): Signal<'light' | 'dark'>",
+		signature: `useMode(): Signal<'light' | 'dark'>`,
 		example: `import { useMode } from "@pyreon/ui-core"
 
 const mode = useMode()
 // mode() returns "light" or "dark" (resolved, reactive)
 // Reflects OS preference when PyreonUI mode="system"`,
-		notes: "Returns the resolved mode as a reactive signal. When mode='system', reflects the OS preference. When inversed is true, the mode is flipped."
+		notes: `Returns the currently resolved mode as a reactive signal — \`'light'\` or \`'dark'\`. When the nearest \`PyreonUI\` ancestor uses \`mode='system'\`, the signal reflects the OS preference and updates when the user changes their system setting. When \`inversed\` is true on any ancestor, the mode is flipped before resolution. Component-scoped subscription — readers re-run only when the resolved mode actually changes. See also: PyreonUI.`,
+		mistakes: `- Reading \`useMode()\` without calling it — the value is a \`Signal\`; use \`mode()\` to read
+- Using \`useMode()\` outside any \`PyreonUI\` ancestor — falls back to a default but loses the reactive system / inversed handling`
 	},
 	"unistyle/enrichTheme": {
 		signature: "enrichTheme(theme: PartialTheme): Theme",
@@ -14657,15 +14866,97 @@ const theme = enrichTheme({
 })
 
 // Merges user overrides with default breakpoints, spacing, and units`,
-		notes: "Merges a partial theme with the full default theme (breakpoints, spacing, unit utilities). Always use when passing a theme to PyreonUI."
+		notes: "Merge a partial theme with the full default theme (breakpoints, spacing, unit utilities, fallback colors). Always call this before passing a user theme to `PyreonUI` — raw theme objects miss the default breakpoints and spacing scale that the rest of the UI system reads from. Idempotent: enriching an already-enriched theme is a no-op. See also: breakpoints, createMediaQueries.",
+		mistakes: `- Passing the raw partial theme to \`<PyreonUI theme={...}>\` without enriching — \`theme.breakpoints\` is undefined and every responsive prop falls back to the desktop value
+- Mutating the theme after passing it to \`PyreonUI\` — the styler resolver caches off the theme identity; clone + re-enrich for whole-theme swaps`
+	},
+	"unistyle/breakpoints": {
+		signature: "breakpoints(): Breakpoints",
+		example: `import { breakpoints } from '@pyreon/unistyle'
+
+const bp = breakpoints()
+// { xs: 0, sm: 640, md: 768, lg: 1024, xl: 1280, xxl: 1536 }`,
+		notes: "Return the default breakpoint set keyed by name (`xs`, `sm`, `md`, `lg`, `xl`, `xxl`) with min-width values in pixels. The same map is folded into `enrichTheme()` output, so most consumers read `theme.breakpoints` rather than calling this directly. Use it when you need the defaults outside a theme context (e.g. building a custom theme programmatically). See also: enrichTheme, createMediaQueries."
+	},
+	"unistyle/createMediaQueries": {
+		signature: "createMediaQueries(breakpoints: Breakpoints): Record<string, string>",
+		example: `import { createMediaQueries, breakpoints } from '@pyreon/unistyle'
+
+const queries = createMediaQueries(breakpoints())
+// { xs: '@media (min-width: 0)', sm: '@media (min-width: 640px)', md: '@media (min-width: 768px)', ... }`,
+		notes: "Build a record of media-query strings keyed by breakpoint name. Each value is a `min-width` query — `xs` is `(min-width: 0)`, `sm` becomes `(min-width: 640px)`, and so on. Used internally by `makeItResponsive()`; expose to consumers when they need to compose custom CSS-in-JS rules outside the responsive-prop pipeline. See also: breakpoints, makeItResponsive."
+	},
+	"unistyle/makeItResponsive": {
+		signature: "makeItResponsive<T>(options: { value: T | T[] | Record<string, T>; property: string; theme: Theme }): string",
+		example: `import { makeItResponsive } from '@pyreon/unistyle'
+
+makeItResponsive({ value: 16, property: 'padding', theme })
+// → 'padding: 16px;'
+
+makeItResponsive({ value: [8, 12, 16], property: 'padding', theme })
+// → 'padding: 8px; @media (min-width: 640px) { padding: 12px } @media (min-width: 768px) { padding: 16px }'
+
+makeItResponsive({ value: { xs: 8, md: 16, xl: 24 }, property: 'padding', theme })
+// → '@media (min-width: 0) { padding: 8px } @media (min-width: 768px) { padding: 16px } @media (min-width: 1280px) { padding: 24px }'`,
+		notes: "Resolve a responsive prop value to CSS for the current screen. Accepts three input shapes: single value (applies at all breakpoints), mobile-first array `[xs, sm, md, lg]` (each entry maps to the next breakpoint), or breakpoint object `{ xs: ..., md: ..., xl: ... }` (named keys map directly). The output is a CSS string with media queries already embedded; insert into a styled component template literal. See also: createMediaQueries, styles.",
+		mistakes: `- Passing CSS-spec property names (\`borderTopWidth\`) — unistyle uses property-first naming (\`borderWidthTop\`); the responsive transformer expects the unistyle convention
+- Forgetting to pass an enriched theme — without \`theme.breakpoints\`, the array form falls back to the first value at every breakpoint`
+	},
+	"unistyle/styles": {
+		signature: "styles(theme: Theme): string",
+		example: `import { styles, enrichTheme } from '@pyreon/unistyle'
+
+const theme = enrichTheme({ colors: { primary: '#3b82f6' } })
+const css = styles(theme)
+// → ':root { --color-primary: #3b82f6; --spacing-xs: 4px; ... }'`,
+		notes: `Generate the CSS string for a complete theme — colors, spacing, fonts, breakpoints, the works. Used to produce the cascade of CSS variables / global declarations that backs every styled component. Most consumers don\'t call this directly; the \`PyreonUI\` provider invokes it internally on theme mount. See also: enrichTheme, extendCss.`
+	},
+	"unistyle/alignContent": {
+		signature: `alignContent(options: { alignX?: AlignXKey; alignY?: AlignYKey; direction?: 'row' | 'column' | 'inline' | 'rows' }): string`,
+		example: `import { alignContent } from '@pyreon/unistyle'
+
+alignContent({ alignX: 'center', alignY: 'start', direction: 'row' })
+// → 'justify-content: center; align-items: flex-start;'
+
+alignContent({ alignX: 'spaceBetween', direction: 'inline' })
+// → 'justify-content: space-between;'`,
+		notes: `Resolve \`alignX\` / \`alignY\` / \`direction\` shorthand to the matching flex / grid CSS (\`justify-content\`, \`align-items\`). The Element / Row / Column primitives use this internally — it\'s exposed for custom layout components that want the same alignment semantics. \`direction: "inline"\` maps to \`row\`; \`direction: "rows"\` maps to \`column\`. See also: makeItResponsive.`
+	},
+	"unistyle/extendCss": {
+		signature: "extendCss(base: ExtendCss, override?: ExtendCss): ExtendCss",
+		example: `import { extendCss } from '@pyreon/unistyle'
+
+const base = { color: 'red', hover: { color: 'darkred' } }
+const extended = extendCss(base, { hover: { background: 'pink' } })
+// → { color: 'red', hover: { color: 'darkred', background: 'pink' } }`,
+		notes: "Extend a CSS definition (theme block, style descriptor) with overrides — deep-merges nested objects without losing the base. Used by rocketstyle dimension chains to layer dimension-specific CSS over a baseline. The base is not mutated; the result is a new object. See also: styles."
+	},
+	"unistyle/stripUnit": {
+		signature: "stripUnit(value: string | number): number",
+		example: `import { stripUnit } from '@pyreon/unistyle'
+
+stripUnit('16px')   // → 16
+stripUnit('1.5rem') // → 1.5
+stripUnit(16)       // → 16`,
+		notes: "Strip the unit suffix from a CSS value and return the numeric part (`\"16px\"` → `16`, `\"1.5rem\"` → `1.5`). Returns the input unchanged when already a number. Useful for arithmetic on theme values declared as strings (`\"16px\"`) without manually parsing. See also: value, values."
+	},
+	"unistyle/value": {
+		signature: "value(input: PropertyValue, fallback?: PropertyValue): UnitValue",
+		example: `import { value } from '@pyreon/unistyle'
+
+value(16)         // → { value: 16, unit: 'px' }
+value('1.5rem')   // → { value: 1.5, unit: 'rem' }
+value('50%')      // → { value: 50, unit: '%' }
+value('garbage', 0) // → { value: 0, unit: 'px' }`,
+		notes: "Parse and validate a single property value into a `UnitValue` shape (`{ value, unit }`). Accepts numbers (treated as pixels), strings with units (`\"16px\"`, `\"1rem\"`, `\"50%\"`), or objects already in `UnitValue` form. Optional `fallback` is returned when the input is invalid. The companion `values()` does the same over an array. See also: stripUnit, values."
 	},
 	"rx/rx": {
-		signature: "Readonly<{ filter, map, sortBy, groupBy, keyBy, uniqBy, take, skip, last, chunk, flatten, find, mapValues, count, sum, min, max, average, distinct, scan, combine, debounce, throttle, search, pipe }>",
+		signature: "Readonly<{ filter, map, sortBy, groupBy, keyBy, uniqBy, take, skip, last, chunk, flatten, find, mapValues, first, compact, reverse, partition, takeWhile, dropWhile, unique, sample, count, sum, min, max, average, reduce, every, some, distinct, scan, combine, zip, merge, debounce, throttle, search, pipe }>",
 		example: `const active = rx.filter(users, u => u.active)      // Computed<User[]>
 const sorted = rx.sortBy(active, 'name')             // Computed<User[]>
 const total = rx.sum(users, u => u.age)              // Computed<number>
 const grouped = rx.groupBy(users, u => u.department) // Computed<Map<string, User[]>>`,
-		notes: "Namespaced object exposing all 24 reactive transform functions plus `pipe`. Use `rx.filter(...)` for dot-notation style, or destructure individual functions for tree-shaking. Every function is overloaded: `Signal<T[]>` input produces `Computed<T[]>` that auto-tracks, plain `T[]` input produces a static result. See also: pipe, filter.",
+		notes: "Namespaced object exposing all 37 reactive transform functions plus `pipe`. Use `rx.filter(...)` for dot-notation style, or destructure individual functions for tree-shaking. Every function is overloaded: `Signal<T[]>` input produces `Computed<T[]>` that auto-tracks, plain `T[]` input produces a static result. See also: pipe, filter.",
 		mistakes: `- Expecting \`rx.filter(signal, pred)\` to return a plain array — signal inputs always produce \`Computed\` outputs. Call the result to read: \`active()\`
 - Passing a signal accessor (\`() => items()\`) instead of the signal itself — pass \`items\` not \`() => items()\`; the function checks for \`.subscribe\` to detect signals`
 	},
@@ -14759,39 +15050,22 @@ setUrlRouter(router)
 } from '@pyreon/document-primitives'
 import { download } from '@pyreon/document'
 
-interface Resume { name: string; headline: string }
-
-function ResumeTemplate(props: { resume: () => Resume }) {
-  return (
-    // title and author accept reactive accessors — extractDocNode
-    // resolves them at extraction time, so each export click reads
-    // the LIVE value from the underlying signal
-    <DocDocument
-      title={() => \`\${props.resume().name} — Resume\`}
-      author={() => props.resume().name}
-    >
-      <DocPage>
-        <DocHeading level="h1">{() => props.resume().name}</DocHeading>
-        <DocText>{() => props.resume().headline}</DocText>
-      </DocPage>
-    </DocDocument>
-  )
-}
-
-// One-step extraction. The two-step createDocumentExport(...).getDocNode()
-// form is still exported for callers that want to pass the helper
-// object around, but extractDocNode is the recommended form.
-const tree = extractDocNode(() => <ResumeTemplate resume={store.resume} />)
-await download(tree, 'resume.pdf')
-await download(tree, 'resume.docx')
-await download(tree, 'resume.html')
-await download(tree, 'resume.md')`,
-		notes: "18 primitives: DocDocument, DocPage, DocSection, DocRow, DocColumn, DocHeading, DocText, DocLink, DocImage, DocTable, DocList, DocListItem, DocCode, DocDivider, DocSpacer, DocButton, DocQuote, DocPageBreak. Same component tree renders in browser AND exports — primitives carry _documentType statics that extractDocumentTree (from @pyreon/connector-document) walks to produce a DocNode for @pyreon/document's render() to consume. DocDocument's title/author/subject accept either a string OR a `() => string` accessor; function values are stored in _documentProps and resolved at extraction time so reactive metadata works without `const initial = get()` workarounds. PR #197 also fixed a latent bug in extractDocumentTree: it now CALLS rocketstyle component functions to read post-attrs _documentProps, where before it only looked at the JSX vnode's props directly — every primitive's metadata was silently dropped during export until that fix landed.",
-		mistakes: `- Calling props.title() at the top of a template body to "fix" reactivity — components run ONCE at mount, so this captures the initial value forever. Pass the accessor through to DocDocument as-is: <DocDocument title={() => get().name}>
-- DocRow direction: layout props (direction, gap) go in .attrs() not .theme(). Element accepts 'inline' | 'rows' | 'reverseInline' | 'reverseRows' — 'row' is NOT valid
-- For text children reactivity, pass a signal accessor and read inside body: <DocText>{() => store.field()}</DocText>
-- Don't declare runtime-filled fields (tag, _documentProps) in the rocketstyle .attrs<P>() generic — they leak as required JSX props
-- Using createDocumentExport(...).getDocNode() in new code — prefer extractDocNode(fn) which is one call instead of two. createDocumentExport is kept for backward compat`
+const tree = extractDocNode(() => (
+  <DocDocument title="Quarterly Report" author="Aisha">
+    <DocPage>
+      <DocHeading level="h1">Q4 Results</DocHeading>
+      <DocText>Revenue grew 23% YoY.</DocText>
+    </DocPage>
+  </DocDocument>
+))
+await download(tree, 'report.pdf')
+await download(tree, 'report.docx')`,
+		notes: `18 primitives: \`DocDocument\`, \`DocPage\`, \`DocSection\`, \`DocRow\`, \`DocColumn\`, \`DocHeading\`, \`DocText\`, \`DocLink\`, \`DocImage\`, \`DocTable\`, \`DocList\`, \`DocListItem\`, \`DocCode\`, \`DocDivider\`, \`DocSpacer\`, \`DocButton\`, \`DocQuote\`, \`DocPageBreak\`. Same component tree renders in browser AND exports — primitives carry \`_documentType\` statics that \`extractDocumentTree\` (from \`@pyreon/connector-document\`) walks to produce a \`DocNode\` for \`@pyreon/document\`\'s \`render()\` to consume. \`DocDocument\`\'s \`title\` / \`author\` / \`subject\` accept either a string OR a \`() => string\` accessor; function values are stored in \`_documentProps\` and resolved at extraction time so reactive metadata works without \`const initial = get()\` workarounds. PR #197 also fixed a latent bug in \`extractDocumentTree\`: it now CALLS rocketstyle component functions to read post-attrs \`_documentProps\`, where before it only looked at the JSX vnode\'s props directly — every primitive\'s metadata was silently dropped during export until that fix landed. See also: createDocumentExport.`,
+		mistakes: `- Calling \`props.title()\` at the top of a template body to "fix" reactivity — components run ONCE at mount, so this captures the initial value forever. Pass the accessor through to DocDocument as-is: \`<DocDocument title={() => get().name}>\`
+- DocRow direction: layout props (direction, gap) go in \`.attrs()\` not \`.theme()\`. Element accepts \`'inline'\` | \`'rows'\` | \`'reverseInline'\` | \`'reverseRows'\` — \`'row'\` is NOT valid
+- For text children reactivity, pass a signal accessor and read inside body: \`<DocText>{() => store.field()}</DocText>\`
+- Don't declare runtime-filled fields (\`tag\`, \`_documentProps\`) in the rocketstyle \`.attrs<P>()\` generic — they leak as required JSX props
+- Using \`createDocumentExport(...).getDocNode()\` in new code — prefer \`extractDocNode(fn)\` which is one call instead of two. \`createDocumentExport\` is kept for backward compat`
 	},
 	"document-primitives/createDocumentExport": {
 		signature: "createDocumentExport(templateFn: () => VNode): { getDocNode(): DocNode }",
@@ -14801,10 +15075,651 @@ import { createDocumentExport } from '@pyreon/document-primitives'
 
 const helper = createDocumentExport(() => <Resume name="Aisha" />)
 const tree = helper.getDocNode()`,
-		notes: "Wrapper around extractDocNode. The wrapper-object form is kept for callers that want to pass the helper around (e.g. to wrapper components that take a DocumentExport instance). New code should use extractDocNode(templateFn) which is one call instead of two."
+		notes: "Wrapper around `extractDocNode`. The wrapper-object form is kept for callers that want to pass the helper around (e.g. to wrapper components that take a `DocumentExport` instance). New code should use `extractDocNode(templateFn)` which is one call instead of two. See also: extractDocNode."
+	},
+	"document-primitives/DocDocument": {
+		signature: "(props: { title?: string | (() => string); author?: string | (() => string); subject?: string | (() => string); children: VNodeChild }) => VNodeChild",
+		example: `<DocDocument title="Quarterly Report" author="Aisha" subject="Q4 2025">
+  <DocPage>...</DocPage>
+</DocDocument>
+
+// Reactive metadata via accessor
+<DocDocument title={() => \`\${user().name} — Resume\`}>
+  <DocPage>...</DocPage>
+</DocDocument>`,
+		notes: "Root container for a document tree — produces a `_documentType: \"document\"` node. Accepts optional metadata: `title`, `author`, `subject`. Each accepts either a plain string OR a `() => string` accessor; function values are stored in `_documentProps` and resolved at extraction time so each export call reads the LIVE value from any underlying signal. See also: DocPage, extractDocNode."
+	},
+	"document-primitives/DocPage": {
+		signature: `(props: { size?: string; orientation?: 'portrait' | 'landscape'; children: VNodeChild }) => VNodeChild`,
+		example: `<DocDocument>
+  <DocPage size="A4" orientation="portrait">
+    <DocHeading level="h1">Page 1</DocHeading>
+  </DocPage>
+  <DocPage size="A4" orientation="landscape">
+    <DocHeading level="h1">Page 2 — landscape</DocHeading>
+  </DocPage>
+</DocDocument>`,
+		notes: "A page boundary inside a `DocDocument`. Paginated outputs (PDF, DOCX) treat each `DocPage` as a separate page; flow outputs (HTML, Markdown) render the contents inline with no page boundary. `size` and `orientation` configure paginated formats — common values: `\"A4\"`, `\"Letter\"`, `\"Legal\"`. See also: DocDocument, DocPageBreak."
+	},
+	"document-primitives/DocSection": {
+		signature: `(props: { direction?: 'column' | 'row'; children: VNodeChild }) => VNodeChild`,
+		example: `<DocPage>
+  <DocSection direction="column">
+    <DocHeading level="h2">Introduction</DocHeading>
+    <DocText>Background paragraph.</DocText>
+  </DocSection>
+</DocPage>`,
+		notes: "Semantic grouping inside a page. Default `direction` is `\"column\"` (children stack vertically); `\"row\"` arranges them horizontally. Use to group related content for visual rhythm and for export targets that emit semantic section markers (HTML `<section>`, DOCX section breaks). See also: DocRow, DocColumn."
+	},
+	"document-primitives/DocRow": {
+		signature: "(props: { children: VNodeChild }) => VNodeChild",
+		example: `<DocRow>
+  <DocText>Name:</DocText>
+  <DocText>Aisha Patel</DocText>
+</DocRow>`,
+		notes: "Horizontal layout container — children flow inline with a fixed 8px gap. Use for side-by-side content (label + value pairs, columns of metadata, button rows). Layout-only — no user-configurable props on this primitive; for columns with custom widths use `DocColumn` inside. See also: DocColumn, DocSection."
+	},
+	"document-primitives/DocColumn": {
+		signature: "(props: { width?: number | string; children: VNodeChild }) => VNodeChild",
+		example: `<DocRow>
+  <DocColumn width="30%">
+    <DocText>Label</DocText>
+  </DocColumn>
+  <DocColumn width="70%">
+    <DocText>Value</DocText>
+  </DocColumn>
+</DocRow>`,
+		notes: `A column inside a row layout. Optional \`width\` controls the column\'s share of the row — accepts a number (interpreted as pixels) or a string (\`"50%"\`, \`"1fr"\`). When omitted, columns share available width equally. Most common shape is \`<DocRow><DocColumn width="30%" /> <DocColumn width="70%" /></DocRow>\`. See also: DocRow, DocSection.`
+	},
+	"document-primitives/DocHeading": {
+		signature: `(props: { level?: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'; children: VNodeChild }) => VNodeChild`,
+		example: `<DocHeading level="h1">Quarterly Report</DocHeading>
+<DocHeading level="h2">Q4 Results</DocHeading>
+<DocHeading level="h3">Revenue Breakdown</DocHeading>`,
+		notes: "Heading text — `level` (`\"h1\"` through `\"h6\"`) controls both visual size and the semantic level emitted to outputs (HTML `<h1>...<h6>`, DOCX heading styles, Markdown `#`...`######`). Default `level` is `\"h1\"`. Used for document structure that downstream tooling can build a TOC from. See also: DocText, DocSection."
+	},
+	"document-primitives/DocText": {
+		signature: "(props: { children: VNodeChild }) => VNodeChild",
+		example: `<DocText>Static paragraph content.</DocText>
+
+// Reactive children
+<DocText>{() => \`Hello, \${user().name}\`}</DocText>`,
+		notes: "Paragraph / inline text. The most common primitive — wraps any text content for the document. Children may be string literals OR signal accessors (`{() => store.field()}`) for reactive content. Visual styling (font weight, variant) is controlled via rocketstyle dimension props on the wrapping component definition. See also: DocHeading, DocLink."
+	},
+	"document-primitives/DocLink": {
+		signature: "(props: { href?: string; children: VNodeChild }) => VNodeChild",
+		example: `<DocText>
+  Read more on
+  <DocLink href="https://pyreon.dev">our blog</DocLink>
+  for the latest releases.
+</DocText>`,
+		notes: "Hyperlink within text. `href` is the URL — defaults to `\"#\"`. Outputs that support hyperlinks (HTML, PDF, DOCX, email) render this as a clickable link; flat outputs (plain text, certain Slack variants) render the link target inline as `text (href)`. See also: DocText."
+	},
+	"document-primitives/DocImage": {
+		signature: "(props: { src: string; alt?: string; width?: number; height?: number; caption?: string }) => VNodeChild",
+		example: `<DocImage
+  src="/charts/q4-revenue.png"
+  alt="Revenue grew 23% in Q4"
+  width={600}
+  height={400}
+  caption="Figure 1: Quarterly revenue, 2024-2025"
+/>`,
+		notes: "An image embedded in the document. `src` is the image URL or data URI. `alt` is the accessible description (also used as fallback text in non-visual outputs). `width` / `height` constrain dimensions in pixels. Optional `caption` renders a caption beneath the image. See also: DocCode."
+	},
+	"document-primitives/DocTable": {
+		signature: "(props: { columns: TableColumn[]; rows: TableRow[]; headerStyle?: object; striped?: boolean; bordered?: boolean; caption?: string }) => VNodeChild",
+		example: `<DocTable
+  caption="Q4 results by region"
+  bordered
+  striped
+  columns={[
+    { key: 'region', label: 'Region', align: 'left' },
+    { key: 'revenue', label: 'Revenue', align: 'right' },
+    { key: 'growth', label: 'YoY Growth', align: 'right' },
+  ]}
+  rows={[
+    { region: 'NA', revenue: '$12.4M', growth: '+23%' },
+    { region: 'EU', revenue: '$8.7M', growth: '+18%' },
+    { region: 'APAC', revenue: '$5.1M', growth: '+41%' },
+  ]}
+/>`,
+		notes: "Tabular data. `columns` defines the header cells (label, key, optional alignment). `rows` is an array of data rows keyed by column key. `striped` adds alternating row backgrounds; `bordered` adds cell borders; `caption` renders an accessible table caption. Both `rows` and `columns` are filtered before reaching the DOM via `.attrs(..., { filter: [...] })` because `HTMLTableElement.rows` / `.cells` are read-only DOM properties — assignment would crash. See also: DocList, DocSection."
+	},
+	"document-primitives/DocList": {
+		signature: "(props: { ordered?: boolean; children: VNodeChild }) => VNodeChild",
+		example: `<DocList>
+  <DocListItem>First bullet</DocListItem>
+  <DocListItem>Second bullet</DocListItem>
+</DocList>
+
+<DocList ordered>
+  <DocListItem>First step</DocListItem>
+  <DocListItem>Second step</DocListItem>
+</DocList>`,
+		notes: "Bulleted (default) or numbered (`ordered`) list. Children are typically `DocListItem` instances. Outputs map this to the right native list type — HTML `<ul>` / `<ol>`, Markdown `-` / `1.`, DOCX list styles. See also: DocListItem."
+	},
+	"document-primitives/DocListItem": {
+		signature: "(props: { children: VNodeChild }) => VNodeChild",
+		example: `<DocList>
+  <DocListItem>Top-level item</DocListItem>
+  <DocListItem>
+    Item with nested list
+    <DocList>
+      <DocListItem>Nested A</DocListItem>
+      <DocListItem>Nested B</DocListItem>
+    </DocList>
+  </DocListItem>
+</DocList>`,
+		notes: `Single item inside a \`DocList\`. Children may be plain text, \`DocText\`, nested \`DocList\` for sublists, or any other inline primitive. Visual marker (bullet vs number) is decided by the parent list\'s \`ordered\` prop, not by the item. See also: DocList.`
+	},
+	"document-primitives/DocCode": {
+		signature: "(props: { language?: string; children: VNodeChild }) => VNodeChild",
+		example: `<DocCode language="typescript">{
+\`const flow = createFlow({
+  nodes: [{ id: '1', position: { x: 0, y: 0 } }],
+  edges: [],
+})\`
+}</DocCode>`,
+		notes: "Monospace code block. Optional `language` hint enables syntax highlighting in outputs that support it (HTML via Prism / Shiki, Markdown fenced code blocks with language tag). Whitespace is preserved verbatim — pass code as a single string child to keep newlines. See also: DocText."
+	},
+	"document-primitives/DocDivider": {
+		signature: "(props: { color?: string; thickness?: number }) => VNodeChild",
+		example: `<DocText>Above the divider.</DocText>
+<DocDivider color="#e5e7eb" thickness={1} />
+<DocText>Below the divider.</DocText>`,
+		notes: "Horizontal rule — visual section separator. `color` controls the line color (any CSS color string); `thickness` controls the line thickness in pixels. Outputs map this to native dividers — HTML `<hr>`, Markdown `---`, DOCX horizontal rule. See also: DocSpacer."
+	},
+	"document-primitives/DocSpacer": {
+		signature: "(props: { height?: number }) => VNodeChild",
+		example: `<DocSection>
+  <DocHeading level="h2">Section A</DocHeading>
+  <DocText>Content...</DocText>
+  <DocSpacer height={32} />
+  <DocHeading level="h2">Section B</DocHeading>
+  <DocText>More content...</DocText>
+</DocSection>`,
+		notes: "Vertical whitespace — adds a blank vertical gap. `height` is in pixels (default 16). Use to space out content beyond what `DocSection` / `DocPage` margins provide. In flow outputs this becomes a styled blank block; in plain-text outputs, a sequence of newlines. See also: DocDivider."
+	},
+	"document-primitives/DocButton": {
+		signature: "(props: { href?: string; children: VNodeChild }) => VNodeChild",
+		example: `<DocButton href="https://pyreon.dev/signup">
+  Get started
+</DocButton>`,
+		notes: "Call-to-action button. Renders as a styled clickable element in HTML / email outputs (mail-safe button table layout for email), and as a labeled link in PDF / DOCX. `href` is the action URL — defaults to `\"#\"`. Visual style (variant) is controlled via rocketstyle dimensions on the component definition. See also: DocLink."
+	},
+	"document-primitives/DocQuote": {
+		signature: "(props: { borderColor?: string; children: VNodeChild }) => VNodeChild",
+		example: `<DocQuote borderColor="#3b82f6">
+  <DocText>"The best way to predict the future is to build it."</DocText>
+  <DocText>— Aisha Patel, Q4 keynote</DocText>
+</DocQuote>`,
+		notes: "Block quote — sets off a quoted passage with an indented left border. `borderColor` controls the indicator stripe (any CSS color). Outputs map this to native quote styling — HTML `<blockquote>`, Markdown `> ...`, DOCX quote style. See also: DocText."
+	},
+	"document-primitives/DocPageBreak": {
+		signature: "() => VNodeChild",
+		example: `<DocPage>
+  <DocHeading level="h1">Section 1</DocHeading>
+  <DocText>...long content...</DocText>
+  <DocPageBreak />
+  <DocHeading level="h1">Section 2 — new page</DocHeading>
+</DocPage>`,
+		notes: "Explicit page boundary inside a `DocPage`. Forces the renderer to start a new page at this point in paginated outputs (PDF, DOCX). In flow outputs (HTML, Markdown), it renders as visible whitespace or is omitted entirely. Use for explicit pagination control beyond what `DocPage` boundaries already provide. See also: DocPage."
 	}
 };
 
+//#endregion
+//#region src/changelog.ts
+/**
+* Changelog parser + registry for the `get_changelog` MCP tool (T2.5.8).
+*
+* AI agents often ask "what changed in @pyreon/X recently?" before
+* writing code against the package — a stale mental model is a
+* frequent bug source. `get_changelog` surfaces recent release notes
+* without the agent having to scrape `git log` or read raw markdown.
+*
+* The parser reads `CHANGELOG.md` files populated by changesets. Each
+* changeset-managed package has a predictable shape:
+*
+*   # @pyreon/<name>
+*
+*   ## <version>
+*
+*   ### Minor Changes | Patch Changes | Major Changes
+*
+*   - [#PR] [`sha`] Thanks [@author]! - <body>
+*
+*     <continuation>
+*
+*   - Updated dependencies [[`sha`]]:
+*     - @pyreon/core@0.13.0
+*
+* The parser extracts each `## <version>` section, collecting the
+* user-facing body plus the dependency bumps separately. Consumers
+* typically want the N most recent non-empty versions (the tool's
+* default is 5).
+*/
+function findMonorepoRoot(startDir) {
+	let dir = resolve(startDir);
+	for (let i = 0; i < 30; i++) {
+		if (existsSync(join(dir, "packages")) && statSync(join(dir, "packages")).isDirectory()) return dir;
+		const parent = dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+	return null;
+}
+function walkPackages(dir, out, depth = 0) {
+	if (depth > 4) return;
+	let entries;
+	try {
+		entries = readdirSync(dir);
+	} catch {
+		return;
+	}
+	for (const name of entries) {
+		if (name.startsWith(".") || name === "node_modules") continue;
+		const full = join(dir, name);
+		let isDir = false;
+		try {
+			isDir = statSync(full).isDirectory();
+		} catch {
+			continue;
+		}
+		if (!isDir) continue;
+		const pkgJsonPath = join(full, "package.json");
+		const changelogPath = join(full, "CHANGELOG.md");
+		if (existsSync(pkgJsonPath) && existsSync(changelogPath)) {
+			try {
+				const pkg = JSON.parse(readFileSync(pkgJsonPath, "utf8"));
+				if (typeof pkg.name === "string") out.push({
+					name: pkg.name,
+					dir: full,
+					changelogPath
+				});
+			} catch {}
+			continue;
+		}
+		if (existsSync(pkgJsonPath)) continue;
+		walkPackages(full, out, depth + 1);
+	}
+}
+/**
+* Parse a CHANGELOG.md body into version entries. The parser assumes
+* the changesets format but tolerates:
+*  - empty `## <version>` sections with no body (ceremonial bumps)
+*  - mixed `### Patch Changes` / `### Minor Changes` / `### Major Changes` under one version
+*  - bullets with multi-line continuations (indented with 2+ spaces)
+*  - `- Updated dependencies …` bullets, split off separately
+*/
+function parseChangelog(body) {
+	const lines = body.split("\n");
+	const entries = [];
+	let currentVersion = null;
+	let currentBullets = [];
+	let currentDepUpdates = [];
+	let currentBuf = [];
+	let bufKind = null;
+	const flushBullet = () => {
+		if (currentBuf.length > 0 && bufKind !== null) {
+			const text = currentBuf.join("\n").trim();
+			if (text.length > 0) if (bufKind === "dep") currentDepUpdates.push(text);
+			else currentBullets.push(text);
+		}
+		currentBuf = [];
+		bufKind = null;
+	};
+	const flushVersion = () => {
+		flushBullet();
+		if (currentVersion !== null) entries.push({
+			version: currentVersion,
+			changes: currentBullets,
+			dependencyUpdates: currentDepUpdates,
+			empty: currentBullets.length === 0 && currentDepUpdates.length === 0
+		});
+		currentVersion = null;
+		currentBullets = [];
+		currentDepUpdates = [];
+	};
+	for (const line of lines) {
+		const versionMatch = /^## (.+)$/.exec(line);
+		if (versionMatch) {
+			flushVersion();
+			currentVersion = versionMatch[1].trim();
+			continue;
+		}
+		if (currentVersion === null) continue;
+		if (/^### /.test(line)) {
+			flushBullet();
+			continue;
+		}
+		if (/^- /.test(line)) {
+			flushBullet();
+			currentBuf = [line.replace(/^- /, "")];
+			bufKind = /^- Updated dependencies/.test(line) ? "dep" : "change";
+			continue;
+		}
+		if (bufKind !== null && line.length > 0 && /^\s/.test(line)) {
+			currentBuf.push(line.replace(/^ {2,4}/, ""));
+			continue;
+		}
+		if (bufKind !== null && line === "") {
+			currentBuf.push("");
+			continue;
+		}
+		flushBullet();
+	}
+	flushVersion();
+	return entries;
+}
+function loadChangelogRegistry(startDir = process.cwd()) {
+	const root = findMonorepoRoot(startDir);
+	if (!root) return {
+		root: null,
+		byName: /* @__PURE__ */ new Map()
+	};
+	const found = [];
+	walkPackages(join(root, "packages"), found);
+	const byName = /* @__PURE__ */ new Map();
+	for (const { name, dir, changelogPath } of found) {
+		let source;
+		try {
+			source = readFileSync(changelogPath, "utf8");
+		} catch {
+			continue;
+		}
+		byName.set(name, {
+			packageName: name,
+			path: changelogPath,
+			dir,
+			entries: parseChangelog(source)
+		});
+	}
+	return {
+		root,
+		byName
+	};
+}
+function findChangelog(registry, packageName) {
+	if (registry.byName.has(packageName)) return registry.byName.get(packageName);
+	if (!packageName.startsWith("@")) {
+		const qualified = `@pyreon/${packageName}`;
+		if (registry.byName.has(qualified)) return registry.byName.get(qualified);
+	}
+	return null;
+}
+function suggestChangelogs(registry, needle) {
+	const lower = needle.toLowerCase();
+	const matches = [];
+	for (const name of registry.byName.keys()) if (name.toLowerCase().includes(lower)) matches.push(name);
+	return matches.slice(0, 5);
+}
+/**
+* Compare two semver-ish version strings. Returns negative if `a < b`,
+* positive if `a > b`, zero if equal. Pre-release suffixes (`-alpha.3`)
+* are compared lexicographically AFTER the numeric portion.
+*
+* Scoped to what changesets actually produce (`0.13.0`, `1.0.0-alpha.3`,
+* `2.5.1`). Not a general-purpose semver implementation — we intentionally
+* do not depend on an external semver package for a 30-line need.
+*/
+function compareVersions(a, b) {
+	const parse = (v) => {
+		const [core, ...preParts] = v.split("-");
+		const pre = preParts.join("-");
+		return {
+			parts: core.split(".").map((n) => {
+				const num = Number.parseInt(n, 10);
+				return Number.isNaN(num) ? 0 : num;
+			}),
+			pre
+		};
+	};
+	const pa = parse(a);
+	const pb = parse(b);
+	const maxLen = Math.max(pa.parts.length, pb.parts.length);
+	for (let i = 0; i < maxLen; i++) {
+		const ai = pa.parts[i] ?? 0;
+		const bi = pb.parts[i] ?? 0;
+		if (ai !== bi) return ai - bi;
+	}
+	if (pa.pre === "" && pb.pre !== "") return 1;
+	if (pa.pre !== "" && pb.pre === "") return -1;
+	if (pa.pre < pb.pre) return -1;
+	if (pa.pre > pb.pre) return 1;
+	return 0;
+}
+/**
+* Filter entries to those strictly NEWER than `sinceVersion`. Ceremonial
+* bumps are preserved — the caller decides whether to also filter them
+* via the `empty` flag. Returns all entries in file order (newest first)
+* that satisfy `compareVersions(entry.version, sinceVersion) > 0`.
+*/
+function filterSince(entries, sinceVersion) {
+	return entries.filter((e) => compareVersions(e.version, sinceVersion) > 0);
+}
+/**
+* Format a package's changelog for the MCP response. Filters empty
+* versions and slices to the `limit` most recent.
+*/
+function formatChangelog(changelog, { limit = 5, includeDependencyUpdates = false, since } = {}) {
+	const nonEmpty = changelog.entries.filter((e) => !e.empty);
+	const afterSince = since ? filterSince(nonEmpty, since) : nonEmpty;
+	const sliced = afterSince.slice(0, limit);
+	if (sliced.length === 0) {
+		if (since) return `# ${changelog.packageName} — no changes since v${since}\n\nThe package has ${nonEmpty.length} substantive version entr${nonEmpty.length === 1 ? "y" : "ies"} in total, but none are newer than v${since}. The known latest substantive version is v${nonEmpty[0]?.version ?? "(none)"}. Drop the \`since\` filter, or pass a lower floor, to see earlier entries.`;
+		const ceremonial = changelog.entries.length;
+		const versions = changelog.entries.slice(0, 3).map((e) => e.version).join(", ");
+		return `# ${changelog.packageName} — no substantive changes\n\nCHANGELOG.md has ${ceremonial} version entr${ceremonial === 1 ? "y" : "ies"} (${versions}${ceremonial > 3 ? ", …" : ""}) but every one is a ceremonial version bump with no user-facing body. This usually means the package only received dependency updates during the captured history. Check \`get_changelog({ includeDependencyUpdates: true })\` or the git log if you need the bumps themselves.`;
+	}
+	const parts = [];
+	const sinceSuffix = since ? ` since v${since}` : "";
+	parts.push(`# ${changelog.packageName} — changelog${sinceSuffix} (${sliced.length}/${afterSince.length} shown)`);
+	parts.push("");
+	if (afterSince.length > limit) {
+		parts.push(`Showing the ${limit} most recent substantive versions${sinceSuffix}. ${afterSince.length - limit} older versions omitted. Pass \`limit\` to expand.`);
+		parts.push("");
+	}
+	for (const entry of sliced) {
+		parts.push(`## ${entry.version}`);
+		parts.push("");
+		for (const change of entry.changes) {
+			parts.push(`- ${change}`);
+			parts.push("");
+		}
+		if (includeDependencyUpdates && entry.dependencyUpdates.length > 0) {
+			parts.push("### Updated dependencies");
+			for (const dep of entry.dependencyUpdates) parts.push(`- ${dep}`);
+			parts.push("");
+		}
+	}
+	return parts.join("\n").trimEnd();
+}
+/**
+* Format the registry as an index when `get_changelog` is called
+* with no package name. Lists every package with its latest
+* substantive version (for orientation).
+*/
+function formatChangelogIndex(registry) {
+	if (!registry.root || registry.byName.size === 0) return "No changelogs found. This tool reads CHANGELOG.md files from the Pyreon monorepo. If you are running the MCP in a consumer project without the Pyreon packages directory, run the MCP from the Pyreon repo root to browse releases.";
+	const names = [...registry.byName.keys()].sort();
+	const parts = [`# Pyreon Changelogs (${names.length} packages)`, ""];
+	parts.push(`Call \`get_changelog({ package: "<name>" })\` for per-package release notes. Pass \`limit\` to control how many versions (default 5). The short form \`foo\` maps to \`@pyreon/foo\`.`);
+	parts.push("");
+	for (const name of names) {
+		const latest = registry.byName.get(name).entries.find((e) => !e.empty);
+		const summary = latest ? `latest substantive: v${latest.version}` : "ceremonial bumps only";
+		parts.push(`- **${name}** — ${summary}`);
+	}
+	return parts.join("\n");
+}
+
+//#endregion
+//#region src/patterns.ts
+/**
+* Pattern registry for the `get_pattern` MCP tool (T2.5.3).
+*
+* Each pattern answers a "how do I do X the right way" question with a
+* code example and rationale. The content is the body of the
+* corresponding `docs/patterns/<name>.md` file, discovered at runtime
+* by walking up from `process.cwd()` to the nearest repo that contains
+* `docs/patterns/`.
+*
+* Why a filesystem lookup instead of bundled content: the patterns
+* belong in the VitePress site (they're first-class docs), and having
+* the MCP fetch them live means the AI sees the same text the human
+* would. Bundling copies would drift.
+*
+* Fallback: if no `docs/patterns/` exists in the walk (e.g. the MCP is
+* running in a consumer repo), the tool reports the miss and lists
+* what patterns WOULD be available if running against the Pyreon
+* monorepo. The list itself is seeded from the directory walk, so
+* adding a new pattern file makes it discoverable without code changes.
+*/
+const PATTERN_PATH_CANDIDATES = [[
+	"docs",
+	"docs",
+	"patterns"
+], ["docs", "patterns"]];
+function findPatternsDir(startDir) {
+	let dir = resolve(startDir);
+	for (let i = 0; i < 30; i++) {
+		for (const segments of PATTERN_PATH_CANDIDATES) {
+			const candidate = join(dir, ...segments);
+			if (existsSync(candidate) && statSync(candidate).isDirectory()) return candidate;
+		}
+		const parent = dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+	return null;
+}
+/**
+* Minimal frontmatter parser. Supports:
+*   title: string (unquoted or quoted)
+*   summary: string
+*   seeAlso: [one, two, three]  OR  seeAlso:\n  - one\n  - two
+*
+* Anything else is ignored. Full YAML would be overkill here.
+*/
+function parseFrontmatter(source) {
+	const match = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/.exec(source);
+	if (!match) return {
+		meta: {},
+		body: source
+	};
+	const rawMeta = match[1];
+	const body = match[2].trim();
+	const meta = {};
+	const lines = rawMeta.split("\n");
+	let seeAlsoActive = false;
+	const seeAlsoItems = [];
+	for (const line of lines) {
+		if (seeAlsoActive) {
+			const bullet = /^\s*-\s*(.+?)\s*$/.exec(line);
+			if (bullet) {
+				seeAlsoItems.push(bullet[1]);
+				continue;
+			}
+			seeAlsoActive = false;
+		}
+		const kv = /^([a-zA-Z]+):\s*(.*)$/.exec(line);
+		if (!kv) continue;
+		const key = kv[1];
+		const value = kv[2].trim();
+		if (key === "title") meta.title = value.replace(/^["']|["']$/g, "");
+		else if (key === "summary") meta.summary = value.replace(/^["']|["']$/g, "");
+		else if (key === "seeAlso") {
+			if (value.startsWith("[") && value.endsWith("]")) meta.seeAlso = value.slice(1, -1).split(",").map((s) => s.trim().replace(/^["']|["']$/g, "")).filter(Boolean);
+			else if (value === "") seeAlsoActive = true;
+		}
+	}
+	if (seeAlsoActive && seeAlsoItems.length > 0) meta.seeAlso = seeAlsoItems;
+	return {
+		meta,
+		body
+	};
+}
+function extractFirstHeading(body) {
+	for (const line of body.split("\n")) {
+		const h = /^#\s+(.+)$/.exec(line);
+		if (h) return h[1];
+	}
+	return null;
+}
+function loadPatternRegistry(startDir = process.cwd()) {
+	const root = findPatternsDir(startDir);
+	if (!root) return {
+		root: null,
+		patterns: []
+	};
+	const patterns = [];
+	const entries = readdirSync(root).sort();
+	for (const entry of entries) {
+		if (!entry.endsWith(".md")) continue;
+		if (entry.startsWith(".") || entry === "README.md" || entry === "index.md") continue;
+		const filePath = join(root, entry);
+		let source;
+		try {
+			source = readFileSync(filePath, "utf8");
+		} catch {
+			continue;
+		}
+		const { meta, body } = parseFrontmatter(source);
+		const name = entry.replace(/\.md$/, "");
+		const title = meta.title ?? extractFirstHeading(body) ?? name;
+		patterns.push({
+			name,
+			path: filePath,
+			body: source,
+			title,
+			summary: meta.summary ?? null,
+			seeAlso: meta.seeAlso ?? []
+		});
+	}
+	return {
+		root,
+		patterns
+	};
+}
+/**
+* Format the registry as a short index listing for the "no arg" case.
+* Each entry: `  - slug — title (summary)`.
+*/
+function formatPatternIndex(registry) {
+	if (!registry.root || registry.patterns.length === 0) return "No patterns found. Patterns live at `docs/docs/patterns/<name>.md` (the VitePress content directory) in the Pyreon monorepo. If you are running the MCP in a consumer project, patterns are not available locally — run the MCP in the Pyreon repo to browse them.";
+	const parts = [`# Pyreon Patterns (${registry.patterns.length})`, ""];
+	parts.push("Call `get_pattern({ name: \"<slug>\" })` for the full body. Each pattern shows the canonical \"do it this way\" with code + rationale, plus the anti-pattern to avoid.");
+	parts.push("");
+	for (const p of registry.patterns) {
+		const summary = p.summary ? ` — ${p.summary}` : "";
+		parts.push(`- **${p.name}** — ${p.title}${summary}`);
+	}
+	return parts.join("\n");
+}
+/**
+* Format a single pattern's full body for the MCP response. Prepends
+* a breadcrumb and appends a cross-reference footer if `seeAlso` was
+* populated.
+*/
+function formatPatternBody(pattern) {
+	const parts = [pattern.body.trimEnd()];
+	if (pattern.seeAlso.length > 0) {
+		parts.push("");
+		parts.push(`---\n\n**See also:** ${pattern.seeAlso.map((s) => `\`get_pattern({ name: "${s}" })\``).join(", ")}`);
+	}
+	return parts.join("\n");
+}
+function findPattern(registry, name) {
+	for (const p of registry.patterns) if (p.name === name) return p;
+	return null;
+}
+function suggestPatterns(registry, name) {
+	const needle = name.toLowerCase();
+	const matches = [];
+	for (const p of registry.patterns) if (p.name.toLowerCase().includes(needle) || p.title.toLowerCase().includes(needle)) matches.push(p.name);
+	return matches.slice(0, 5);
+}
+
 //#endregion
 //#region src/index.ts
 /**
@@ -14821,204 +15736,292 @@ const tree = helper.getDocNode()`,
 *   get_routes                — List all routes in the current project
 *   get_components            — List all components with their props and signals
 *   get_browser_smoke_status  — Report which browser-categorized packages have smoke coverage
+*   get_pattern               — Fetch a "how do I do X" pattern body from docs/patterns/
+*   get_anti_patterns         — Browse the anti-patterns catalog, optionally filtered by category
+*   get_changelog             — Recent release notes for a @pyreon/* package, parsed from CHANGELOG.md
+*   audit_test_environment    — Scan test files for mock-vnode patterns (PR #197 bug class)
 *
 * Usage:
 *   bunx @pyreon/mcp          # stdio transport (for IDE integration)
 */
-const server = new McpServer({
-	name: "pyreon",
-	version
-});
-let cachedContext = null;
-let contextCwd = process.cwd();
-function getContext() {
-	if (!cachedContext || contextCwd !== process.cwd()) {
-		contextCwd = process.cwd();
-		cachedContext = generateContext(contextCwd);
-	}
-	return cachedContext;
-}
 function textResult(text) {
 	return { content: [{
 		type: "text",
 		text
 	}] };
 }
-server.tool("get_api", {
-	package: z.string(),
-	symbol: z.string()
-}, async ({ package: pkg, symbol }) => {
-	const entry = API_REFERENCE[`${pkg}/${symbol}`];
-	if (!entry) {
-		const suggestions = Object.keys(API_REFERENCE).filter((k) => k.toLowerCase().includes(symbol.toLowerCase())).slice(0, 5);
-		return textResult(`Symbol '${symbol}' not found in @pyreon/${pkg}.\n\n${suggestions.length > 0 ? `Did you mean one of these?\n${suggestions.map((s) => `  - ${s}`).join("\n")}` : "No similar symbols found."}`);
-	}
-	return textResult(`## @pyreon/${pkg} — ${symbol}\n\n**Signature:**\n\`\`\`typescript\n${entry.signature}\n\`\`\`\n\n**Usage:**\n\`\`\`typescript\n${entry.example}\n\`\`\`\n\n${entry.notes ? `**Notes:** ${entry.notes}\n\n` : ""}${entry.mistakes ? `**Common mistakes:**\n${entry.mistakes}\n` : ""}`);
-});
-server.tool("validate", {
-	code: z.string(),
-	filename: z.string().optional()
-}, async ({ code, filename }) => {
-	const diagnostics = detectReactPatterns(code, filename ?? "snippet.tsx");
-	if (diagnostics.length === 0) return textResult("✓ No issues found. The code follows Pyreon patterns correctly.");
-	const issueText = diagnostics.map((d, i) => `${i + 1}. **${d.code}** (line ${d.line})\n   ${d.message}\n   Current: \`${d.current}\`\n   Fix: \`${d.suggested}\`\n   Auto-fixable: ${d.fixable ? "yes" : "no"}`).join("\n\n");
-	return textResult(`Found ${diagnostics.length} issue${diagnostics.length === 1 ? "" : "s"}:\n\n${issueText}`);
-});
-server.tool("migrate_react", {
-	code: z.string(),
-	filename: z.string().optional()
-}, async ({ code, filename }) => {
-	const result = migrateReactCode(code, filename ?? "component.tsx");
-	const changeList = result.changes.map((c) => `- Line ${c.line}: ${c.description}`).join("\n");
-	const remainingIssues = result.diagnostics.filter((d) => !d.fixable);
-	const manualText = remainingIssues.length > 0 ? `\n\n**Remaining issues (manual fix needed):**\n${remainingIssues.map((d) => `- Line ${d.line}: ${d.message}\n  Suggested: \`${d.suggested}\``).join("\n")}` : "";
-	return textResult(`## Migrated Code\n\n\`\`\`tsx\n${result.code}\n\`\`\`\n\n**Changes applied (${result.changes.length}):**\n${changeList || "No changes needed."}${manualText}`);
-});
-server.tool("diagnose", { error: z.string() }, async ({ error }) => {
-	const diagnosis = diagnoseError(error);
-	if (!diagnosis) return textResult(`Could not identify a Pyreon-specific pattern in this error.\n\nError: ${error}\n\nSuggestions:\n- Check for typos in variable/function names\n- Verify all imports are correct\n- Run \`bun run typecheck\` for full TypeScript diagnostics\n- Run \`pyreon doctor\` for project-wide health check`);
-	let text = `**Cause:** ${diagnosis.cause}\n\n**Fix:** ${diagnosis.fix}`;
-	if (diagnosis.fixCode) text += `\n\n**Code:**\n\`\`\`typescript\n${diagnosis.fixCode}\n\`\`\``;
-	if (diagnosis.related) text += `\n\n**Related:** ${diagnosis.related}`;
-	return textResult(text);
-});
-server.tool("get_routes", {}, async () => {
-	const ctx = getContext();
-	if (ctx.routes.length === 0) return textResult("No routes detected. Routes are defined via createRouter() or a routes array.");
-	const routeTable = ctx.routes.map((r) => {
-		const flags = [
-			r.hasLoader ? "loader" : "",
-			r.hasGuard ? "guard" : "",
-			r.params.length > 0 ? `params: ${r.params.join(", ")}` : "",
-			r.name ? `name: "${r.name}"` : ""
-		].filter(Boolean).join(", ");
-		return `  ${r.path}${flags ? ` (${flags})` : ""}`;
-	}).join("\n");
-	return textResult(`**Routes (${ctx.routes.length}):**\n\n${routeTable}`);
-});
-server.tool("get_components", {}, async () => {
-	const ctx = getContext();
-	if (ctx.components.length === 0) return textResult("No components detected.");
-	const compList = ctx.components.map((c) => {
-		const details = [c.props.length > 0 ? `props: { ${c.props.join(", ")} }` : "", c.hasSignals ? `signals: [${c.signalNames.join(", ")}]` : ""].filter(Boolean).join(", ");
-		return `  ${c.name} — ${c.file}${details ? `\n    ${details}` : ""}`;
-	}).join("\n");
-	return textResult(`**Components (${ctx.components.length}):**\n\n${compList}`);
-});
-server.tool("get_browser_smoke_status", {}, async () => {
-	const fs = await import("node:fs");
-	const path = await import("node:path");
-	const cwd = process.cwd();
-	let browserPackages = [];
-	{
-		let dir = cwd;
-		for (let i = 0; i < 30; i++) {
-			const candidate = path.join(dir, ".claude", "rules", "browser-packages.json");
-			if (fs.existsSync(candidate)) {
-				try {
-					const parsed = JSON.parse(fs.readFileSync(candidate, "utf8"));
-					if (Array.isArray(parsed.packages)) browserPackages = parsed.packages.filter((p) => typeof p === "string");
-				} catch {}
-				break;
+function createServer() {
+	const server = new McpServer({
+		name: "pyreon",
+		version
+	});
+	let cachedContext = null;
+	let contextCwd = process.cwd();
+	function getContext() {
+		if (!cachedContext || contextCwd !== process.cwd()) {
+			contextCwd = process.cwd();
+			cachedContext = generateContext(contextCwd);
+		}
+		return cachedContext;
+	}
+	server.tool("get_api", {
+		package: z.string(),
+		symbol: z.string()
+	}, async ({ package: pkg, symbol }) => {
+		const entry = API_REFERENCE[`${pkg}/${symbol}`];
+		if (!entry) {
+			const suggestions = Object.keys(API_REFERENCE).filter((k) => k.toLowerCase().includes(symbol.toLowerCase())).slice(0, 5);
+			return textResult(`Symbol '${symbol}' not found in @pyreon/${pkg}.\n\n${suggestions.length > 0 ? `Did you mean one of these?\n${suggestions.map((s) => `  - ${s}`).join("\n")}` : "No similar symbols found."}`);
+		}
+		return textResult(`## @pyreon/${pkg} — ${symbol}\n\n**Signature:**\n\`\`\`typescript\n${entry.signature}\n\`\`\`\n\n**Usage:**\n\`\`\`typescript\n${entry.example}\n\`\`\`\n\n${entry.notes ? `**Notes:** ${entry.notes}\n\n` : ""}${entry.mistakes ? `**Common mistakes:**\n${entry.mistakes}\n` : ""}`);
+	});
+	server.tool("validate", {
+		code: z.string(),
+		filename: z.string().optional()
+	}, async ({ code, filename }) => {
+		const fname = filename ?? "snippet.tsx";
+		const reactDiags = detectReactPatterns(code, fname);
+		const pyreonDiags = detectPyreonPatterns(code, fname);
+		if (reactDiags.length === 0 && pyreonDiags.length === 0) return textResult("✓ No issues found. The code follows Pyreon patterns correctly.");
+		const merged = [...reactDiags, ...pyreonDiags];
+		merged.sort((a, b) => a.line - b.line || a.column - b.column);
+		const issueText = merged.map((d, i) => `${i + 1}. **${d.code}** (line ${d.line})\n   ${d.message}\n   Current: \`${d.current}\`\n   Fix: \`${d.suggested}\`\n   Auto-fixable: ${d.fixable ? "yes" : "no"}`).join("\n\n");
+		return textResult(`Found ${merged.length} issue${merged.length === 1 ? "" : "s"}:\n\n${issueText}`);
+	});
+	server.tool("migrate_react", {
+		code: z.string(),
+		filename: z.string().optional()
+	}, async ({ code, filename }) => {
+		const result = migrateReactCode(code, filename ?? "component.tsx");
+		const changeList = result.changes.map((c) => `- Line ${c.line}: ${c.description}`).join("\n");
+		const remainingIssues = result.diagnostics.filter((d) => !d.fixable);
+		const manualText = remainingIssues.length > 0 ? `\n\n**Remaining issues (manual fix needed):**\n${remainingIssues.map((d) => `- Line ${d.line}: ${d.message}\n  Suggested: \`${d.suggested}\``).join("\n")}` : "";
+		return textResult(`## Migrated Code\n\n\`\`\`tsx\n${result.code}\n\`\`\`\n\n**Changes applied (${result.changes.length}):**\n${changeList || "No changes needed."}${manualText}`);
+	});
+	server.tool("diagnose", { error: z.string() }, async ({ error }) => {
+		const diagnosis = diagnoseError(error);
+		if (!diagnosis) return textResult(`Could not identify a Pyreon-specific pattern in this error.\n\nError: ${error}\n\nSuggestions:\n- Check for typos in variable/function names\n- Verify all imports are correct\n- Run \`bun run typecheck\` for full TypeScript diagnostics\n- Run \`pyreon doctor\` for project-wide health check`);
+		let text = `**Cause:** ${diagnosis.cause}\n\n**Fix:** ${diagnosis.fix}`;
+		if (diagnosis.fixCode) text += `\n\n**Code:**\n\`\`\`typescript\n${diagnosis.fixCode}\n\`\`\``;
+		if (diagnosis.related) text += `\n\n**Related:** ${diagnosis.related}`;
+		return textResult(text);
+	});
+	server.tool("get_routes", {}, async () => {
+		const ctx = getContext();
+		if (ctx.routes.length === 0) return textResult("No routes detected. Routes are defined via createRouter() or a routes array.");
+		const routeTable = ctx.routes.map((r) => {
+			const flags = [
+				r.hasLoader ? "loader" : "",
+				r.hasGuard ? "guard" : "",
+				r.params.length > 0 ? `params: ${r.params.join(", ")}` : "",
+				r.name ? `name: "${r.name}"` : ""
+			].filter(Boolean).join(", ");
+			return `  ${r.path}${flags ? ` (${flags})` : ""}`;
+		}).join("\n");
+		return textResult(`**Routes (${ctx.routes.length}):**\n\n${routeTable}`);
+	});
+	server.tool("get_components", {}, async () => {
+		const ctx = getContext();
+		if (ctx.components.length === 0) return textResult("No components detected.");
+		const compList = ctx.components.map((c) => {
+			const details = [c.props.length > 0 ? `props: { ${c.props.join(", ")} }` : "", c.hasSignals ? `signals: [${c.signalNames.join(", ")}]` : ""].filter(Boolean).join(", ");
+			return `  ${c.name} — ${c.file}${details ? `\n    ${details}` : ""}`;
+		}).join("\n");
+		return textResult(`**Components (${ctx.components.length}):**\n\n${compList}`);
+	});
+	server.tool("get_browser_smoke_status", {}, async () => {
+		const fs = await import("node:fs");
+		const path = await import("node:path");
+		const cwd = process.cwd();
+		let browserPackages = [];
+		{
+			let dir = cwd;
+			for (let i = 0; i < 30; i++) {
+				const candidate = path.join(dir, ".claude", "rules", "browser-packages.json");
+				if (fs.existsSync(candidate)) {
+					try {
+						const parsed = JSON.parse(fs.readFileSync(candidate, "utf8"));
+						if (Array.isArray(parsed.packages)) browserPackages = parsed.packages.filter((p) => typeof p === "string");
+					} catch {}
+					break;
+				}
+				const parent = path.dirname(dir);
+				if (parent === dir) break;
+				dir = parent;
 			}
-			const parent = path.dirname(dir);
-			if (parent === dir) break;
-			dir = parent;
-		}
-	}
-	if (browserPackages.length === 0) return textResult("No `.claude/rules/browser-packages.json` found in the current project. This tool reports browser-smoke coverage for Pyreon monorepos that ship the single-source-of-truth list. Consumer apps can still opt in via the lint rule's `additionalPackages` option.");
-	function hasBrowserTest(dir) {
-		let entries;
-		try {
-			entries = fs.readdirSync(dir);
-		} catch {
-			return false;
 		}
-		for (const name of entries) {
-			if (name.startsWith(".") || name === "node_modules" || name === "lib" || name === "dist") continue;
-			const full = path.join(dir, name);
-			let isDir = false;
+		if (browserPackages.length === 0) return textResult("No `.claude/rules/browser-packages.json` found in the current project. This tool reports browser-smoke coverage for Pyreon monorepos that ship the single-source-of-truth list. Consumer apps can still opt in via the lint rule's `additionalPackages` option.");
+		function hasBrowserTest(dir) {
+			let entries;
 			try {
-				isDir = fs.statSync(full).isDirectory();
+				entries = fs.readdirSync(dir);
 			} catch {
-				continue;
+				return false;
 			}
-			if (isDir) {
-				if (hasBrowserTest(full)) return true;
-				continue;
+			for (const name of entries) {
+				if (name.startsWith(".") || name === "node_modules" || name === "lib" || name === "dist") continue;
+				const full = path.join(dir, name);
+				let isDir = false;
+				try {
+					isDir = fs.statSync(full).isDirectory();
+				} catch {
+					continue;
+				}
+				if (isDir) {
+					if (hasBrowserTest(full)) return true;
+					continue;
+				}
+				if (/\.browser\.test\.(?:ts|tsx)$/.test(name)) return true;
 			}
-			if (/\.browser\.test\.(?:ts|tsx)$/.test(name)) return true;
-		}
-		return false;
-	}
-	const pkgDirs = /* @__PURE__ */ new Map();
-	function walkPkgs(dir, depth = 0) {
-		if (depth > 4) return;
-		let entries;
-		try {
-			entries = fs.readdirSync(dir);
-		} catch {
-			return;
+			return false;
 		}
-		for (const name of entries) {
-			if (name.startsWith(".") || name === "node_modules") continue;
-			const full = path.join(dir, name);
-			let isDir = false;
+		const pkgDirs = /* @__PURE__ */ new Map();
+		function walkPkgs(dir, depth = 0) {
+			if (depth > 4) return;
+			let entries;
 			try {
-				isDir = fs.statSync(full).isDirectory();
+				entries = fs.readdirSync(dir);
 			} catch {
-				continue;
+				return;
+			}
+			for (const name of entries) {
+				if (name.startsWith(".") || name === "node_modules") continue;
+				const full = path.join(dir, name);
+				let isDir = false;
+				try {
+					isDir = fs.statSync(full).isDirectory();
+				} catch {
+					continue;
+				}
+				if (!isDir) continue;
+				const pkgJsonPath = path.join(full, "package.json");
+				if (fs.existsSync(pkgJsonPath)) try {
+					const parsed = JSON.parse(fs.readFileSync(pkgJsonPath, "utf8"));
+					if (typeof parsed.name === "string") pkgDirs.set(parsed.name, full);
+				} catch {}
+				else walkPkgs(full, depth + 1);
 			}
-			if (!isDir) continue;
-			const pkgJsonPath = path.join(full, "package.json");
-			if (fs.existsSync(pkgJsonPath)) try {
-				const parsed = JSON.parse(fs.readFileSync(pkgJsonPath, "utf8"));
-				if (typeof parsed.name === "string") pkgDirs.set(parsed.name, full);
-			} catch {}
-			else walkPkgs(full, depth + 1);
 		}
-	}
-	walkPkgs(path.join(cwd, "packages"));
-	const covered = [];
-	const missing = [];
-	const unknown = [];
-	for (const name of browserPackages) {
-		const dir = pkgDirs.get(name);
-		if (!dir) {
-			unknown.push(name);
-			continue;
+		walkPkgs(path.join(cwd, "packages"));
+		const covered = [];
+		const missing = [];
+		const unknown = [];
+		for (const name of browserPackages) {
+			const dir = pkgDirs.get(name);
+			if (!dir) {
+				unknown.push(name);
+				continue;
+			}
+			if (hasBrowserTest(dir)) covered.push(name);
+			else missing.push(name);
 		}
-		if (hasBrowserTest(dir)) covered.push(name);
-		else missing.push(name);
-	}
-	const parts = [];
-	parts.push(`**Browser smoke coverage** (${covered.length} / ${browserPackages.length}):`);
-	parts.push("");
-	if (covered.length > 0) {
-		parts.push(`✓ Covered (${covered.length}):`);
-		for (const n of covered) parts.push(`  - ${n}`);
+		const parts = [];
+		parts.push(`**Browser smoke coverage** (${covered.length} / ${browserPackages.length}):`);
 		parts.push("");
+		if (covered.length > 0) {
+			parts.push(`✓ Covered (${covered.length}):`);
+			for (const n of covered) parts.push(`  - ${n}`);
+			parts.push("");
+		}
+		if (missing.length > 0) {
+			parts.push(`✗ Missing \`*.browser.test.*\` (${missing.length}):`);
+			for (const n of missing) parts.push(`  - ${n}`);
+			parts.push("");
+			parts.push("Add a `*.browser.test.{ts,tsx}` file under `src/` in each missing package. See `.claude/rules/test-environment-parity.md` for the setup recipe.");
+		}
+		if (unknown.length > 0) {
+			parts.push(`? Listed in browser-packages.json but not found in this repo (${unknown.length}):`);
+			for (const n of unknown) parts.push(`  - ${n}`);
+		}
+		return textResult(parts.join("\n"));
+	});
+	server.tool("get_pattern", { name: z.string().optional().describe("Pattern slug (e.g. \"dev-warnings\", \"controllable-state\"). Omit to list available patterns.") }, async ({ name }) => {
+		const registry = loadPatternRegistry();
+		if (!name) return textResult(formatPatternIndex(registry));
+		const pattern = findPattern(registry, name);
+		if (pattern) return textResult(formatPatternBody(pattern));
+		const suggestions = suggestPatterns(registry, name);
+		return textResult(`Pattern "${name}" not found.\n\n${suggestions.length > 0 ? `Did you mean one of these?\n${suggestions.map((s) => `  - ${s}`).join("\n")}\n\nOr call get_pattern() with no arg to see the full list.` : "Call get_pattern() with no arg to see available patterns."}`);
+	});
+	server.tool("get_anti_patterns", { category: z.enum([
+		"reactivity",
+		"jsx",
+		"context",
+		"architecture",
+		"testing",
+		"lifecycle",
+		"documentation",
+		"all"
+	]).optional().describe(`Category filter: ${ANTI_PATTERN_CATEGORIES.join(", ")}, or "all" (default).`) }, async ({ category = "all" }) => {
+		const cat = category;
+		const doc = loadAntiPatternsDoc();
+		if (!doc) return textResult("Could not locate `.claude/rules/anti-patterns.md`. This tool reads the file from the Pyreon monorepo — running in a consumer project without the rules directory surfaces this miss. File issues against pyreon/pyreon if the file exists but is not being found.");
+		const all = parseAntiPatterns(doc);
+		return textResult(formatAntiPatterns(cat === "all" ? all : all.filter((e) => e.category === cat), cat));
+	});
+	server.tool("get_changelog", {
+		package: z.string().optional().describe("Package name, e.g. \"query\" or \"@pyreon/query\". Omit to list every package with a CHANGELOG."),
+		limit: z.number().int().positive().optional().describe("Maximum number of substantive versions to return. Default 5."),
+		includeDependencyUpdates: z.boolean().optional().describe("Include `Updated dependencies` bullets. Default false (usually noise)."),
+		since: z.string().optional().describe("Only include versions strictly newer than this one (e.g. \"0.12.0\"). Useful when an agent knows the version it was trained against and wants just the delta.")
+	}, async ({ package: pkg, limit, includeDependencyUpdates, since }) => {
+		const registry = loadChangelogRegistry();
+		if (!pkg) return textResult(formatChangelogIndex(registry));
+		const changelog = findChangelog(registry, pkg);
+		if (changelog) return textResult(formatChangelog(changelog, {
+			limit,
+			includeDependencyUpdates,
+			since
+		}));
+		const suggestions = suggestChangelogs(registry, pkg);
+		return textResult(`Changelog for "${pkg}" not found.\n\n${suggestions.length > 0 ? `Did you mean one of these?\n${suggestions.map((s) => `  - ${s}`).join("\n")}\n\nOr call get_changelog() with no arg for the full list.` : "Call get_changelog() with no arg for the list of packages that ship a CHANGELOG."}`);
+	});
+	server.tool("audit_test_environment", {
+		minRisk: z.enum([
+			"high",
+			"medium",
+			"low"
+		]).optional().describe("Minimum risk level to surface. Default \"medium\" — HIGH + MEDIUM files. Use \"high\" for only the riskiest, \"low\" to see everything."),
+		limit: z.number().int().positive().optional().describe("Maximum entries to show per risk group. Default 20.")
+	}, async ({ minRisk, limit }) => {
+		return textResult(formatTestAudit(auditTestEnvironment(process.cwd()), {
+			minRisk,
+			limit
+		}));
+	});
+	return server;
+}
+/**
+* Locate `.claude/rules/anti-patterns.md` by walking up from cwd.
+* Returns the file contents or null if not found within 30 levels.
+* Separate from the patterns loader because the doc path is fixed
+* (`.claude/rules/`) — no glob needed.
+*/
+function loadAntiPatternsDoc(startDir = process.cwd()) {
+	let dir = resolve(startDir);
+	for (let i = 0; i < 30; i++) {
+		const candidate = join(dir, ".claude", "rules", "anti-patterns.md");
+		if (existsSync(candidate)) try {
+			return readFileSync(candidate, "utf8");
+		} catch {
+			return null;
+		}
+		const parent = dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
 	}
-	if (missing.length > 0) {
-		parts.push(`✗ Missing \`*.browser.test.*\` (${missing.length}):`);
-		for (const n of missing) parts.push(`  - ${n}`);
-		parts.push("");
-		parts.push("Add a `*.browser.test.{ts,tsx}` file under `src/` in each missing package. See `.claude/rules/test-environment-parity.md` for the setup recipe.");
-	}
-	if (unknown.length > 0) {
-		parts.push(`? Listed in browser-packages.json but not found in this repo (${unknown.length}):`);
-		for (const n of unknown) parts.push(`  - ${n}`);
-	}
-	return textResult(parts.join("\n"));
-});
+	return null;
+}
 async function main() {
+	const server = createServer();
 	const transport = new StdioServerTransport();
 	await server.connect(transport);
 }
-main().catch((err) => {
+if (import.meta.main) main().catch((err) => {
 	console.error("MCP server error:", err);
 	process.exit(1);
 });
 
 //#endregion
+export { createServer };
 //# sourceMappingURL=index.js.map