@happyvertical/smrt-cli 0.51.39 → 0.53.0

package/dist/{commands-C2PjCUio.js → commands-e1tsvozP.js}

@@ -2,7 +2,7 @@ import { t as resolveManifestEntryPackageName } from "./index.js";
 import { t as DEFAULT_CLI_CONFIG } from "./config-hqNo4lzH.js";
 import { createRequire } from "node:module";
 import * as fs from "node:fs";
-import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, writeFileSync } from "node:fs";
 import * as path from "node:path";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
@@ -13,7 +13,7 @@ import { createLogger } from "@happyvertical/logger";
 import glob from "fast-glob";
 import { createHash } from "node:crypto";
 import { getPackageConfig } from "@happyvertical/smrt-config";
-import { toSnakeCase } from "@happyvertical/smrt-core/utils";
+import { toSnakeCase as toSnakeCase$1 } from "@happyvertical/smrt-core/utils";
 import { checkKnowledgeGraphFreshness, discoverScopedPackageDirectories, readAgentModuleDocs, readPackageAgentDoc, resolveAgentModuleDocPaths } from "@happyvertical/smrt-core/knowledge";
 import { MCPGenerator } from "@happyvertical/smrt-core/generators";
 import { generateDeclarationsFromCLI } from "@happyvertical/smrt-core/prebuild";
@@ -21,9 +21,10 @@ import { execFileSync, execSync, spawn, spawnSync } from "node:child_process";
 import https from "node:https";
 import { homedir, tmpdir } from "node:os";
 import { extract } from "tar";
+import Ajv2020 from "ajv/dist/2020.js";
 import { importWorkspaceModule } from "@happyvertical/smrt-core/utils/import-workspace-module";
 import { renderForeignKeyAddStatements } from "@happyvertical/smrt-core/schema";
-import { FRAMEWORK_BASE_TABLE_NAMES, buildIntegerWidthTableStatements, collectIntegerWidthTargets, collectNullEqualIndexTargets, dropFrameworkBaseTables, migrateNullEqualIndexes, nullEqualIndexStatements, parsePostgresTimeoutMs, planFrameworkBaseTableDrop, preflightIntegerWidthWidening, preflightNullEqualIndexes, widenIntegerColumnsToBigInt } from "@happyvertical/smrt-core/migrations";
+import { FRAMEWORK_BASE_TABLE_NAMES, backfillLegacyQualifiedNames, buildIntegerWidthTableStatements, collectIntegerWidthTargets, collectNullEqualIndexTargets, countLegacyQualifiedNameReferences, dropFrameworkBaseTables, migrateNullEqualIndexes, nullEqualIndexStatements, parsePostgresTimeoutMs, planFrameworkBaseTableDrop, preflightIntegerWidthWidening, preflightNullEqualIndexes, widenIntegerColumnsToBigInt } from "@happyvertical/smrt-core/migrations";
 import { buildArchitectureContext, buildKnowledgeIndex, buildReviewContext, checkKnowledgeFreshness, compactContextResult, diffKnowledgeIndex, renderFreshnessResult, renderKnowledgeIndexMarkdown } from "@happyvertical/smrt-dev-mcp/knowledge";
 import { RUNTIME_TOOLS } from "@happyvertical/smrt-dev-mcp/runtime";
 //#region src/commands/db-command-utils.ts
@@ -767,7 +768,8 @@ function partitionSchemaChanges(changes, getClassForTable) {
 					...change.foreignKey ? { foreignKey: change.foreignKey } : {},
 					...change.orphanBlocked !== void 0 ? { orphanBlocked: change.orphanBlocked } : {},
 					...change.orphanNullable !== void 0 ? { orphanNullable: change.orphanNullable } : {},
-					...change.engineUnsupported !== void 0 ? { engineUnsupported: change.engineUnsupported } : {}
+					...change.engineUnsupported !== void 0 ? { engineUnsupported: change.engineUnsupported } : {},
+					...change.note ? { note: change.note } : {}
 				};
 				if (isAdvisoryOnlyChangeLike(change)) manualInterventions.push(action);
 				else migrations.push(action);
@@ -833,7 +835,8 @@ function partitionSchemaChanges(changes, getClassForTable) {
 						actual: mm.actual
 					},
 					sql: change.sql,
-					...change.sqlStatements ? { sqlStatements: change.sqlStatements } : {}
+					...change.sqlStatements ? { sqlStatements: change.sqlStatements } : {},
+					...change.note ? { note: change.note } : {}
 				};
 				const executionKind = classifyTypeUpgradeSql(change.sql);
 				if (executionKind === "executable") migrations.push(action);
@@ -1230,6 +1233,11 @@ var dbDiffCommand = {
 			description: "Include orphan-index drops in the diff (indexes in DB but not in the manifest, excluding *_pkey/*_key implicit-from-constraint indexes). Off by default for safety.",
 			default: false
 		},
