@happyvertical/smrt-dev-mcp 0.40.62 → 0.40.64

package/dist/{knowledge-DUUhTM5u.js → knowledge-A7-gIjW4.js}

@@ -4,6 +4,680 @@ import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { MODULE_DOC_HASH_PREFIX, readAgentModuleDocs } from "@happyvertical/smrt-core/knowledge";
 import { ManifestAdapter, OxcScanner } from "@happyvertical/smrt-scanner";
+//#region src/tool-catalog.ts
+var REVIEW_SKILL_NAME = "smrt-code-review";
+var JSON_SCHEMA_2020_12 = "https://json-schema.org/draft/2020-12/schema";
+function compareToolNames(left, right) {
+	return left < right ? -1 : left > right ? 1 : 0;
+}
+/**
+* Stable success/error envelope for development tools. `data` preserves each
+* tool's existing payload exactly; coverage/diagnostics are promoted only when
+* the underlying result actually reports them.
+*/
+var DEV_MCP_OUTPUT_SCHEMA = {
+	$schema: JSON_SCHEMA_2020_12,
+	type: "object",
+	additionalProperties: false,
+	required: [
+		"ok",
+		"coverage",
+		"diagnostics",
+		"data"
+	],
+	properties: {
+		ok: { type: "boolean" },
+		coverage: {
+			type: ["object", "null"],
+			additionalProperties: true
+		},
+		diagnostics: {
+			type: "array",
+			items: {
+				type: "object",
+				additionalProperties: true
+			}
+		},
+		data: {}
+	}
+};
+var TOOLS = [
+	{
+		name: "generate-smrt-class",
+		description: "Generate a complete SMRT class with @smrt() decorator",
+		inputSchema: {
+			type: "object",
+			properties: {
+				className: {
+					type: "string",
+					description: "Name of the class (PascalCase)"
+				},
+				properties: {
+					type: "array",
+					description: "Array of property definitions",
+					items: {
+						type: "object",
+						properties: {
+							name: { type: "string" },
+							type: {
+								type: "string",
+								enum: [
+									"text",
+									"integer",
+									"decimal",
+									"boolean",
+									"datetime",
+									"json"
+								]
+							},
+							required: { type: "boolean" },
+							nullable: { type: "boolean" },
+							description: { type: "string" },
+							defaultValue: { oneOf: [
+								{ type: "string" },
+								{ type: "number" },
+								{ type: "boolean" },
+								{ type: "object" },
+								{ type: "null" }
+							] }
+						},
+						required: ["name", "type"]
+					}
+				},
+				baseClass: {
+					type: "string",
+					enum: ["SmrtObject", "SmrtCollection"],
+					default: "SmrtObject"
+				},
+				template: {
+					type: "string",
+					enum: [
+						"basic",
+						"global-catalog",
+						"optional-catalog",
+						"tenant-project-object",
+						"tenant-event-log-object",
+						"cross-package-reference"
+					],
+					default: "basic"
+				},
+				tableName: { type: "string" },
+				conflictColumns: {
+					type: "array",
+					items: { type: "string" }
+				},
+				tenantScoped: { oneOf: [{ type: "boolean" }, {
+					type: "object",
+					properties: {
+						mode: {
+							type: "string",
+							enum: ["required", "optional"]
+						},
+						field: { type: "string" },
+						autoFilter: { type: "boolean" },
+						autoPopulate: { type: "boolean" },
+						allowSuperAdminBypass: { type: "boolean" }
+					}
+				}] },
+				includeTenantIdField: { type: "boolean" },
+				relationships: {
+					type: "array",
+					items: {
+						type: "object",
+						properties: {
+							name: { type: "string" },
+							type: {
+								type: "string",
+								enum: [
+									"foreignKey",
+									"crossPackageRef",
+									"oneToMany",
+									"manyToMany"
+								]
+							},
+							related: { type: "string" },
+							required: { type: "boolean" },
+							nullable: { type: "boolean" },
+							description: { type: "string" },
+							validate: { type: "boolean" },
+							foreignKey: { type: "string" },
+							through: { type: "string" },
+							sourceKey: { type: "string" },
+							targetKey: { type: "string" }
+						},
+						required: [
+							"name",
+							"type",
+							"related"
+						]
+					}
+				},
+				includeCompanionSnippets: {
+					type: "boolean",
+					default: false
+				},
+				includeApiConfig: {
+					type: "boolean",
+					default: true
+				},
+				includeMcpConfig: {
+					type: "boolean",
+					default: true
+				},
+				includeCliConfig: {
+					type: "boolean",
+					default: true
+				}
+			},
+			required: ["className", "properties"]
+		}
+	},
+	{
+		name: "introspect-project",
+		description: "Scan a directory for SMRT objects. Returns a compact summary by default; pass detail: \"full\" for field, schema, and method details.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				directory: {
+					type: "string",
+					description: "Project directory (default: cwd)"
+				},
+				manifestPath: {
+					type: "string",
+					description: "Optional manifest path. Defaults to .smrt/manifest.json, dist/manifest.json, then source scanning."
+				},
+				detail: {
+					type: "string",
+					enum: ["summary", "full"],
+					default: "summary",
+					description: "summary: one compact record per object. full: complete field/schema/method detail (large)."
+				},
+				maxChars: {
+					type: "number",
+					description: "Character budget for the `objects` payload. Objects past the budget are omitted and reported under `truncated`. Project metadata and diagnostics are always returned in full, so the serialized response is somewhat larger than this budget."
+				},
+				includeFields: {
+					type: "boolean",
+					description: "Include field details (detail: \"full\" only)"
+				},
+				includeRelationships: {
+					type: "boolean",
+					description: "Analyze relationships (detail: \"full\" only)"
+				},
+				includeMethods: {
+					type: "boolean",
+					description: "Include public method details (detail: \"full\" only)"
+				}
+			}
+		}
+	},
+	{
+		name: "review-smrt-project",
+		description: "Advisory ecosystem alignment review for downstream SMRT projects",
+		inputSchema: {
+			type: "object",
+			properties: {
+				directory: {
+					type: "string",
+					description: "Project directory (default: cwd)"
+				},
+				rootDir: {
+					type: "string",
+					description: "Compatibility alias for directory"
+				},
+				includeSourceEvidence: {
+					type: "boolean",
+					description: "Include file and line evidence in findings",
+					default: true
+				},
+				maxFindings: {
+					type: "number",
+					description: "Optional maximum number of findings to return"
+				}
+			}
+		}
+	},
+	{
+		name: "reflect-knowledge",
+		description: "Report deterministic SMRT + HappyVertical SDK knowledge coverage and freshness",
+		inputSchema: {
+			type: "object",
+			properties: { rootDir: {
+				type: "string",
+				description: "Project root directory (default: cwd)"
+			} }
+		}
+	},
+	{
+		name: "reflect-domain-knowledge",
+		description: "Report domain-scoped SMRT knowledge artifacts, SDK packages, and freshness",
+		inputSchema: {
+			type: "object",
+			properties: {
+				rootDir: { type: "string" },
+				scope: {
+					type: "string",
+					enum: [
+						"project",
+						"local",
+						"package",
+						"sdk",
+						"installed"
+					],
+					default: "project"
+				},
+				package: { type: "string" }
+			}
+		}
+	},
+	{
+		name: "check-knowledge-freshness",
+		description: "Run deterministic freshness checks for SMRT agent knowledge",
+		inputSchema: {
+			type: "object",
+			properties: {
+				rootDir: { type: "string" },
+				changed: {
+					type: "boolean",
+					description: "Limit stale-pattern checks to changed files"
+				},
+				strict: {
+					type: "boolean",
+					description: "Treat stale-pattern findings as errors"
+				}
+			}
+		}
+	},
+	{
+		name: "check-domain-knowledge",
+		description: "Run deterministic freshness checks for domain knowledge artifacts",
+		inputSchema: {
+			type: "object",
+			properties: {
+				rootDir: { type: "string" },
+				changed: { type: "boolean" },
+				strict: { type: "boolean" },
+				scope: {
+					type: "string",
+					enum: [
+						"project",
+						"local",
+						"package",
+						"sdk",
+						"installed"
+					],
+					default: "project"
+				},
+				package: { type: "string" }
+			}
+		}
+	},
+	{
+		name: "build-review-context",
+		description: "Build model-ready SMRT review context from changed files and optional focus text",
+		inputSchema: {
+			type: "object",
+			properties: {
+				rootDir: { type: "string" },
+				changedFiles: {
+					type: "array",
+					items: { type: "string" }
+				},
+				focus: { type: "string" },
+				documentation: { type: "string" },
+				detail: {
+					type: "string",
+					enum: ["summary", "full"],
+					default: "summary",
+					description: "summary: authored package docs are listed by path to stay inside tool-result budgets. full: embed them."
+				}
+			}
+		}
+	},
+	{
+		name: "build-domain-review-context",
+		description: "Build domain-scoped model-ready SMRT review context and prompt bundle",
+		inputSchema: {
+			type: "object",
+			properties: {
+				rootDir: { type: "string" },
+				changedFiles: {
+					type: "array",
+					items: { type: "string" }
+				},
+				focus: { type: "string" },
+				documentation: { type: "string" },
+				scope: {
+					type: "string",
+					enum: [
+						"project",
+						"local",
+						"package",
+						"sdk",
+						"installed"
+					],
+					default: "project"
+				},
+				package: { type: "string" },
+				detail: {
+					type: "string",
+					enum: ["summary", "full"],
+					default: "summary",
+					description: "summary: authored package docs are listed by path to stay inside tool-result budgets. full: embed them."
+				}
+			}
+		}
+	},
+	{
+		name: "smrt-review",
+		description: "Return deterministic review findings and/or a reusable model prompt bundle. For a formal downstream review, first call get-agent-skill with { \"name\": \"smrt-code-review\" } or load the smrt-code-review MCP prompt/resource.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				rootDir: { type: "string" },
+				changedFiles: {
+					type: "array",
+					items: { type: "string" }
+				},
+				focus: { type: "string" },
+				documentation: { type: "string" },
+				mode: {
+					type: "string",
+					enum: [
+						"findings",
+						"prompt-bundle",
+						"both"
+					],
+					default: "both"
+				},
+				detail: {
+					type: "string",
+					enum: ["summary", "full"],
+					default: "summary",
+					description: "summary: authored package docs are listed by path to stay inside tool-result budgets. full: embed them."
+				}
+			}
+		}
+	},
+	{
+		name: "build-architecture-context",
+		description: "Build model-ready SMRT architecture context from an idea or documentation",
+		inputSchema: {
+			type: "object",
+			properties: {
+				rootDir: { type: "string" },
+				idea: { type: "string" },
+				documentation: { type: "string" },
+				focus: { type: "string" },
+				detail: {
+					type: "string",
+					enum: ["summary", "full"],
+					default: "summary",
+					description: "summary: authored package docs are listed by path to stay inside tool-result budgets. full: embed them."
+				}
+			}
+		}
+	},
+	{
+		name: "build-domain-architecture-context",
+		description: "Build domain-scoped model-ready SMRT architecture context and prompt bundle",
+		inputSchema: {
+			type: "object",
+			properties: {
+				rootDir: { type: "string" },
+				idea: { type: "string" },
+				documentation: { type: "string" },
+				focus: { type: "string" },
+				scope: {
+					type: "string",
+					enum: [
+						"project",
+						"local",
+						"package",
+						"sdk",
+						"installed"
+					],
+					default: "project"
+				},
+				package: { type: "string" },
+				detail: {
+					type: "string",
+					enum: ["summary", "full"],
+					default: "summary",
+					description: "summary: authored package docs are listed by path to stay inside tool-result budgets. full: embed them."
+				}
+			}
+		}
+	},
+	{
+		name: "smrt-architecture",
+		description: "Suggest SMRT and HappyVertical SDK packages and return an architecture prompt bundle",
+		inputSchema: {
+			type: "object",
+			properties: {
+				rootDir: { type: "string" },
+				idea: { type: "string" },
+				documentation: { type: "string" },
+				focus: { type: "string" },
+				detail: {
+					type: "string",
+					enum: ["summary", "full"],
+					default: "summary",
+					description: "summary: authored package docs are listed by path to stay inside tool-result budgets. full: embed them."
+				}
+			}
+		}
+	},
+	{
+		name: "list-agent-skills",
+		description: "List bundled harness-agnostic agent skills shipped with smrt-dev-mcp",
+		inputSchema: {
+			type: "object",
+			properties: {}
+		}
+	},
+	{
+		name: "get-agent-skill",
+		description: "Return a bundled harness-agnostic agent skill as Markdown plus optional references",
+		inputSchema: {
+			type: "object",
+			properties: {
+				name: {
+					type: "string",
+					enum: [REVIEW_SKILL_NAME],
+					description: "Bundled agent skill name"
+				},
+				includeReferences: {
+					type: "boolean",
+					default: true,
+					description: "Include referenced files with the skill bundle"
+				}
+			},
+			required: ["name"]
+		}
+	}
+].map((tool) => ({
+	...tool,
+	inputSchema: {
+		...tool.inputSchema,
+		$schema: JSON_SCHEMA_2020_12
+	},
+	outputSchema: DEV_MCP_OUTPUT_SCHEMA
+})).sort((left, right) => compareToolNames(left.name, right.name));
+//#endregion
+//#region src/knowledge/mcp-docs.ts
+var PACKAGE_NAME = "@happyvertical/smrt-dev-mcp";
+/**
+* Compare the authored development-MCP catalog to the actual exported tools.
+* The parser intentionally checks only stable structural Markdown: tool names
+* plus top-level input-property names, types, enums, and requiredness.
+* Descriptive prose and prose-embedded defaults remain authored.
+*/
+function checkMcpToolDocumentation(rootDir, packageDir, tools) {
+	const readmePath = join(packageDir, "README.md");
+	const agentsPath = join(packageDir, "AGENTS.md");
+	const issues = [];
+	if (!existsSync(readmePath)) {
+		issues.push(issue(rootDir, readmePath, "mcp-readme-missing", "MCP package README.md is missing"));
+		return issues;
+	}
+	const expectedTools = [...tools].sort((left, right) => compareNames(left.name, right.name));
+	const { sections: readmeSections, names: documentedToolNames } = readToolSections(readFileSync(readmePath, "utf8"));
+	const expectedToolNames = expectedTools.map((tool) => tool.name);
+	const readmeCatalogDiff = setDifference(expectedToolNames, documentedToolNames);
+	if (readmeCatalogDiff) issues.push(issue(rootDir, readmePath, "mcp-readme-tool-drift", `README tool catalog differs from exported TOOLS (${readmeCatalogDiff})`));
+	for (const tool of expectedTools) {
+		const section = readmeSections.get(tool.name);
+		if (section === void 0) continue;
+		const { parameters: documentedParameters, names: documentedParameterNames } = readParameterTable(section);
+		const expectedProperties = Object.keys(tool.inputSchema.properties ?? {}).sort(compareNames);
+		const propertyDiff = setDifference(expectedProperties, documentedParameterNames);
+		const required = new Set(tool.inputSchema.required ?? []);
+		const requiredness = expectedProperties.filter((name) => documentedParameters.has(name) && documentedParameters.get(name)?.required !== required.has(name)).map((name) => `${name} expected ${required.has(name) ? "Yes" : "No"} but documented ${documentedParameters.get(name)?.required ? "Yes" : "No"}`);
+		const inputProperties = tool.inputSchema.properties ?? {};
+		const types = expectedProperties.filter((name) => documentedParameters.has(name)).flatMap((name) => {
+			const expected = formatSchemaType(inputProperties[name]);
+			const documented = documentedParameters.get(name)?.type;
+			return documented === expected ? [] : [`${name} expected ${expected} but documented ${documented}`];
+		});
+		const details = [
+			propertyDiff,
+			requiredness.length > 0 ? `requiredness: ${requiredness.join(", ")}` : void 0,
+			types.length > 0 ? `types: ${types.join(", ")}` : void 0
+		].filter((value) => Boolean(value));
+		if (details.length > 0) issues.push(issue(rootDir, readmePath, "mcp-readme-schema-drift", `README parameters for "${tool.name}" differ from its exported input schema (${details.join("; ")})`));
+	}
+	if (!existsSync(agentsPath)) return issues;
+	const agentsCatalogDiff = setDifference(expectedToolNames, readAgentToolNames(readFileSync(agentsPath, "utf8")).sort(compareNames));
+	if (agentsCatalogDiff) issues.push(issue(rootDir, agentsPath, "mcp-agents-tool-drift", `AGENTS.md tool catalog differs from exported TOOLS (${agentsCatalogDiff})`));
+	return issues;
+}
+function issue(rootDir, path, code, message) {
+	return {
+		severity: "error",
+		code,
+		message,
+		file: relative(rootDir, path),
+		packageName: PACKAGE_NAME
+	};
+}
+function readToolSections(markdown) {
+	const availableTools = sectionAfterHeading(markdown, "Available Tools");
+	if (!availableTools) return {
+		sections: /* @__PURE__ */ new Map(),
+		names: []
+	};
+	const headings = [...availableTools.matchAll(/^### `([^`]+)`\s*$/gm)];
+	return {
+		sections: new Map(headings.map((heading, index) => {
+			const start = (heading.index ?? 0) + heading[0].length;
+			const end = headings[index + 1]?.index ?? availableTools.length;
+			return [heading[1], availableTools.slice(start, end)];
+		})),
+		names: headings.map((heading) => heading[1])
+	};
+}
+function readParameterTable(section) {
+	const parameters = /* @__PURE__ */ new Map();
+	const names = [];
+	for (const line of section.split("\n")) {
+		if (!line.trimStart().startsWith("|")) continue;
+		const cells = splitMarkdownRow(line);
+		const name = /^`([^`]+)`$/.exec(cells[0]?.trim() ?? "")?.[1];
+		const required = cells[2]?.trim();
+		if (!name || required !== "Yes" && required !== "No") continue;
+		names.push(name);
+		parameters.set(name, {
+			name,
+			required: required === "Yes",
+			type: normalizeDocumentedType(cells[1] ?? "")
+		});
+	}
+	return {
+		parameters,
+		names
+	};
+}
+function normalizeDocumentedType(value) {
+	const trimmed = value.trim();
+	return (trimmed.startsWith("`") && trimmed.endsWith("`") ? trimmed.slice(1, -1) : trimmed).replaceAll("\\|", "|").replace(/\s*\|\s*/g, " | ").trim();
+}
+function formatSchemaType(value) {
+	if (!isRecord(value)) return "unknown";
+	if (Array.isArray(value.oneOf)) return unique(value.oneOf.map(formatSchemaType)).join(" | ");
+	if (Array.isArray(value.enum) && value.enum.length > 0) return value.enum.map(formatEnumValue).join(" | ");
+	if (value.type === "array") {
+		const itemType = formatSchemaType(value.items);
+		return itemType.includes(" | ") ? `(${itemType})[]` : `${itemType}[]`;
+	}
+	if (Array.isArray(value.type)) return unique(value.type.map(String)).join(" | ");
+	return typeof value.type === "string" ? value.type : "unknown";
+}
+function formatEnumValue(value) {
+	if (typeof value === "string") return `'${value.replaceAll("'", "\\'")}'`;
+	return String(value);
+}
+function isRecord(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function unique(values) {
+	return [...new Set(values)];
+}
+function splitMarkdownRow(row) {
+	const content = row.trim().replace(/^\|/, "").replace(/\|$/, "");
+	const cells = [];
+	let cell = "";
+	for (let index = 0; index < content.length; index += 1) {
+		const character = content[index];
+		if (character === "|" && content[index - 1] !== "\\") {
+			cells.push(cell);
+			cell = "";
+		} else cell += character;
+	}
+	cells.push(cell);
+	return cells;
+}
+function readAgentToolNames(markdown) {
+	const toolsSection = sectionAfterHeading(markdown, "Tools");
+	if (!toolsSection) return [];
+	return [...toolsSection.matchAll(/^\|\s*`([^`]+)`\s*\|/gm)].map((match) => match[1]);
+}
+function sectionAfterHeading(markdown, heading) {
+	const marker = new RegExp(`^## ${heading}\\s*$`, "m").exec(markdown);
+	if (!marker) return "";
+	const start = (marker.index ?? 0) + marker[0].length;
+	const remainder = markdown.slice(start);
+	const nextHeading = /^##\s+/m.exec(remainder);
+	return remainder.slice(0, nextHeading?.index ?? remainder.length);
+}
+function setDifference(expected, actual) {
+	const expectedSet = new Set(expected);
+	const actualSet = new Set(actual);
+	const missing = expected.filter((value) => !actualSet.has(value)).sort(compareNames);
+	const extra = unique(actual.filter((value) => !expectedSet.has(value))).sort(compareNames);
+	const expectedDuplicates = duplicateNames(expected);
+	const actualDuplicates = duplicateNames(actual);
+	const parts = [
+		missing.length > 0 ? `missing: ${missing.join(", ")}` : void 0,
+		extra.length > 0 ? `extra: ${extra.join(", ")}` : void 0,
+		expectedDuplicates.length > 0 ? `exported duplicates: ${expectedDuplicates.join(", ")}` : void 0,
+		actualDuplicates.length > 0 ? `duplicates: ${actualDuplicates.join(", ")}` : void 0
+	].filter((value) => Boolean(value));
+	return parts.length > 0 ? parts.join("; ") : void 0;
+}
+function duplicateNames(values) {
+	const seen = /* @__PURE__ */ new Set();
+	const duplicates = /* @__PURE__ */ new Set();
+	for (const value of values) {
+		if (seen.has(value)) duplicates.add(value);
+		seen.add(value);
+	}
+	return [...duplicates].sort(compareNames);
+}
+function compareNames(left, right) {
+	return left < right ? -1 : left > right ? 1 : 0;
+}
+//#endregion
 //#region src/knowledge/index.ts
 var SDK_PACKAGE_NAMES = /* @__PURE__ */ new Set([
 	"@happyvertical/ai",
@@ -117,7 +791,7 @@ async function buildKnowledgeIndex(options = {}) {
 		packages.push(readKnowledgePackage(rootDir, dir, includeDocs));
 	}
 	await applyScannerFallbacks(packages, packageDirs.filter((dir) => resolve(dir) !== resolve(rootDir)).map((dir) => `${relative(rootDir, dir).replaceAll("\\", "/")}/**`));
-	packages.push(...discoverInstalledSdkPackages(rootDir, packageDirs, includeDocs));
+	packages.push(...discoverInstalledPackages(rootDir, packageDirs, includeDocs));
 	const uniquePackages = dedupePackages(packages);
 	const scopedPackages = filterKnowledgePackages(uniquePackages, options);
 	const smrtPackages = scopedPackages.filter((pkg) => pkg.kind === "smrt");
@@ -130,24 +804,26 @@ async function buildKnowledgeIndex(options = {}) {
 		packages: uniquePackages
 	});
 	return {
-		schemaVersion: 2,
+		schemaVersion: 3,
 		generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
 		rootDir,
 		packages: scopedPackages,
 		smrtPackages,
 		sdkPackages,
+		installedPackages: scopedPackages.filter((pkg) => pkg.isInstalledDependency),
 		relationshipsV2: summarizeRelationshipsV2(scopedPackages),
 		coverage,
 		diagnostics: buildIndexDiagnostics(rootDir, uniquePackages, coverage, discoveryDiagnostics)
 	};
 }
 function buildCoverage(options) {
+	const authored = options.packages.filter((pkg) => !pkg.isInstalledDependency);
 	return {
 		workspaceGlobs: options.globs,
 		workspaceGlobSource: options.globSource,
 		packageDirs: options.packageDirs.map((dir) => relative(options.rootDir, dir) || "."),
-		packagesWithObjects: options.packages.filter((pkg) => pkg.objects.length > 0).map((pkg) => `${pkg.name} (${pkg.objects.length}, ${pkg.objectSource})`),
-		packagesWithoutObjects: options.packages.filter((pkg) => pkg.objects.length === 0).map((pkg) => ({
+		packagesWithObjects: authored.filter((pkg) => pkg.objects.length > 0).map((pkg) => `${pkg.name} (${pkg.objects.length}, ${pkg.objectSource})`),
+		packagesWithoutObjects: authored.filter((pkg) => pkg.objects.length === 0).map((pkg) => ({
 			name: pkg.name,
 			reason: pkg.objectSourceReason ?? pkg.objectSource,
 			checkedPaths: pkg.checkedObjectPaths,
@@ -171,7 +847,25 @@ function remedyForReason(pkg) {
 */
 function buildIndexDiagnostics(rootDir, packages, coverage, discoveryDiagnostics = []) {
 	const diagnostics = [...discoveryDiagnostics];
-	if (packages.reduce((total, pkg) => total + pkg.objects.length, 0) === 0) diagnostics.push({
+	const authoredPackages = packages.filter((pkg) => !pkg.isInstalledDependency);
+	const authoredObjects = authoredPackages.reduce((total, pkg) => total + pkg.objects.length, 0);
+	const installedObjects = packages.reduce((total, pkg) => total + (pkg.isInstalledDependency ? pkg.objects.length : 0), 0);
+	if (authoredObjects === 0 && installedObjects > 0) diagnostics.push({
+		severity: "warning",
+		code: "no-authored-smrt-objects",
+		message: [
+			`No SMRT objects were discovered in the project's own packages under ${rootDir},`,
+			`though ${installedObjects} were read from installed dependencies.`,
+			"Expected for an application that only consumes the framework;",
+			"a discovery failure if this workspace is supposed to declare @smrt() classes."
+		].join(" "),
+		remedy: [
+			"If this workspace authors SMRT objects, confirm rootDir is the workspace root,",
+			"confirm the workspace globs cover the directories that hold @smrt() classes,",
+			"and run `pnpm build` in the owning package to emit .smrt/manifest.json."
+		].join(" ")
+	});
+	if (authoredObjects === 0 && installedObjects === 0) diagnostics.push({
 		severity: "error",
 		code: "no-smrt-objects-discovered",
 		message: [
@@ -180,7 +874,7 @@ function buildIndexDiagnostics(rootDir, packages, coverage, discoveryDiagnostics
 			`Package directories checked (${coverage.packageDirs.length}): ${coverage.packageDirs.join(", ") || "(none)"}.`,
 			"Treat this as a discovery failure, not as evidence that the project has no SMRT model."
 		].join(" "),
-		checkedPaths: [...new Set(packages.flatMap((pkg) => pkg.checkedObjectPaths))],
+		checkedPaths: [...new Set(authoredPackages.flatMap((pkg) => pkg.checkedObjectPaths))],
 		remedy: [
 			"Confirm rootDir is the workspace root;",
 			"confirm pnpm-workspace.yaml `packages:` covers the directories that hold @smrt() classes (for example apps/*);",
@@ -250,10 +944,11 @@ async function checkKnowledgeFreshness(options = {}) {
 async function checkKnowledgeFreshnessFromIndex(index, options = {}) {
 	const issues = [];
 	const changedFiles = options.changed ? getChangedFiles(index.rootDir) : void 0;
-	const hasMemberPackages = index.packages.some((item) => item.kind !== "sdk" && !item.isWorkspaceRoot);
-	const memberDirectories = index.packages.filter((item) => item.kind !== "sdk" && !item.isWorkspaceRoot && item.relativeDirectory).map((item) => item.relativeDirectory);
+	const authoredPackages = index.packages.filter((item) => !item.isInstalledDependency);
+	const hasMemberPackages = authoredPackages.some((item) => item.kind !== "sdk" && !item.isWorkspaceRoot);
+	const memberDirectories = authoredPackages.filter((item) => item.kind !== "sdk" && !item.isWorkspaceRoot && item.relativeDirectory).map((item) => item.relativeDirectory);
 	const isNestedMember = (pkg) => Boolean(pkg.relativeDirectory) && memberDirectories.some((directory) => directory !== pkg.relativeDirectory && pkg.relativeDirectory.startsWith(`${directory}/`));
-	for (const pkg of index.packages.filter((item) => item.kind !== "sdk" && !(item.isWorkspaceRoot && hasMemberPackages))) {
+	for (const pkg of authoredPackages.filter((item) => item.kind !== "sdk" && !(item.isWorkspaceRoot && hasMemberPackages))) {
 		const packageJsonPath = join(pkg.directory, "package.json");
 		const nested = isNestedMember(pkg);
 		if (!pkg.hasAgentsMd && !nested) issues.push({
@@ -310,7 +1005,9 @@ async function checkKnowledgeFreshnessFromIndex(index, options = {}) {
 			packageName: pkg.name
 		});
 	}
-	for (const pkg of index.packages) issues.push(...checkDomainKnowledgeArtifact(index.rootDir, pkg));
+	for (const pkg of authoredPackages) issues.push(...checkDomainKnowledgeArtifact(index.rootDir, pkg));
+	const devMcpPackage = authoredPackages.find((pkg) => pkg.name === "@happyvertical/smrt-dev-mcp");
+	if (devMcpPackage) issues.push(...checkMcpToolDocumentation(index.rootDir, devMcpPackage.directory, TOOLS));
 	issues.push(...findStalePatternIssues(index.rootDir, changedFiles));
 	const effectiveIssues = issues.map((issue) => issue.code.startsWith("stale-") ? {
 		...issue,
@@ -517,6 +1214,7 @@ function renderKnowledgeIndexMarkdown(index) {
 		"",
 		`- SMRT packages: ${index.smrtPackages.length}`,
 		`- SDK packages: ${index.sdkPackages.length}`,
+		`- Installed dependencies: ${index.installedPackages.length}`,
 		`- foreignKey fields: ${index.relationshipsV2.foreignKeyFields}`,
 		`- crossPackageRef fields: ${index.relationshipsV2.crossPackageRefFields}`,
 		`- junction collections: ${index.relationshipsV2.junctionCollections}`,
@@ -540,6 +1238,10 @@ function renderKnowledgeIndexMarkdown(index) {
 		lines.push(`- MCP tools: ${pkg.mcpTools.length}`);
 		lines.push(`- domain knowledge: ${pkg.domainKnowledgePath ?? "(manifest fallback)"}`);
 		lines.push(`- docs: ${pkg.docSource ?? "(none)"}${pkg.hasClaudeShim ? " + CLAUDE.md shim" : ""}`);
+		if (pkg.isInstalledDependency) {
+			lines.push("- source: installed dependency");
+			lines.push(`- AGENTS.md sha256: ${pkg.agentDocSha256 ?? "(none)"}`);
+		}
 		if (pkg.moduleDocs.length > 0) lines.push(`- module docs: ${pkg.moduleDocs.map((doc) => doc.path).join(", ")}`);
 		if (pkg.relationshipFeatures.length > 0) lines.push(`- relationships-v2: ${pkg.relationshipFeatures.join(", ")}`);
 		lines.push("");
@@ -817,34 +1519,85 @@ function discoverProjectPackageDirs(rootDir) {
 		diagnostics: expansion.diagnostics
 	};
 }
-function discoverInstalledSdkPackages(rootDir, packageDirs, includeDocs) {
-	return [join(rootDir, "node_modules", "@happyvertical"), ...packageDirs.map((dir) => join(dir, "node_modules", "@happyvertical"))].filter((scopeDir, index, all) => existsSync(scopeDir) && all.indexOf(scopeDir) === index).flatMap((scopeDir) => readdirSync(scopeDir, { withFileTypes: true }).filter((entry) => entry.isDirectory() || entry.isSymbolicLink()).map((entry) => {
-		const entryPath = join(scopeDir, entry.name);
+/**
+* Installed `@happyvertical/*` packages, resolved once each (#2275).
+*
+* Reads the `@happyvertical` scope directory of the project and of every
+* workspace package — one `readdir` per scope directory, resolving each entry's
+* real path — instead of descending through `node_modules`. Under pnpm those
+* entries are symlinks into a store whose entries link back out to each other,
+* so a descent revisits the same package once per path that reaches it. The
+* realpath is the dedupe key only: the same store entry reached from three
+* scope directories is read once, but it is read through its `node_modules`
+* path, because a realpath is the wrong thing to report. On a host where any
+* ancestor of the root is a symlink (`/var` on macOS, a symlinked worktree),
+* `relative(rootDir, realpath)` escapes the root entirely.
+*
+* Workspace packages linked into a sibling's `node_modules` are skipped here.
+* They are authored source that happens to be reachable through a link, and
+* calling them installed would exempt them from the freshness gate.
+*
+* Both SMRT and SDK packages are returned. A consumer app authors neither, and
+* its `@happyvertical/smrt-*` dependencies are exactly the surface it needs to
+* audit; excluding them is why the index could see nothing in a consumer app.
+*/
+function discoverInstalledPackages(rootDir, packageDirs, includeDocs) {
+	const scopeDirs = [join(rootDir, "node_modules", "@happyvertical"), ...packageDirs.map((dir) => join(dir, "node_modules", "@happyvertical"))];
+	const workspaceRealPaths = new Set([rootDir, ...packageDirs].flatMap((dir) => {
+		try {
+			return [realpathSync(dir)];
+		} catch {
+			return [];
+		}
+	}));
+	const byRealPath = /* @__PURE__ */ new Map();
+	for (const scopeDir of new Set(scopeDirs)) {
+		if (!existsSync(scopeDir)) continue;
+		let entries;
 		try {
-			return lstatSync(entryPath).isSymbolicLink() ? realpathSync(entryPath) : entryPath;
+			entries = readdirSync(scopeDir, { withFileTypes: true });
 		} catch {
-			return entryPath;
+			continue;
 		}
-	})).filter((dir) => {
-		const pkg = objectRecord(readJson(join(dir, "package.json")));
-		return typeof pkg.name === "string" && SDK_PACKAGE_NAMES.has(pkg.name) && !pkg.name.startsWith("@happyvertical/smrt-");
-	}).map((dir) => readKnowledgePackage(rootDir, dir, includeDocs));
+		for (const entry of entries) {
+			if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
+			const entryPath = join(scopeDir, entry.name);
+			let resolved;
+			try {
+				resolved = realpathSync(entryPath);
+			} catch {
+				continue;
+			}
+			if (workspaceRealPaths.has(resolved)) continue;
+			if (byRealPath.has(resolved)) continue;
+			byRealPath.set(resolved, entryPath);
+		}
+	}
+	const packages = [];
+	for (const directory of byRealPath.values()) {
+		const name = objectRecord(readJson(join(directory, "package.json"))).name;
+		if (typeof name !== "string") continue;
+		if (!SDK_PACKAGE_NAMES.has(name) && !name.startsWith("@happyvertical/smrt-")) continue;
+		packages.push(readKnowledgePackage(rootDir, directory, includeDocs, { installed: true }));
+	}
+	return packages.sort((a, b) => a.name.localeCompare(b.name));
 }
 function filterKnowledgePackages(packages, options) {
 	const packageQuery = options.packageName ?? options.package;
 	return packages.filter((pkg) => {
 		if (packageQuery && !packageMatches(pkg, packageQuery.toLowerCase())) return false;
 		switch (options.scope) {
-			case "local": return pkg.kind !== "sdk" && !pkg.relativeDirectory.includes("node_modules");
-			case "package": return pkg.kind !== "sdk";
+			case "local": return pkg.kind !== "sdk" && !pkg.isInstalledDependency && !pkg.relativeDirectory.includes("node_modules");
+			case "package": return pkg.kind !== "sdk" && !pkg.isInstalledDependency;
 			case "sdk": return pkg.kind === "sdk";
+			case "installed": return pkg.isInstalledDependency;
 			case "project":
 			case void 0: return true;
 			default: return true;
 		}
 	});
 }
-function readKnowledgePackage(rootDir, directory, includeDocs) {
+function readKnowledgePackage(rootDir, directory, includeDocs, options = {}) {
 	const packageJson = objectRecord(readJson(join(directory, "package.json")));
 	const dependencies = stringRecord(packageJson.dependencies);
 	const devDependencies = stringRecord(packageJson.devDependencies);
@@ -894,6 +1647,7 @@ function readKnowledgePackage(rootDir, directory, includeDocs) {
 		hasClaudeShim: claudeContent.trim() === "@AGENTS.md",
 		docSource,
 		agentDoc: includeDocs ? domainKnowledge?.content.agentDoc || (hasAgentsMd ? agentsContent : fallbackClaudeDoc || void 0) : void 0,
+		agentDocSha256: hasAgentsMd ? createHash("sha256").update(agentsContent).digest("hex") : void 0,
 		moduleDocs: includeDocs ? domainKnowledge?.content.moduleDocs ?? readAgentModuleDocs(directory, agentsContent || void 0) : [],
 		hasDomainKnowledge: Boolean(domainKnowledge),
 		domainKnowledgePath: domainKnowledge?.path ? relative(rootDir, domainKnowledge.path) : void 0,
@@ -906,6 +1660,7 @@ function readKnowledgePackage(rootDir, directory, includeDocs) {
 		relationshipFeatures: relationshipFeatures(objects),
 		isWorkspaceRoot: resolve(directory) === resolve(rootDir),
 		isPrivate: packageJson.private === true,
+		isInstalledDependency: options.installed === true,
 		objectSource: resolvedObjects.source,
 		objectSourceReason: resolvedObjects.reason,
 		checkedObjectPaths: resolvedObjects.checkedPaths
@@ -1547,7 +2302,7 @@ function selectPackages(index, options) {
 	const selected = /* @__PURE__ */ new Set();
 	const packageName = options.packageName?.toLowerCase();
 	if (packageName) {
-		for (const pkg of domainPackages(index)) if (packageMatches(pkg, packageName)) selected.add(pkg);
+		for (const pkg of domainPackages(index)) if (scopeAllowsPackage(pkg, options.scope) && packageMatches(pkg, packageName)) selected.add(pkg);
 	}
 	for (const pkg of selectPackagesForFiles(index, options.changedFiles ?? [])) if (scopeAllowsPackage(pkg, options.scope)) selected.add(pkg);
 	const text = (options.text ?? "").toLowerCase();
@@ -1565,7 +2320,7 @@ function selectPackages(index, options) {
 			"@happyvertical/smrt-dev-mcp"
 		]) {
 			const pkg = index.smrtPackages.find((item) => item.name === name);
-			if (pkg) selected.add(pkg);
+			if (pkg && scopeAllowsPackage(pkg, options.scope)) selected.add(pkg);
 		}
 		if (selected.size === 0) {
 			const contributing = domainPackages(index).filter((pkg) => pkg.objects.length > 0 && scopeAllowsPackage(pkg, options.scope) && !pkg.relativeDirectory.includes("node_modules")).sort((a, b) => b.objects.length - a.objects.length).slice(0, MAX_FALLBACK_PACKAGES);
@@ -1580,28 +2335,41 @@ function selectSdkPackages(index, selectedPackages, texts, options = {}) {
 	const text = texts.filter(Boolean).join("\n").toLowerCase();
 	const packageName = options.packageName?.toLowerCase();
 	for (const sdk of index.sdkPackages) {
+		const selectedDependency = sdkNames.has(sdk.name);
+		if (!scopeAllowsSdkPackage(sdk, options.scope, selectedDependency)) continue;
 		const shortName = sdk.name.replace("@happyvertical/", "");
-		if (options.scope === "sdk" || sdkNames.has(sdk.name) || packageName && packageMatches(sdk, packageName) || text.includes(sdk.name.toLowerCase()) || includesToken(text, shortName)) selected.add(sdk);
+		if (options.scope === "sdk" || selectedDependency || packageName && packageMatches(sdk, packageName) || text.includes(sdk.name.toLowerCase()) || includesToken(text, shortName)) selected.add(sdk);
 	}
-	if (selected.size === 0) for (const name of [
+	if (selected.size === 0 && !(packageName && selectedPackages.length === 0)) for (const name of [
 		"@happyvertical/ai",
 		"@happyvertical/sql",
 		"@happyvertical/files",
 		"@happyvertical/utils"
 	]) {
-		const sdk = index.sdkPackages.find((item) => item.name === name);
+		const sdk = index.sdkPackages.find((item) => item.name === name && scopeAllowsSdkPackage(item, options.scope, false));
 		if (sdk) selected.add(sdk);
 	}
 	return [...selected].sort((a, b) => a.name.localeCompare(b.name));
 }
+function scopeAllowsSdkPackage(pkg, scope, selectedDependency) {
+	switch (scope) {
+		case "installed": return pkg.isInstalledDependency;
+		case "local":
+		case "package": return !pkg.isInstalledDependency || selectedDependency;
+		case "sdk":
+		case "project":
+		case void 0: return true;
+	}
+}
 function domainPackages(index) {
 	return index.packages.filter((pkg) => pkg.kind !== "sdk");
 }
 function scopeAllowsPackage(pkg, scope) {
 	switch (scope) {
 		case "sdk": return false;
-		case "local": return !pkg.relativeDirectory.includes("node_modules");
-		case "package":
+		case "installed": return pkg.isInstalledDependency;
+		case "local": return !pkg.isInstalledDependency && !pkg.relativeDirectory.includes("node_modules");
+		case "package": return !pkg.isInstalledDependency;
 		case "project":
 		case void 0: return true;
 	}
@@ -1834,6 +2602,6 @@ function sortJson(value) {
 	return value;
 }
 //#endregion
-export { checkKnowledgeFreshnessFromIndex as a, renderFreshnessResult as c, smrtReview as d, checkKnowledgeFreshness as i, renderKnowledgeIndexMarkdown as l, buildKnowledgeIndex as n, diffKnowledgeIndex as o, buildReviewContext as r, packageDocPaths as s, buildArchitectureContext as t, smrtArchitecture as u };
+export { checkKnowledgeFreshnessFromIndex as a, renderFreshnessResult as c, smrtReview as d, REVIEW_SKILL_NAME as f, checkKnowledgeFreshness as i, renderKnowledgeIndexMarkdown as l, buildKnowledgeIndex as n, diffKnowledgeIndex as o, TOOLS as p, buildReviewContext as r, packageDocPaths as s, buildArchitectureContext as t, smrtArchitecture as u };
 
-//# sourceMappingURL=knowledge-DUUhTM5u.js.map
+//# sourceMappingURL=knowledge-A7-gIjW4.js.map