+		"drop-legacy-natural-key": {
+			type: "boolean",
+			description: "Include the drop of the legacy global (slug, context) unique index a tenant-led natural key superseded (see db:migrate --drop-legacy-natural-key).",
+			default: false
+		},
 		"drop-columns": {
 			type: "boolean",
 			description: "Include orphan-column drops in the diff (columns in DB but not in the manifest). Off by default; orphans are always reported.",
@@ -1243,6 +1251,11 @@ var dbDiffCommand = {
 		"postgres-timestamp-legacy-timezone": {
 			type: "string",
 			description: "Confirm that legacy PostgreSQL timestamp-without-time-zone values are UTC wall times before previewing their conversion to timestamptz. Exact value required: UTC; omitted by default."
+		},
+		"empty-text-as-null": {
+			type: "boolean",
+			description: "Preview storing empty or whitespace-only text as NULL when converging a nullable legacy text column to a typed column (timestamp, JSON, integer). Any other value that does not convert still blocks. Off by default; the diff names the empty-text count instead.",
+			default: false
 		}
 	},
 	handler: async (_args, options) => {
@@ -1298,8 +1311,10 @@ var dbDiffCommand = {
 				includeDroppedTables: false,
 				includeDroppedColumns: Boolean(options["drop-columns"]),
 				includeDroppedIndexes: Boolean(options["drop-indexes"]),
+				dropLegacyNaturalKey: Boolean(options["drop-legacy-natural-key"]),
 				relaxColumns: Boolean(options["relax-columns"]),
-				postgresTimestampMigration
+				postgresTimestampMigration,
+				emptyTextAsNull: Boolean(options["empty-text-as-null"])
 			}).compare(schemaDefinitions);
 			if (options.json) {
 				console.log(JSON.stringify({
@@ -1394,9 +1409,21 @@ var dbDiffCommand = {
 			}
 			if (typeUpgrades.length > 0) {
 				console.log(`  🔁 Type upgrades (${typeUpgrades.length}):`);
-				for (const change of typeUpgrades) console.log(`     ⤴ ${change.table}.${change.name}: ${change.mismatch?.actual} → ${change.mismatch?.expected}`);
+				for (const change of typeUpgrades) {
+					console.log(`     ⤴ ${change.table}.${change.name}: ${change.mismatch?.actual} → ${change.mismatch?.expected}`);
+					if (change.note) console.log(`       (${change.note})`);
+				}
 				console.log("     (auto-applied by smrt db:migrate)\n");
 			}
+			const foreignKeyChanges = diff.changes.filter((c) => c.type === "add_foreign_key" && (c.sql || c.sqlStatements?.length));
+			if (foreignKeyChanges.length > 0) {
+				console.log(`  🔗 Foreign keys (${foreignKeyChanges.length}):`);
+				for (const change of foreignKeyChanges) {
+					console.log(`     + ${change.name} on ${change.table}${change.note ? ` (${change.note})` : ""}`);
+					if (change.advisory?.severity === "warning") console.log(`       ⚠️  ${change.advisory.message}`);
+				}
+				console.log();
+			}
 			if (typeMismatches.length > 0) {
 				console.log(`  ⚠️  Type mismatches (${typeMismatches.length}):`);
 				for (const change of typeMismatches) console.log(`     ! ${change.table}.${change.name}: ${change.mismatch?.expected} vs ${change.mismatch?.actual}`);
@@ -1581,6 +1608,11 @@ var dbHistoryCommand = {
 			description: "Show full details including checksums",
 			default: false,
 			short: "v"
+		},
+		"empty-text-as-null": {
+			type: "boolean",
+			description: "Assess the same convergence `db:migrate --empty-text-as-null` would apply: a nullable legacy text column whose only obstacle is empty or whitespace-only text is pending, not blocked. Off by default.",
+			default: false
 		}
 	},
 	handler: async (_args, options) => {
@@ -1619,7 +1651,7 @@ var dbHistoryCommand = {
 			if (failedHistory.length > 0 && typeof db.getTableSchema === "function") try {
 				await autoDiscoverAndLoad();
 				const manifestSchemas = ObjectRegistry.getAllSchemasAsDefinitions();
-				const diff = await new SchemaComparer(db).compare(manifestSchemas);
+				const diff = await new SchemaComparer(db, { emptyTextAsNull: Boolean(options["empty-text-as-null"]) }).compare(manifestSchemas);
 				liveSchemaCompared = true;
 				failedAssessments = assessFailedMigrations(failedHistory, diff);
 			} catch {
@@ -2868,7 +2900,7 @@ async function evaluateSchemaContract(options) {
 			present = (await ObjectRegistry.getAllFields(entry.name)).has(fieldName);
 			if (present) {
 				table = inferTableName(entry);
-				column = toSnakeCase(fieldName);
+				column = toSnakeCase$1(fieldName);
 				if (table) {
 					inferredTables.add(table);
 					inferredColumns.add(`${table}.${column}`);
@@ -2928,6 +2960,99 @@ function assertSchemaContract(report) {
 	if (!report.ok) throw new SchemaContractError(report);
 }
 //#endregion
+//#region src/commands/tenant-natural-keys.ts
+/**
+* Tenant natural-key detector for `db:status`.
+*
+* A tenant-owned table (declared tenant scope, or an undeclared `tenantId`
+* field — `ObjectRegistry.getOwnershipTenantColumn()`) upserts on a
+* tenant-led key such as `(tenant_id, slug, context)`. A live database created
+* before that default can still carry the GLOBAL `(slug, context)` unique:
+* then a second tenant's same-slug save collides with a row it cannot see.
+* Before the save-time ownership guard, `ON CONFLICT … DO UPDATE` rewrote that
+* row's `id` and `tenant_id` (the Anytown Ludis takeover); now the save is
+* refused, and on engines that require an exact ON CONFLICT target the create
+* fails until `smrt db:migrate` swaps the index.
+*
+* Rollout is expand, then contract: `smrt db:migrate` builds the tenant-led
+* unique beside the global one (an `error` until it exists, so db:status exits
+* 1), and the global one stays — reported as a `warning` — until
+* `smrt db:migrate --drop-legacy-natural-key` once no old code is running.
+* Explicit `@smrt({ conflictColumns })` that omit the tenant column are the
+* author's declared contract and are not reported here (the tenancy
+* package's `auditTenantScopedRegistrations()` flags runtime-registered ones).
+*/
+function sameColumnSet(a, b) {
+	return a.length === b.length && a.every((column) => b.includes(column));
+}
+/**
+* Compare every tenant-owned table's upsert target with its live unique
+* indexes. Tables absent from `liveSchemas` (not created yet, or not
+* introspected) are skipped — the schema diff reports those.
+*/
+function checkTenantNaturalKeyUniques(liveSchemas) {
+	const findings = [];
+	const seenTables = /* @__PURE__ */ new Set();
+	for (const className of ObjectRegistry.getQualifiedClassNames()) {
+		if (isCollectionRegistration(className)) continue;
+		const tableName = ObjectRegistry.getTableName(className);
+		if (!tableName || seenTables.has(tableName)) continue;
+		const tenantColumn = ObjectRegistry.getOwnershipTenantColumn(className);
+		if (!tenantColumn) continue;
+		const conflictColumns = ObjectRegistry.getConflictColumns(className);
+		if (!conflictColumns.includes(tenantColumn)) continue;
+		const live = liveSchemas.get(tableName);
+		if (!live) continue;
+		seenTables.add(tableName);
+		const uniques = (live.indexes ?? []).filter((index) => index.unique === true && !index.where);
+		const naturalKey = conflictColumns.filter((column) => column !== tenantColumn);
+		const global = uniques.find((index) => sameColumnSet(index.columns ?? [], naturalKey));
+		const target = `(${conflictColumns.join(", ")})`;
+		if (uniques.some((index) => sameColumnSet(index.columns ?? [], conflictColumns))) {
+			if (global) findings.push({
+				name: `${tableName}.${global.name ?? "(unnamed unique)"}`,
+				status: "warning",
+				message: `Tenant-owned table "${tableName}" (${className}) still carries the legacy unique index on (${naturalKey.join(", ")}) beside the tenant-led ${target}. Until it is dropped, a second tenant cannot store a key another tenant already uses (the save fails with a unique violation; nothing is overwritten).`,
+				recommendation: "Once every running instance is on the release that upserts on the tenant-led key, run `smrt db:migrate --drop-legacy-natural-key` to drop it.",
+				details: {
+					className,
+					tableName,
+					conflictColumns,
+					liveIndex: global.name,
+					kind: "legacy_global_unique"
+				}
+			});
+			continue;
+		}
+		if (global) findings.push({
+			name: `${tableName}.${global.name ?? "(unnamed unique)"}`,
+			status: "error",
+			message: `Tenant-owned table "${tableName}" (${className}) has a unique index on (${naturalKey.join(", ")}) shared by every tenant, but the model upserts on ${target}. A second tenant cannot store a key another tenant already uses; saves that collide are refused (TENANT_ISOLATION_VIOLATION), and creates can fail outright until the index matches the upsert target.`,
+			recommendation: "Run `smrt db:migrate` BEFORE deploying the release that upserts on the tenant-led key: it builds the tenant-inclusive unique under its own name (a superset, so it cannot fail on existing rows) and keeps this one, so old code (ON CONFLICT on the global key) and new code (ON CONFLICT on the tenant-led key) both keep working. After the rollout, `smrt db:migrate --drop-legacy-natural-key` drops the legacy index.",
+			details: {
+				className,
+				tableName,
+				conflictColumns,
+				liveIndex: global.name,
+				kind: "global_unique"
+			}
+		});
+		else findings.push({
+			name: `${tableName}.${target}`,
+			status: "warning",
+			message: `Tenant-owned table "${tableName}" (${className}) has no unique index on ${target}, the key the model upserts on.`,
+			recommendation: "Run `smrt db:migrate` to create the tenant-inclusive unique index.",
+			details: {
+				className,
+				tableName,
+				conflictColumns,
+				kind: "missing_tenant_unique"
+			}
+		});
+	}
+	return findings;
+}
+//#endregion
 //#region src/commands/db-status.ts
 /**
 * db:status Command
@@ -3148,6 +3273,11 @@ var dbStatusCommand = {
 			description: "Also compare the live schema to the expected shape (incl. _smrt_* system tables and index policy)",
 			default: false,
 			short: "p"
+		},
+		"empty-text-as-null": {
+			type: "boolean",
+			description: "Assess the same convergence `db:migrate --empty-text-as-null` would apply: a nullable legacy text column whose only obstacle is empty or whitespace-only text is pending, not blocked. Off by default.",
+			default: false
 		}
 	},
 	handler: async (_args, options) => {
@@ -3246,16 +3376,16 @@ var dbStatusCommand = {
 			const manifestSchemas = ObjectRegistry.getAllSchemasAsDefinitions();
 			let comparer;
 			if (typeof db.getTableSchema === "function") {
-				comparer = new SchemaComparer(db);
+				comparer = new SchemaComparer(db, { emptyTextAsNull: Boolean(options["empty-text-as-null"]) });
 				diff = await comparer.compare(manifestSchemas);
 				status.drift = summarizeSchemaDiff(diff);
 				status.notes = summarizeSchemaNotes(diff);
-				status.preconditions = await checkTenantIdUuidPreconditions({
+				status.preconditions = [...await checkTenantIdUuidPreconditions({
 					db,
 					dbType,
 					dbUrl,
 					manifestSchemas
-				});
+				}), ...checkTenantNaturalKeyUniques(comparer.getLiveSchemaSnapshot())];
 				status.failedMigrations = summarizeFailedMigrations(failed, getUnresolvedGeneratedMigrationNames(diff.changes));
 				if (options.parity) try {
 					status.parity = await checkLiveSchemaParity({
@@ -4139,14 +4269,14 @@ var docsCommands = {
 * This replaces per-agent export commands (praeco export, caelus export, etc.)
 * with a single, schema-driven export that respects field-level export annotations.
 */
-function toSnakeCase$1(str) {
+function toSnakeCase$2(str) {
 	return str.replace(/([A-Z])/g, "_$1").toLowerCase().replace(/^_/, "");
 }
 function toColumnName(fieldName) {
 	const dotIndex = fieldName.indexOf(".");
 	const baseFieldName = dotIndex >= 0 ? fieldName.substring(0, dotIndex) : fieldName;
 	const jsonPath = dotIndex >= 0 ? fieldName.substring(dotIndex) : "";
-	return `${baseFieldName.startsWith("_") ? `_${toSnakeCase$1(baseFieldName.slice(1))}` : toSnakeCase$1(baseFieldName)}${jsonPath}`;
+	return `${baseFieldName.startsWith("_") ? `_${toSnakeCase$2(baseFieldName.slice(1))}` : toSnakeCase$2(baseFieldName)}${jsonPath}`;
 }
 function assertSafeIdentifier(identifier, label) {
 	if (!/^[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z_][a-zA-Z0-9_]*)*$/.test(identifier)) throw new Error(`Invalid ${label}: ${identifier}`);
@@ -5554,6 +5684,19 @@ async function loadGitTemplate(gitUrl) {
 	}
 }
 /**
+* Get the template directory path (for copying overlay files)
+*
+* Prefers the subdir-resolved `__templateRoot` so that subdirectory templates
+* (`github:user/repo/subdir`) overlay from the subdir rather than the repo root.
+* Falls back to `__tempDir` for configs loaded before the field existed.
+*/
+function getGitTemplateDir(config) {
+	const gitConfig = config;
+	const templateRoot = gitConfig.__templateRoot ?? gitConfig.__tempDir;
+	if (!templateRoot) throw new Error("Template was not loaded from git repository");
+	return templateRoot;
+}
+/**
 * Cleanup temporary directory after template is used
 */
 async function cleanupGitTemplate(config) {
@@ -6102,8 +6245,310 @@ async function processPlaceholders(outputDir, config, options) {
 	console.log(`   Processed placeholders in ${replacedCount} files`);
 }
 //#endregion
+//#region src/commands/mcp-apps-packaging.ts
+/**
+* Portable MCP Apps plugin packaging helpers.
+*
+* These helpers intentionally validate distribution metadata only. Runtime
+* MCP extension metadata is owned by the v2 server adapter and is not an
+* install-plugin manifest.
+*/
+var requireSchema = createRequire(import.meta.url);
+var pluginSchema = requireSchema("@happyvertical/smrt-dev-mcp/schemas/agent-plugins-1.0.0/plugin.schema.json");
+var mcpSchema = requireSchema("@happyvertical/smrt-dev-mcp/schemas/agent-plugins-1.0.0/mcp.schema.json");
+var ajv = new Ajv2020({
+	strict: true,
+	allErrors: true
+});
+var validatePluginSchema = ajv.compile(pluginSchema);
+var validateMcpSchema = ajv.compile(mcpSchema);
+var PLUGIN_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json";
+var MCP_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json";
+var CANONICAL_SCOPE_REGISTRY = "@happyvertical:registry=https://npm.happyvertical.com/";
+var SECRET_KEY = /(?:api[_-]?key|secret|token|password|authorization|credential)/i;
+var ENVIRONMENT_CREDENTIAL_FILE = /^\.env(?:\.|$)/;
+var PRIVATE_KEY_CARRIER = /^(?:id_(?:rsa|dsa|ecdsa|ed25519)|private(?:[._-]key)?|.*\.key)$/i;
+var PRIVATE_KEY_HEADER = /-----BEGIN(?: [A-Z0-9]+)* PRIVATE KEY-----/;
+function add(result, code, message) {
+	result.findings.push({
+		code,
+		message
+	});
+}
+function readJson$1(path, result) {
+	try {
+		return JSON.parse(readFileSync(path, "utf8"));
+	} catch (error) {
+		add(result, "json-malformed", `${relative(process.cwd(), path)} is not valid JSON`);
+		return;
+	}
+}
+function isObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function safeRelativePath(value, field, root, result) {
+	if (typeof value !== "string" || !value.startsWith("./") || value.includes("\\") || value.split("/").includes("..")) {
+		add(result, "unsafe-path", `${field} must be a root-relative ./ path without parent segments`);
+		return;
+	}
+	const target = resolve(root, value);
+	if (!target.startsWith(`${root}${sep}`)) {
+		add(result, "unsafe-path", `${field} resolves outside the plugin root`);
+		return;
+	}
+	try {
+		const stat = lstatSync(target);
+		if (stat.isSymbolicLink() || !stat.isFile()) add(result, "invalid-resource", `${field} must name a regular file`);
+	} catch {
+		add(result, "missing-resource", `${field} does not exist`);
+	}
+}
+function scanTree(root, current, result) {
+	for (const entry of readdirSync(current, { withFileTypes: true })) {
+		const path = join(current, entry.name);
+		const display = relative(root, path);
+		const stat = lstatSync(path);
+		if (stat.isSymbolicLink()) add(result, "symlink", `${display} is a symbolic link; plugin packages must contain regular files`);
+		else if (stat.isDirectory()) scanTree(root, path, result);
+		else if (stat.isFile()) if (ENVIRONMENT_CREDENTIAL_FILE.test(entry.name) || PRIVATE_KEY_CARRIER.test(entry.name)) add(result, "secret-artifact", `${display} is a credential carrier and cannot be packaged`);
+		else try {
+			if (PRIVATE_KEY_HEADER.test(readFileSync(path, "utf8"))) add(result, "secret-artifact", `${display} contains a private key and cannot be packaged`);
+		} catch {
+			add(result, "artifact-unreadable", `${display} could not be inspected and cannot be packaged`);
+		}
+	}
+}
+function scanSecrets(value, source, result) {
+	if (Array.isArray(value)) {
+		value.forEach((item) => {
+			scanSecrets(item, source, result);
+		});
+		return;
+	}
+	if (!isObject(value)) return;
+	for (const [key, child] of Object.entries(value)) {
+		if (SECRET_KEY.test(key) && typeof child === "string" && child.trim()) add(result, "secret-artifact", `${source} contains a credential-shaped ${key} field`);
+		scanSecrets(child, source, result);
+	}
+}
+function validateServerUrl(value, name, result) {
+	if (typeof value !== "string") return add(result, "server-url", `mcpServers.${name}.url must be a string`);
+	try {
+		const url = new URL(value);
+		const isLoopback = url.hostname === "127.0.0.1" || url.hostname === "localhost" || url.hostname === "[::1]";
+		if (url.username || url.password) add(result, "server-url", `mcpServers.${name}.url must not contain credentials`);
+		if (url.protocol !== "https:" && !(url.protocol === "http:" && isLoopback)) add(result, "server-url", `mcpServers.${name}.url must use HTTPS, except loopback development URLs`);
+	} catch {
+		add(result, "server-url", `mcpServers.${name}.url is not a URL`);
+	}
+}
+/** Validate portable plugin files and the optional OpenAI install extension. */
+function validateMcpAppsPackage(rootPath) {
+	const root = resolve(rootPath);
+	const result = {
+		findings: [],
+		valid: false
+	};
+	try {
+		scanTree(root, root, result);
+	} catch {
+		add(result, "plugin-root", "Plugin root must be a readable directory");
+		return result;
+	}
+	const pluginPath = join(root, "plugin.json");
+	const mcpPath = join(root, "mcp.json");
+	if (!lstatExists(pluginPath)) add(result, "plugin-missing", "plugin.json is required at the plugin root");
+	if (!lstatExists(mcpPath)) add(result, "mcp-missing", "mcp.json is required at the plugin root");
+	const plugin = lstatExists(pluginPath) ? readJson$1(pluginPath, result) : void 0;
+	const mcp = lstatExists(mcpPath) ? readJson$1(mcpPath, result) : void 0;
+	if (plugin !== void 0 && !isObject(plugin)) add(result, "plugin-object", "plugin.json must contain an object");
+	if (mcp !== void 0 && !isObject(mcp)) add(result, "mcp-object", "mcp.json must contain an object");
+	if (plugin !== void 0 && !validatePluginSchema(plugin)) add(result, "plugin-format", "plugin.json violates the pinned Agent Plugins 1.0.0 schema");
+	if (mcp !== void 0 && !validateMcpSchema(mcp)) add(result, "mcp-format", "mcp.json violates the pinned Agent Plugins 1.0.0 schema");
+	if (isObject(plugin)) {
+		scanSecrets(plugin, "plugin.json", result);
+		if (plugin.$schema !== PLUGIN_SCHEMA) add(result, "plugin-schema", `plugin.json.$schema must be ${PLUGIN_SCHEMA}`);
+		if (plugin.extensions !== void 0 && !isObject(plugin.extensions)) add(result, "extensions", "plugin.json.extensions must be an object");
+		const openai = (isObject(plugin.extensions) ? plugin.extensions : void 0)?.["com.openai"];
+		if (openai !== void 0 && !isObject(openai)) add(result, "openai-extension", "extensions.com.openai must be an object");
+		if (isObject(openai)) {
+			if (openai.apps !== void 0) safeRelativePath(openai.apps, "extensions.com.openai.apps", root, result);
+			const ui = openai.interface;
+			if (ui !== void 0 && !isObject(ui)) add(result, "openai-interface", "extensions.com.openai.interface must be an object");
+			if (isObject(ui)) {
+				for (const key of ["composerIcon", "logo"]) if (ui[key] !== void 0) safeRelativePath(ui[key], `extensions.com.openai.interface.${key}`, root, result);
+				if (ui.screenshots !== void 0) if (!Array.isArray(ui.screenshots) || ui.screenshots.some((path) => typeof path !== "string")) add(result, "openai-screenshots", "interface.screenshots must be an array of paths");
+				else ui.screenshots.forEach((path, index) => {
+					safeRelativePath(path, `extensions.com.openai.interface.screenshots[${index}]`, root, result);
+				});
+			}
+		}
+	}
+	if (isObject(mcp)) {
+		scanSecrets(mcp, "mcp.json", result);
+		if (mcp.$schema !== MCP_SCHEMA) add(result, "mcp-schema", `mcp.json.$schema must be ${MCP_SCHEMA}`);
+		if (!isObject(mcp.mcpServers) || Object.keys(mcp.mcpServers).length === 0) add(result, "mcp-servers", "mcp.json requires a non-empty mcpServers object");
+		else for (const [name, server] of Object.entries(mcp.mcpServers)) {
+			if (!name.trim() || !isObject(server)) {
+				add(result, "mcp-server", `mcpServers.${name || "<empty>"} must be an object with a name`);
+				continue;
+			}
+			if (server.type !== "streamable-http") add(result, "mcp-transport", `mcpServers.${name}.type must be streamable-http`);
+			validateServerUrl(server.url, name, result);
+		}
+	}
+	result.valid = result.findings.length === 0;
+	return result;
+}
+function lstatExists(path) {
+	try {
+		return lstatSync(path).isFile();
+	} catch {
+		return false;
+	}
+}
+/**
+* Add the public, credential-free SMRT package route to a generated app.
+* A pre-existing scope route is an explicit consumer decision and must not be
+* silently replaced.
+*/
+function configureMcpAppsConsumerRegistry(appRoot) {
+	const npmrcPath = join(resolve(appRoot), ".npmrc");
+	let existing = "";
+	try {
+		const stat = lstatSync(npmrcPath);
+		if (stat.isSymbolicLink() || !stat.isFile()) throw new Error("Generated application .npmrc must be a regular file");
+		existing = readFileSync(npmrcPath, "utf8");
+	} catch (error) {
+		if (error.code !== "ENOENT") throw error;
+	}
+	const scopeLines = existing.split(/\r?\n/).filter((line) => /^\s*@happyvertical:registry(?:\s|=|$)/.test(line));
+	if (scopeLines.length > 0) {
+		for (const line of scopeLines) {
+			const match = /^\s*@happyvertical:registry\s*=\s*(\S+?)(?:\s+[;#].*)?\s*$/.exec(line);
+			if (!match || match[1] !== "https://npm.happyvertical.com/") throw new Error("Generated application already declares a different or malformed @happyvertical registry; refusing to replace it");
+		}
+		return;
+	}
+	writeFileSync(npmrcPath, `${existing}${existing && !existing.endsWith("\n") ? "\n" : ""}${CANONICAL_SCOPE_REGISTRY}\n`);
+}
+/** Copy the opt-in app route/resources and merge only its declared dependencies. */
+function addMcpAppsRuntime(sourceRoot, appRoot) {
+	const resolvedSource = resolve(sourceRoot);
+	const source = join(lstatSync(resolvedSource).isFile() ? dirname(resolvedSource) : resolvedSource, "mcp-apps-template");
+	const dependencies = JSON.parse(readFileSync(join(source, "package.dependencies.json"), "utf8"));
+	cpSync(join(source, "src"), join(resolve(appRoot), "src"), {
+		recursive: true,
+		force: false,
+		errorOnExist: true
+	});
+	const packagePath = join(resolve(appRoot), "package.json");
+	const packageJson = JSON.parse(readFileSync(packagePath, "utf8"));
+	packageJson.dependencies = {
+		...packageJson.dependencies,
+		...dependencies
+	};
+	writeFileSync(packagePath, `${JSON.stringify(packageJson, null, 2)}\n`);
+}
+function assertMcpAppsPluginName(name) {
+	if (!validatePluginSchema({
+		$schema: PLUGIN_SCHEMA,
+		name
+	})) throw new Error("Plugin name must satisfy Agent Plugins 1.0.0 (1–64 lowercase letters, digits, dots or hyphens; no repeated separators).");
+}
+/** Create the minimal local portable package. It intentionally has no .app.json: registered IDs are host-owned. */
+function scaffoldMcpAppsPackage(rootPath, name, version = "0.1.0") {
+	assertMcpAppsPluginName(name);
+	const root = resolve(rootPath);
+	mkdirSync(root, { recursive: true });
+	const pluginPath = join(root, "plugin.json");
+	const mcpPath = join(root, "mcp.json");
+	if (lstatExists(pluginPath) || lstatExists(mcpPath)) throw new Error("Refusing to overwrite existing MCP Apps package files");
+	writeFileSync(pluginPath, `${JSON.stringify({
+		$schema: PLUGIN_SCHEMA,
+		name,
+		version,
+		description: "SMRT MCP Apps package",
+		extensions: { "com.openai": { interface: {
+			displayName: name,
+			shortDescription: "SMRT MCP Apps package"
+		} } }
+	}, null, 2)}\n`);
+	writeFileSync(mcpPath, `${JSON.stringify({
+		$schema: MCP_SCHEMA,
+		mcpServers: { smrt: {
+			type: "streamable-http",
+			url: "http://127.0.0.1:3000/api/mcp"
+		} }
+	}, null, 2)}\n`);
+}
+var mcpAppsCommands = {
+	"mcp-apps scaffold": {
+		name: "mcp-apps scaffold",
+		description: "Create opt-in portable MCP Apps plugin metadata for a local SMRT app",
+		options: {
+			"output-dir": {
+				type: "string",
+				description: "Plugin directory (defaults to ./mcp-apps)"
+			},
+			name: {
+				type: "string",
+				description: "Portable plugin name",
+				default: "smrt-app"
+			},
+			version: {
+				type: "string",
+				description: "Portable plugin version",
+				default: "0.1.0"
+			}
+		},
+		handler: async (_args, options) => {
+			const root = typeof options["output-dir"] === "string" ? options["output-dir"] : "./mcp-apps";
+			scaffoldMcpAppsPackage(root, typeof options.name === "string" ? options.name : "smrt-app", typeof options.version === "string" ? options.version : "0.1.0");
+			console.log(`Created portable MCP Apps metadata in ${root}.`);
+			console.log("Mount and authorize the native v2 /api/mcp endpoint before changing the loopback URL.");
+		}
+	},
+	"mcp-apps validate": {
+		name: "mcp-apps validate",
+		description: "Fail closed when portable MCP Apps package metadata is unsafe or incomplete",
+		options: { "output-dir": {
+			type: "string",
+			description: "Plugin directory (defaults to ./mcp-apps)"
+		} },
+		handler: async (_args, options) => {
+			const root = typeof options["output-dir"] === "string" ? options["output-dir"] : "./mcp-apps";
+			const result = validateMcpAppsPackage(root);
+			for (const finding of result.findings) console.error(`${finding.code}: ${finding.message}`);
+			if (!result.valid) throw new Error(`MCP Apps package validation failed with ${result.findings.length} finding(s)`);
+			console.log(`MCP Apps package at ${root} is valid.`);
+		}
+	}
+};
+//#endregion
 //#region src/commands/gnode.ts
 /**
+* Gnode CLI Commands
+*
+* Commands for creating and managing gnodes (federated local knowledge bases)
+*/
+var SCOPED_PACKAGE_NAME = /^@[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*$/;
+function projectIdentity(name, outputDir) {
+	const packagePath = join(outputDir, "package.json");
+	if (existsSync(packagePath)) {
+		const existing = JSON.parse(readFileSync(packagePath, "utf8"));
+		if (typeof existing.name !== "string" || !SCOPED_PACKAGE_NAME.test(existing.name)) throw new Error("Generated applications require a scoped package identity (for example @smrt-app/my-app); rename the existing project before generating into it");
+		return existing.name;
+	}
+	if (SCOPED_PACKAGE_NAME.test(name)) return name;
+	const slug = name.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+	if (!slug) throw new Error("MCP Apps project name must contain a package slug");
+	return `@smrt-app/${slug}`;
+}
+function mcpAppsPluginName(packageName) {
+	return packageName.split("/").at(-1) ?? packageName;
+}
+/**
 * Gnode commands for CLI
 */
 var gnodeCommands = {
@@ -6137,6 +6582,10 @@ var gnodeCommands = {
 				type: "string",
 				description: "IANA timezone (e.g., \"America/Edmonton\")",
 				default: "America/Edmonton"
+			},
+			"mcp-apps": {
+				type: "boolean",
+				description: "Add opt-in portable MCP Apps plugin metadata under mcp-apps/"
 			}
 		},
 		handler: async (args, options) => {
@@ -6144,26 +6593,38 @@ var gnodeCommands = {
 			if (!name) throw new Error("Project name is required: smrt gnode create <name>");
 			const outputDir = options.outputDir || `./${name}`;
 			const templateName = options.template || "sveltekit";
+			const mcpApps = options.mcpApps || options["mcp-apps"];
+			const projectName = projectIdentity(name, outputDir);
+			if (mcpApps) assertMcpAppsPluginName(mcpAppsPluginName(projectName));
 			const siteOptions = options.location || options.lat || options.lon ? {
 				location: options.location,
 				latitude: options.lat ? Number(options.lat) : void 0,
 				longitude: options.lon ? Number(options.lon) : void 0,
 				timezone: options.timezone
 			} : void 0;
+			let gitConfig;
 			try {
 				console.log(`🔍 Resolving template: ${templateName}...`);
 				const source = await resolveTemplate(templateName);
 				console.log(`✓ Found template: ${source.type}:${source.location}\n`);
 				const config = await loadTemplate(source);
+				if (source.type === "git") gitConfig = config;
 				await generate(source, config, {
-					name,
+					name: projectName,
 					template: templateName,
 					outputDir,
 					site: siteOptions
 				});
-				if (source.type === "git") await cleanupGitTemplate(config);
+				if (mcpApps || config.name === "sveltekit") configureMcpAppsConsumerRegistry(outputDir);
+				if (mcpApps) {
+					addMcpAppsRuntime(source.type === "git" ? getGitTemplateDir(config) : source.resolved, outputDir);
+					scaffoldMcpAppsPackage(`${outputDir}/mcp-apps`, mcpAppsPluginName(projectName));
+					console.log("✓ Added MCP Apps metadata and the canonical @happyvertical package registry. Configure the authorized v2 MCP endpoint before deployment.");
+				}
 			} catch (error) {
 				throw new Error(`Failed to create gnode: ${error instanceof Error ? error.message : "Unknown error"}`, { cause: error });
+			} finally {
+				if (gitConfig) await cleanupGitTemplate(gitConfig);
 			}
 		}
 	},
@@ -6948,7 +7409,7 @@ var dbMaterializeTenantHierarchyCommand = {
 			if (!config.database?.url || config.database.url === ":memory:") throw new Error("Database configuration required for db:materialize-tenant-hierarchy. Configure database.url in smrt.config.ts (or DATABASE_URL).");
 			const dbType = config.database.type || "sqlite";
 			const { getDatabase } = await import("@happyvertical/sql");
-			const { materializeTenantHierarchy, TenantHierarchyMaterializationError } = await import("./dist-iMaSv6C_.js");
+			const { materializeTenantHierarchy, TenantHierarchyMaterializationError } = await import("./dist-DtTkpUee.js");
 			db = await getDatabase({
 				type: dbType,
 				url: config.database.url
@@ -7157,7 +7618,7 @@ var dbMigrateLedgerAccountsCommand = {
 			if (dbType !== "postgres") throw new Error("db:migrate-ledger-accounts currently supports PostgreSQL only; no changes were made. See the smrt-ledgers README for SQLite.");
 			await autoDiscoverAndLoad();
 			const { getDatabase } = await import("@happyvertical/sql");
-			const { migrateLedgerAccountsTable, planLedgerAccountsTableMove } = await import("./dist-C8sNOzr2.js");
+			const { migrateLedgerAccountsTable, planLedgerAccountsTableMove } = await import("./dist-CLA60jwS.js");
 			db = await getDatabase({
 				type: dbType,
 				url: config.database.url
@@ -8225,6 +8686,139 @@ async function columnIsUuid(db, table, column) {
 	return rows[0]?.data_type === "uuid";
 }
 //#endregion
+//#region src/commands/db-qualified-names.ts
+/**
+* Stored references to deprecated qualified names (#3338).
+*
+* `smrt doctor --db` reports how many rows still store a name a class
+* declared in `@smrt({ previousQualifiedNames })` — the signal that an alias
+* can (or cannot yet) be removed. `smrt db:migrate-qualified-names` is the
+* opt-in, idempotent cleanup; nothing rewrites stored names automatically.
+*/
+async function connect() {
+	const { getPackageConfig } = await import("@happyvertical/smrt-config");
+	const { DEFAULT_CLI_CONFIG } = await import("./config-hqNo4lzH.js").then((n) => n.n);
+	const config = getPackageConfig("cli", DEFAULT_CLI_CONFIG);
+	if (!config.database?.url || config.database.url === ":memory:") throw new Error("No persistent database is configured. Set `database.url` in smrt.config.ts (or DATABASE_URL).");
+	const dbType = config.database.type || "sqlite";
+	const { getDatabase } = await import("@happyvertical/sql");
+	return {
+		db: await getDatabase({
+			type: dbType,
+			url: config.database.url
+		}),
+		dbType,
+		url: config.database.url
+	};
+}
+/**
+* Count stored deprecated qualified names in the configured database.
+* Never throws for an operational problem.
+*/
+async function runLegacyQualifiedNameReport(options = {}) {
+	let db;
+	try {
+		if (options.discover ?? true) await autoDiscoverAndLoad();
+		const connection = await connect();
+		db = connection.db;
+		return {
+			report: await countLegacyQualifiedNameReferences(db, { engineHint: connection.dbType }),
+			error: null
+		};
+	} catch (error) {
+		return {
+			report: null,
+			error: redactConnectionStringsInText(error instanceof Error ? error.message : String(error))
+		};
+	} finally {
+		await closeDatabaseConnection(db);
+	}
+}
+/**
+* Render a legacy-name report as the lines `smrt doctor --db` and
+* `smrt db:migrate-qualified-names` print.
+*
+* A zero count is a removal signal only when it is global and complete: a
+* tenant-scoped count (`tenantId`) or one that skipped untenanted tables
+* never says the aliases are removable. Stored rows are also only half the
+* picture, so every report reminds the operator that source still naming an
+* old name must move first.
+*/
+function formatLegacyQualifiedNameReport(report, options = {}) {
+	if (report.aliases.length === 0) return ["   No class declares previousQualifiedNames."];
+	const scope = options.tenantId !== void 0 ? ` for tenant ${options.tenantId}` : "";
+	const lines = [`   Declared aliases: ${report.aliases.length}`, ...report.aliases.map(({ alias, current }) => `     - ${alias} → ${current}`)];
+	if (report.total > 0) {
+		lines.push(`   ⚠️  ${report.total} stored reference(s)${scope} still use a deprecated name:`);
+		for (const reference of report.references) lines.push(`     - ${reference.table}.${reference.column} = ${reference.alias}: ${reference.count} row(s)`);
+		lines.push("   They keep resolving. Rewrite them early with `smrt db:migrate-qualified-names` (opt-in); keep the aliases until this count is zero.");
+	} else if (options.tenantId !== void 0) lines.push(`   ✅ No counted row${scope} uses a deprecated name. This is a tenant-scoped count, not a removal signal: other tenants and untenanted tables were not counted. Run without --tenant (or \`smrt doctor --db\`) before deciding to remove an alias.`);
+	else if (report.untenantedTables.length > 0) lines.push("   ✅ No counted row uses a deprecated name, but some tables were skipped (below), so this is not a removal signal.");
+	else lines.push("   ✅ No stored row in this database uses a deprecated name. The aliases may be removed in a breaking release once every deployment reports zero and no source still names them.");
+	if (report.untenantedTables.length > 0) lines.push(`   Skipped (no tenant column, not counted): ${report.untenantedTables.join(", ")}`);
+	if (report.missingTables.length > 0) lines.push(`   (not migrated in this database: ${report.missingTables.join(", ")})`);
+	lines.push("   Before removing an alias, also update source still naming an old qualified name (@crossPackageRef / relationship targets, playbook step models) to the current name.");
+	return lines;
+}
+/** `smrt db:migrate-qualified-names` — the opt-in rewrite. */
+var dbMigrateQualifiedNamesCommand = {
+	name: "db:migrate-qualified-names",
+	description: "Rewrite stored deprecated qualified names (declared via @smrt({ previousQualifiedNames })) to current names. Opt-in and idempotent (#3338).",
+	aliases: ["migrate-qualified-names"],
+	args: [],
+	options: {
+		"dry-run": {
+			type: "boolean",
+			description: "Report the rows that would be rewritten without writing.",
+			default: false
+		},
+		tenant: {
+			type: "string",
+			description: "Rewrite only this tenant's rows (tables without a tenant column are skipped)."
+		},
+		force: {
+			type: "boolean",
+			description: "Run again even if this alias set was already recorded.",
+			default: false
+		}
+	},
+	handler: async (_args, options) => {
+		let db;
+		try {
+			await autoDiscoverAndLoad();
+			const connection = await connect();
+			db = connection.db;
+			console.log("\n🏷️  Deprecated qualified-name backfill\n");
+			console.log(`✓ Connected to ${formatDatabaseDisplayUrl(connection.dbType, connection.url)}\n`);
+			const result = await backfillLegacyQualifiedNames(db, {
+				engineHint: connection.dbType,
+				dryRun: options["dry-run"] === true,
+				force: options.force === true,
+				...options.tenant ? { tenantId: options.tenant } : {}
+			});
+			for (const line of formatLegacyQualifiedNameReport(result.before, { ...options.tenant ? { tenantId: options.tenant } : {} })) console.log(line);
+			console.log();
+			if (result.dryRun) {
+				console.log("DRY RUN: no changes made.\n");
+				return;
+			}
+			if (!result.ran) {
+				console.log(result.before.aliases.length === 0 ? "Nothing to do.\n" : `Already applied (${result.backfillName}); pass --force to run again.\n`);
+				return;
+			}
+			for (const reference of result.rewritten) console.log(`✓ ${reference.table}.${reference.column}: ${reference.count} row(s) ${reference.alias} → ${reference.current}`);
+			for (const reference of result.skippedDuplicates) console.log(`⚠️  ${reference.table}.${reference.column}: ${reference.count} row(s) kept as ${reference.alias} — a row with the same identity already uses ${reference.current}. Resolve the duplicates, then re-run.`);
+			if (result.skippedDuplicates.length > 0) process.exitCode = 1;
+			console.log(result.recorded ? `\n✓ Recorded ${result.backfillName}.\n` : "\nNot recorded: references remain.\n");
+		} catch (error) {
+			console.error(`\n❌ Qualified-name backfill failed: ${redactConnectionStringsInText(error instanceof Error ? error.message : String(error))}\n`);
+			process.exitCode = 1;
+		} finally {
+			await closeDatabaseConnection(db);
+		}
+	}
+};
+//#endregion
 //#region src/commands/dev-knowledge.ts
 /**
 * dev:knowledge-* commands
@@ -9418,6 +10012,7 @@ function renderAgentSurfaceReport(report) {
 * Utility commands for CLI
 */
 var utilityCommands = {
+	...mcpAppsCommands,
 	introspect: {
 		name: "introspect",
 		description: "Analyze project and discover SMRT objects",
@@ -9876,7 +10471,7 @@ export default testManifest;
 				}
 			}
 			try {
-				const { resolveDataPath, discoverJsonFiles, JsonDatabaseValidator, displayValidationResults } = await import("./json-validator-oEN7eUI3.js");
+				const { resolveDataPath, discoverJsonFiles, JsonDatabaseValidator, displayValidationResults } = await import("./json-validator-BiAdsE1O.js");
 				const dataPath = await resolveDataPath(options.data);
 				if (!dataPath) {
 					console.error("\n❌ Could not find data directory");
@@ -9998,6 +10593,11 @@ export default testManifest;
 				type: "string",
 				description: "Confirm that legacy PostgreSQL timestamp-without-time-zone values are UTC wall times before converting them to timestamptz. Exact value required: UTC; omitted by default."
 			},
+			"empty-text-as-null": {
+				type: "boolean",
+				description: "Store empty or whitespace-only text as NULL when converging a nullable legacy text column to a typed column (timestamp, JSON, integer). Any other value that does not convert still blocks, and NOT NULL columns are never changed. Off by default.",
+				default: false
+			},
 			force: {
 				type: "boolean",
 				description: "Force re-apply even if already applied (skip checksum validation)",
@@ -10023,6 +10623,11 @@ export default testManifest;
 				description: "Drop orphan indexes (in DB but not in manifest, excluding *_pkey/*_key implicit-from-constraint indexes). Off by default.",
 				default: false
 			},
+			"drop-legacy-natural-key": {
+				type: "boolean",
+				description: "Drop the legacy global (slug, context) unique index a tenant-led natural key superseded on a table that is tenant-owned by its tenantId field. Off by default: db:migrate builds the tenant-led index beside it so code still on the previous release keeps upserting. Pass this once every instance runs the release that upserts on the tenant-led key.",
+				default: false
+			},
 			"drop-columns": {
 				type: "boolean",
 				description: "DESTRUCTIVE: drop orphan columns (in DB but not in manifest). Off by default; orphans are always reported.",
@@ -10171,8 +10776,10 @@ export default testManifest;
 				const diff = await new SchemaComparer(db, {
 					includeDroppedIndexes: Boolean(options["drop-indexes"]),
 					includeDroppedColumns: Boolean(options["drop-columns"]),
+					dropLegacyNaturalKey: Boolean(options["drop-legacy-natural-key"]),
 					relaxColumns: Boolean(options["relax-columns"]),
-					postgresTimestampMigration
+					postgresTimestampMigration,
+					emptyTextAsNull: Boolean(options["empty-text-as-null"])
 				}).compare(manifestSchemas);
 				const engine = tracker.getEngine();
 				const tablePlan = planForeignKeyCreation(diff.added_tables, engine);
@@ -10255,6 +10862,12 @@ export default testManifest;
 					pendingOrphanDispositions.length = 0;
 					pendingOrphanDispositions.push(...stillPending);
 				}
+				const destructiveForeignKeys = migrations.filter((migration) => migration.type === "add_foreign_key" && migration.advisory?.severity === "warning" && Boolean(migration.sql || migration.sqlStatements?.length));
+				if (destructiveForeignKeys.length > 0) {
+					console.log(`\n⚠️  ${destructiveForeignKeys.length} foreign-key change(s) make deletes DESTRUCTIVE:`);
+					for (const migration of destructiveForeignKeys) console.log(`   ${migration.advisory?.message}`);
+					console.log();
+				}
 				const preForeignKeyMigrations = migrations.filter((migration) => migration.phase === "pre_foreign_key");
 				const remainingMigrations = migrations.filter((migration) => migration.phase !== "pre_foreign_key");
 				assertForceMigrationTargetsExist(forceSelection.forceMigrations, [
@@ -10407,7 +11020,7 @@ export default testManifest;
 							actionDesc = `Dropped column ${migration.tableName}.${migration.columnName}`;
 						} else if (migration.type === "type_upgrade" && migration.column) {
 							migrationSql = migration.sql || "";
-							actionDesc = `Upgraded column ${migration.tableName}.${migration.column.name} from ${migration.mismatch?.actual} to ${migration.mismatch?.expected}`;
+							actionDesc = `Upgraded column ${migration.tableName}.${migration.column.name} from ${migration.mismatch?.actual} to ${migration.mismatch?.expected}${migration.note ? ` (${migration.note})` : ""}`;
 						} else if (migration.type === "add_index" && migration.index) {
 							migrationSql = migration.sql || "";
 							actionDesc = `Created index ${migration.index.name} on ${migration.tableName}`;
@@ -10416,7 +11029,7 @@ export default testManifest;
 							actionDesc = `Dropped index ${migration.indexName} on ${migration.tableName}`;
 						} else if (migration.type === "add_foreign_key") {
 							migrationSql = migration.sql || "";
-							actionDesc = `Added foreign-key constraint on ${migration.tableName}`;
+							actionDesc = migration.note ? `Replaced foreign-key constraint on ${migration.tableName} (${migration.note})` : `Added foreign-key constraint on ${migration.tableName}`;
 						} else if (migration.type === "drop_foreign_key") {
 							migrationSql = migration.sql || "";
 							actionDesc = `Dropped foreign-key constraint on ${migration.tableName}`;
@@ -10814,6 +11427,11 @@ export default testManifest;
 				check("SMRT objects discovered", false, void 0, "Could not discover manifests");
 			}
 			const runtimeCheck = await runRuntimeCheckSafely(cwd);
+			const mcpAppsPath = resolve(cwd, "mcp-apps");
+			if (existsSync(mcpAppsPath)) {
+				const mcpApps = validateMcpAppsPackage(mcpAppsPath);
+				check("Portable MCP Apps package", mcpApps.valid, mcpApps.findings.map((finding) => `${finding.code}: ${finding.message}`).join("; "));
+			}
 			const projectManifestPath = resolve(cwd, ".smrt", "manifest.json");
 			const registerPath = resolve(cwd, ".smrt", "register.js");
 			if (existsSync(projectManifestPath)) try {
@@ -10879,6 +11497,15 @@ export default testManifest;
 				for (const line of formatPermissionsOutcome(permissions)) console.log(line);
 				if (!permissions.skipped) check("PostgreSQL role permissions", !permissions.error && permissions.plan?.diagnostics.length === 0, permissions.error ?? "PostgreSQL role permissions differ from the configured contract");
 				console.log();
+				console.log("🏷️  Deprecated Qualified Names\n");
+				const legacyNames = await runLegacyQualifiedNameReport({ discover: false });
+				if (!legacyNames.report) check("Deprecated qualified-name references", false, legacyNames.error ?? "Could not count stored references");
+				else {
+					for (const line of formatLegacyQualifiedNameReport(legacyNames.report)) console.log(line);
+					if (legacyNames.report.total > 0) warnings.push(`deprecated qualified names: ${legacyNames.report.total} stored reference(s)`);
+					else passed.push("Deprecated qualified-name references");
+				}
+				console.log();
 			}
 			console.log("━".repeat(50));
 			console.log(`\n📊 Summary\n`);
@@ -10916,6 +11543,7 @@ export default testManifest;
 	"db:migrate-null-equal-indexes": dbMigrateNullEqualIndexesCommand,
 	"db:migrate-agent-schedule-slugs": dbMigrateAgentScheduleSlugsCommand,
 	"db:migrate-ledger-accounts": dbMigrateLedgerAccountsCommand,
+	"db:migrate-qualified-names": dbMigrateQualifiedNamesCommand,
 	"db:materialize-tenant-hierarchy": dbMaterializeTenantHierarchyCommand,
 	"db:drop-framework-base-tables": dbDropFrameworkBaseTablesCommand,
 	"db:orphans": dbOrphansCommand,