@vantageos/vantage-registry-mcp 1.2.0 → 1.4.0

package/server.ts

@@ -13,16 +13,17 @@
  *   upsert_template, list_templates, get_template
  *   upsert_runbook, get_runbook, list_runbooks, list_runbooks_by_category, list_runbooks_by_team, delete_runbook
  *   link_runbook_template, unlink_runbook_template, list_templates_for_runbook, list_runbooks_for_template
+ *   register_component, list_components, get_component, search_components, update_component, delete_component
  *   get_stats
  *
- * Orchestrator: Omega — VantageOS Team | 2026-05-19
+ * Orchestrator: Omega — VantageOS Team | 2026-06-01
  */
 
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { ConvexHttpClient } from "convex/browser";
-import { readFileSync } from "fs";
-import { resolve } from "path";
 import { z } from "zod";
 import { api } from "../convex/_generated/api.js";
 
@@ -80,7 +81,9 @@ const hookStatusSchema = z
 
 const sourceSchema = z
 	.enum(["internal", "external", "plugin"])
-	.describe("Component source — internal (our code), external (third-party), plugin (from plugin)");
+	.describe(
+		"Component source — internal (our code), external (third-party), plugin (from plugin)",
+	);
 
 const pluginSourceSchema = z
 	.enum(["internal", "external"])
@@ -127,7 +130,7 @@ const convex = new ConvexHttpClient(convexUrl);
 
 const server = new McpServer({
 	name: "vantage-registry",
-	version: "1.2.0",
+	version: "1.4.0",
 });
 
 // ═══════════════════════════════════════════════════════════════════════════════
@@ -143,12 +146,17 @@ server.tool(
 		agentCount: z.number().int().describe("Number of agents in this team"),
 		skillCount: z.number().int().describe("Number of skills in this team"),
 		status: teamStatusSchema,
-		project: z.string().optional().describe("Associated project — e.g. 'vantage-starter'"),
+		project: z
+			.string()
+			.optional()
+			.describe("Associated project — e.g. 'vantage-starter'"),
 	},
 	async (args) => {
 		const id = await convex.mutation(api.teams.upsert, args);
 		return {
-			content: [{ type: "text", text: JSON.stringify({ id, ...args }, null, 2) }],
+			content: [
+				{ type: "text", text: JSON.stringify({ id, ...args }, null, 2) },
+			],
 		};
 	},
 );
@@ -157,7 +165,9 @@ server.tool(
 	"list_teams",
 	"List all teams in VantageRegistry. Optionally filter by status (active, planned, deprecated).",
 	{
-		status: teamStatusSchema.optional().describe("Filter by status — omit to list all"),
+		status: teamStatusSchema
+			.optional()
+			.describe("Filter by status — omit to list all"),
 	},
 	async ({ status }) => {
 		const results = await convex.query(api.teams.list, { status });
@@ -189,7 +199,9 @@ server.tool(
 	"upsert_agent",
 	"Create or update an agent in VantageRegistry. Upserts by name+team — if an agent with the same name and team exists, it is updated.",
 	{
-		name: z.string().describe("Agent name — e.g. 'copywriter', 'strategy-researcher'"),
+		name: z
+			.string()
+			.describe("Agent name — e.g. 'copywriter', 'strategy-researcher'"),
 		team: z.string().describe("Team this agent belongs to"),
 		description: z.string().describe("What this agent does"),
 		content: z.string().describe("Full agent definition content (markdown)"),
@@ -200,9 +212,15 @@ server.tool(
 		source: sourceSchema,
 		pricing: z.enum(["free", "paid"]).optional().describe("Pricing tier"),
 		price: z.number().optional().describe("Price in EUR (if paid)"),
-		license: z.string().optional().describe("License — e.g. 'MIT', 'proprietary'"),
+		license: z
+			.string()
+			.optional()
+			.describe("License — e.g. 'MIT', 'proprietary'"),
 		publisherId: z.string().optional().describe("Publisher identifier"),
-		categories: z.array(z.string()).optional().describe("Categories beyond team name"),
+		categories: z
+			.array(z.string())
+			.optional()
+			.describe("Categories beyond team name"),
 	},
 	async (args) => {
 		const id = await convex.mutation(api.agents.upsert, args);
@@ -210,7 +228,11 @@ server.tool(
 			content: [
 				{
 					type: "text",
-					text: JSON.stringify({ id, name: args.name, team: args.team }, null, 2),
+					text: JSON.stringify(
+						{ id, name: args.name, team: args.team },
+						null,
+						2,
+					),
 				},
 			],
 		};
@@ -219,13 +241,35 @@ server.tool(
 
 server.tool(
 	"list_agents",
-	"List all agents in VantageRegistry. Optionally filter by status.",
+	"List all agents in VantageRegistry. Optionally filter by status, team, or category. " +
+		"fields='lite' returns compact {_id, name, team, status}. fields='full' returns the complete document including content.",
 	{
-		status: agentStatusSchema.optional().describe("Filter by status — omit to list all"),
-		summary: z.boolean().optional().describe("Return summary only (no content). Default: true"),
+		status: agentStatusSchema
+			.optional()
+			.describe("Filter by status — omit to list all"),
+		team: z.string().optional().describe("Filter by team — e.g. 'dev', 'core'"),
+		category: z.string().optional().describe("Filter by category"),
+		fields: z
+			.enum(["lite", "full"])
+			.optional()
+			.describe(
+				"Projection: 'lite' (compact) or 'full' (complete document). Omit to use legacy summary behaviour.",
+			),
+		summary: z
+			.boolean()
+			.optional()
+			.describe(
+				"Return summary only (no content). Default: true — legacy, prefer fields='lite'",
+			),
 	},
-	async ({ status, summary }) => {
-		const results = await convex.query(api.agents.list, { status, summary });
+	async ({ status, team, category, fields, summary }) => {
+		const results = await convex.query(api.agents.list, {
+			status,
+			team,
+			category,
+			fields,
+			summary,
+		});
 		return {
 			content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
 		};
@@ -237,10 +281,16 @@ server.tool(
 	"List all agents belonging to a specific team.",
 	{
 		team: z.string().describe("Team name to filter by"),
-		summary: z.boolean().optional().describe("Return summary only (no content). Default: true"),
+		summary: z
+			.boolean()
+			.optional()
+			.describe("Return summary only (no content). Default: true"),
 	},
 	async ({ team, summary }) => {
-		const results = await convex.query(api.agents.listByTeam, { team, summary });
+		const results = await convex.query(api.agents.listByTeam, {
+			team,
+			summary,
+		});
 		return {
 			content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
 		};
@@ -269,10 +319,14 @@ server.tool(
 	"upsert_skill",
 	"Create or update a skill in VantageRegistry. Upserts by name+team — if a skill with the same name and team exists, it is updated.",
 	{
-		name: z.string().describe("Skill name — e.g. 'social-post', 'competitor-watch'"),
+		name: z
+			.string()
+			.describe("Skill name — e.g. 'social-post', 'competitor-watch'"),
 		team: z.string().describe("Team this skill belongs to"),
 		category: skillCategorySchema,
-		description: z.string().describe("What this skill does — use pushy trigger descriptions"),
+		description: z
+			.string()
+			.describe("What this skill does — use pushy trigger descriptions"),
 		content: z.string().describe("Full SKILL.md content"),
 		filePath: z.string().describe("File path relative to project root"),
 		lineCount: z.number().int().describe("Number of lines in the skill file"),
@@ -281,9 +335,15 @@ server.tool(
 		source: sourceSchema,
 		pricing: z.enum(["free", "paid"]).optional().describe("Pricing tier"),
 		price: z.number().optional().describe("Price in EUR (if paid)"),
-		license: z.string().optional().describe("License — e.g. 'MIT', 'proprietary'"),
+		license: z
+			.string()
+			.optional()
+			.describe("License — e.g. 'MIT', 'proprietary'"),
 		publisherId: z.string().optional().describe("Publisher identifier"),
-		categories: z.array(z.string()).optional().describe("Categories beyond team name"),
+		categories: z
+			.array(z.string())
+			.optional()
+			.describe("Categories beyond team name"),
 	},
 	async (args) => {
 		const id = await convex.mutation(api.skills.upsert, args);
@@ -291,7 +351,11 @@ server.tool(
 			content: [
 				{
 					type: "text",
-					text: JSON.stringify({ id, name: args.name, team: args.team, category: args.category }, null, 2),
+					text: JSON.stringify(
+						{ id, name: args.name, team: args.team, category: args.category },
+						null,
+						2,
+					),
 				},
 			],
 		};
@@ -300,13 +364,39 @@ server.tool(
 
 server.tool(
 	"list_skills",
-	"List all skills in VantageRegistry. Optionally filter by status.",
+	"List all skills in VantageRegistry. Optionally filter by status, team, or category. " +
+		"fields='lite' returns compact {_id, name, team, category, status}. fields='full' returns the complete document including content.",
 	{
-		status: skillStatusSchema.optional().describe("Filter by status — omit to list all"),
-		summary: z.boolean().optional().describe("Return summary only (no content). Default: true"),
+		status: skillStatusSchema
+			.optional()
+			.describe("Filter by status — omit to list all"),
+		team: z.string().optional().describe("Filter by team — e.g. 'dev', 'core'"),
+		category: skillCategorySchema
+			.optional()
+			.describe(
+				"Filter by category: capability, composite, playbook, root, or external",
+			),
+		fields: z
+			.enum(["lite", "full"])
+			.optional()
+			.describe(
+				"Projection: 'lite' (compact) or 'full' (complete document). Omit to use legacy summary behaviour.",
+			),
+		summary: z
+			.boolean()
+			.optional()
+			.describe(
+				"Return summary only (no content). Default: true — legacy, prefer fields='lite'",
+			),
 	},
-	async ({ status, summary }) => {
-		const results = await convex.query(api.skills.list, { status, summary });
+	async ({ status, team, category, fields, summary }) => {
+		const results = await convex.query(api.skills.list, {
+			status,
+			team,
+			category,
+			fields,
+			summary,
+		});
 		return {
 			content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
 		};
@@ -318,10 +408,16 @@ server.tool(
 	"List all skills belonging to a specific team.",
 	{
 		team: z.string().describe("Team name to filter by"),
-		summary: z.boolean().optional().describe("Return summary only (no content). Default: true"),
+		summary: z
+			.boolean()
+			.optional()
+			.describe("Return summary only (no content). Default: true"),
 	},
 	async ({ team, summary }) => {
-		const results = await convex.query(api.skills.listByTeam, { team, summary });
+		const results = await convex.query(api.skills.listByTeam, {
+			team,
+			summary,
+		});
 		return {
 			content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
 		};
@@ -333,10 +429,16 @@ server.tool(
 	"List all skills of a specific category (capability, composite, playbook, root, external).",
 	{
 		category: skillCategorySchema,
-		summary: z.boolean().optional().describe("Return summary only (no content). Default: true"),
+		summary: z
+			.boolean()
+			.optional()
+			.describe("Return summary only (no content). Default: true"),
 	},
 	async ({ category, summary }) => {
-		const results = await convex.query(api.skills.listByCategory, { category, summary });
+		const results = await convex.query(api.skills.listByCategory, {
+			category,
+			summary,
+		});
 		return {
 			content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
 		};
@@ -367,10 +469,14 @@ server.tool(
 		"Returns content, sha256 hash, semver version, and last sync timestamp. " +
 		"Returns null fields if the skill has not been hosted in VR yet.",
 	{
-		name: z.string().describe("Skill slug — e.g. 'check-messages', 'blog-writer'"),
+		name: z
+			.string()
+			.describe("Skill slug — e.g. 'check-messages', 'blog-writer'"),
 	},
 	async ({ name }) => {
-		const result = await convex.query(api.skillContentDb.getSkillContent, { name });
+		const result = await convex.query(api.skillContentDb.getSkillContent, {
+			name,
+		});
 		return {
 			content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
 		};
@@ -389,14 +495,23 @@ server.tool(
 	{
 		name: z.string().describe("Skill slug — e.g. 'check-messages'"),
 		content: z.string().describe("Full SKILL.md body (frontmatter + markdown)"),
-		createIfMissing: z.boolean().optional().default(false).describe("Auto-create a placeholder skill row if it does not exist (default: false)"),
+		createIfMissing: z
+			.boolean()
+			.optional()
+			.default(false)
+			.describe(
+				"Auto-create a placeholder skill row if it does not exist (default: false)",
+			),
 	},
 	async ({ name, content, createIfMissing }) => {
-		const result = await convex.mutation(api.skillContentDb.upsertSkillContent, {
-			name,
-			content,
-			createIfMissing,
-		});
+		const result = await convex.mutation(
+			api.skillContentDb.upsertSkillContent,
+			{
+				name,
+				content,
+				createIfMissing,
+			},
+		);
 		return {
 			content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
 		};
@@ -410,11 +525,20 @@ server.tool(
 		"canonical hash + stored filePath so the caller can compute disk SHA256 and compare. " +
 		"scope='all' (default) returns every skill. name=<slug> filters to a single skill.",
 	{
-		name: z.string().optional().describe("Skill slug — filter to a single skill"),
-		scope: z.string().optional().describe("'all' to return every skill (default when name is omitted)"),
+		name: z
+			.string()
+			.optional()
+			.describe("Skill slug — filter to a single skill"),
+		scope: z
+			.string()
+			.optional()
+			.describe("'all' to return every skill (default when name is omitted)"),
 	},
 	async ({ name, scope }) => {
-		const result = await convex.query(api.skillContentDb.detectSkillDrift, { name, scope });
+		const result = await convex.query(api.skillContentDb.detectSkillDrift, {
+			name,
+			scope,
+		});
 		return {
 			content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
 		};
@@ -431,10 +555,14 @@ server.tool(
 		"Returns content, sha256 hash, semver version, and last sync timestamp. " +
 		"Returns null fields if the agent has not been hosted in VR yet.",
 	{
-		name: z.string().describe("Agent slug — e.g. 'dev-convex-expert', 'dev-senior-dev'"),
+		name: z
+			.string()
+			.describe("Agent slug — e.g. 'dev-convex-expert', 'dev-senior-dev'"),
 	},
 	async ({ name }) => {
-		const result = await convex.query(api.agentContentDb.getAgentContent, { name });
+		const result = await convex.query(api.agentContentDb.getAgentContent, {
+			name,
+		});
 		return {
 			content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
 		};
@@ -451,15 +579,26 @@ server.tool(
 		"Throws if the agent does not exist and createIfMissing is not set.",
 	{
 		name: z.string().describe("Agent slug — e.g. 'dev-convex-expert'"),
-		content: z.string().describe("Full agent content body (AGENT.md or similar)"),
-		createIfMissing: z.boolean().optional().default(false).describe("Auto-create a placeholder agent row if it does not exist (default: false)"),
+		content: z
+			.string()
+			.describe("Full agent content body (AGENT.md or similar)"),
+		createIfMissing: z
+			.boolean()
+			.optional()
+			.default(false)
+			.describe(
+				"Auto-create a placeholder agent row if it does not exist (default: false)",
+			),
 	},
 	async ({ name, content, createIfMissing }) => {
-		const result = await convex.mutation(api.agentContentDb.upsertAgentContent, {
-			name,
-			content,
-			createIfMissing,
-		});
+		const result = await convex.mutation(
+			api.agentContentDb.upsertAgentContent,
+			{
+				name,
+				content,
+				createIfMissing,
+			},
+		);
 		return {
 			content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
 		};
@@ -473,11 +612,20 @@ server.tool(
 		"canonical hash + stored filePath so the caller can compute disk SHA256 and compare. " +
 		"scope='all' (default) returns every agent. name=<slug> filters to a single agent.",
 	{
-		name: z.string().optional().describe("Agent slug — filter to a single agent"),
-		scope: z.string().optional().describe("'all' to return every agent (default when name is omitted)"),
+		name: z
+			.string()
+			.optional()
+			.describe("Agent slug — filter to a single agent"),
+		scope: z
+			.string()
+			.optional()
+			.describe("'all' to return every agent (default when name is omitted)"),
 	},
 	async ({ name, scope }) => {
-		const result = await convex.query(api.agentContentDb.detectAgentDrift, { name, scope });
+		const result = await convex.query(api.agentContentDb.detectAgentDrift, {
+			name,
+			scope,
+		});
 		return {
 			content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
 		};
@@ -494,10 +642,14 @@ server.tool(
 		"Returns content, sha256 hash, semver version, and last sync timestamp. " +
 		"Returns null fields if the plugin has not been hosted in VR yet.",
 	{
-		name: z.string().describe("Plugin slug — e.g. 'perello-bootstrap', 'perello-identity'"),
+		name: z
+			.string()
+			.describe("Plugin slug — e.g. 'perello-bootstrap', 'perello-identity'"),
 	},
 	async ({ name }) => {
-		const result = await convex.query(api.pluginContentDb.getPluginContent, { name });
+		const result = await convex.query(api.pluginContentDb.getPluginContent, {
+			name,
+		});
 		return {
 			content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
 		};
@@ -515,14 +667,23 @@ server.tool(
 	{
 		name: z.string().describe("Plugin slug — e.g. 'perello-bootstrap'"),
 		content: z.string().describe("Full plugin content body"),
-		createIfMissing: z.boolean().optional().default(false).describe("Auto-create a placeholder plugin row if it does not exist (default: false)"),
+		createIfMissing: z
+			.boolean()
+			.optional()
+			.default(false)
+			.describe(
+				"Auto-create a placeholder plugin row if it does not exist (default: false)",
+			),
 	},
 	async ({ name, content, createIfMissing }) => {
-		const result = await convex.mutation(api.pluginContentDb.upsertPluginContent, {
-			name,
-			content,
-			createIfMissing,
-		});
+		const result = await convex.mutation(
+			api.pluginContentDb.upsertPluginContent,
+			{
+				name,
+				content,
+				createIfMissing,
+			},
+		);
 		return {
 			content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
 		};
@@ -536,11 +697,20 @@ server.tool(
 		"canonical hash + stored filePath so the caller can compute disk SHA256 and compare. " +
 		"scope='all' (default) returns every plugin. name=<slug> filters to a single plugin.",
 	{
-		name: z.string().optional().describe("Plugin slug — filter to a single plugin"),
-		scope: z.string().optional().describe("'all' to return every plugin (default when name is omitted)"),
+		name: z
+			.string()
+			.optional()
+			.describe("Plugin slug — filter to a single plugin"),
+		scope: z
+			.string()
+			.optional()
+			.describe("'all' to return every plugin (default when name is omitted)"),
 	},
 	async ({ name, scope }) => {
-		const result = await convex.query(api.pluginContentDb.detectPluginDrift, { name, scope });
+		const result = await convex.query(api.pluginContentDb.detectPluginDrift, {
+			name,
+			scope,
+		});
 		return {
 			content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
 		};
@@ -557,10 +727,14 @@ server.tool(
 		"Returns content, sha256 hash, semver version, and last sync timestamp. " +
 		"Returns null fields if the hook has not been hosted in VR yet.",
 	{
-		name: z.string().describe("Hook slug — e.g. 'enforce-no-task-in-message', 'check-pii'"),
+		name: z
+			.string()
+			.describe("Hook slug — e.g. 'enforce-no-task-in-message', 'check-pii'"),
 	},
 	async ({ name }) => {
-		const result = await convex.query(api.hookContentDb.getHookContent, { name });
+		const result = await convex.query(api.hookContentDb.getHookContent, {
+			name,
+		});
 		return {
 			content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
 		};
@@ -579,7 +753,13 @@ server.tool(
 	{
 		name: z.string().describe("Hook slug — e.g. 'enforce-no-task-in-message'"),
 		content: z.string().describe("Full hook script content"),
-		createIfMissing: z.boolean().optional().default(false).describe("Auto-create a placeholder hook row if it does not exist (default: false)"),
+		createIfMissing: z
+			.boolean()
+			.optional()
+			.default(false)
+			.describe(
+				"Auto-create a placeholder hook row if it does not exist (default: false)",
+			),
 	},
 	async ({ name, content, createIfMissing }) => {
 		const result = await convex.mutation(api.hookContentDb.upsertHookContent, {
@@ -601,10 +781,16 @@ server.tool(
 		"scope='all' (default) returns every hook. name=<slug> filters to a single hook.",
 	{
 		name: z.string().optional().describe("Hook slug — filter to a single hook"),
-		scope: z.string().optional().describe("'all' to return every hook (default when name is omitted)"),
+		scope: z
+			.string()
+			.optional()
+			.describe("'all' to return every hook (default when name is omitted)"),
 	},
 	async ({ name, scope }) => {
-		const result = await convex.query(api.hookContentDb.detectHookDrift, { name, scope });
+		const result = await convex.query(api.hookContentDb.detectHookDrift, {
+			name,
+			scope,
+		});
 		return {
 			content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
 		};
@@ -621,10 +807,14 @@ server.tool(
 		"Returns content, sha256 hash, semver version, and last sync timestamp. " +
 		"Returns null fields if the command has not been hosted in VR yet.",
 	{
-		name: z.string().describe("Command slug — e.g. 'sync-workspace-from-vr', 'deploy-prod'"),
+		name: z
+			.string()
+			.describe("Command slug — e.g. 'sync-workspace-from-vr', 'deploy-prod'"),
 	},
 	async ({ name }) => {
-		const result = await convex.query(api.commandContentDb.getCommandContent, { name });
+		const result = await convex.query(api.commandContentDb.getCommandContent, {
+			name,
+		});
 		return {
 			content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
 		};
@@ -643,10 +833,13 @@ server.tool(
 		content: z.string().describe("Full command script content"),
 	},
 	async ({ name, content }) => {
-		const result = await convex.mutation(api.commandContentDb.upsertCommandContent, {
-			name,
-			content,
-		});
+		const result = await convex.mutation(
+			api.commandContentDb.upsertCommandContent,
+			{
+				name,
+				content,
+			},
+		);
 		return {
 			content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
 		};
@@ -660,11 +853,20 @@ server.tool(
 		"canonical hash + stored filePath so the caller can compute disk SHA256 and compare. " +
 		"scope='all' (default) returns every command. name=<slug> filters to a single command.",
 	{
-		name: z.string().optional().describe("Command slug — filter to a single command"),
-		scope: z.string().optional().describe("'all' to return every command (default when name is omitted)"),
+		name: z
+			.string()
+			.optional()
+			.describe("Command slug — filter to a single command"),
+		scope: z
+			.string()
+			.optional()
+			.describe("'all' to return every command (default when name is omitted)"),
 	},
 	async ({ name, scope }) => {
-		const result = await convex.query(api.commandContentDb.detectCommandDrift, { name, scope });
+		const result = await convex.query(api.commandContentDb.detectCommandDrift, {
+			name,
+			scope,
+		});
 		return {
 			content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
 		};
@@ -679,7 +881,9 @@ server.tool(
 	"upsert_plugin",
 	"Create or update a plugin in VantageRegistry. Upserts by name.",
 	{
-		name: z.string().describe("Plugin name — e.g. 'perello-bootstrap', 'perello-identity'"),
+		name: z
+			.string()
+			.describe("Plugin name — e.g. 'perello-bootstrap', 'perello-identity'"),
 		description: z.string().describe("What this plugin provides"),
 		agentCount: z.number().int().describe("Number of agents in this plugin"),
 		skillCount: z.number().int().describe("Number of skills in this plugin"),
@@ -690,9 +894,15 @@ server.tool(
 		filePath: z.string().optional().describe("Plugin directory path"),
 		pricing: z.enum(["free", "paid"]).optional().describe("Pricing tier"),
 		price: z.number().optional().describe("Price in EUR (if paid)"),
-		license: z.string().optional().describe("License — e.g. 'MIT', 'proprietary'"),
+		license: z
+			.string()
+			.optional()
+			.describe("License — e.g. 'MIT', 'proprietary'"),
 		publisherId: z.string().optional().describe("Publisher identifier"),
-		categories: z.array(z.string()).optional().describe("Categories beyond team name"),
+		categories: z
+			.array(z.string())
+			.optional()
+			.describe("Categories beyond team name"),
 	},
 	async (args) => {
 		const id = await convex.mutation(api.plugins.upsert, args);
@@ -709,12 +919,28 @@ server.tool(
 
 server.tool(
 	"list_plugins",
-	"List all plugins in VantageRegistry. Optionally filter by status.",
+	"List all plugins in VantageRegistry. Optionally filter by status, source, or team. " +
+		"fields='lite' returns compact {_id, name, status, source}. fields='full' returns the complete document.",
 	{
-		status: pluginStatusSchema.optional().describe("Filter by status — omit to list all"),
-	},
-	async ({ status }) => {
-		const results = await convex.query(api.plugins.list, { status });
+		status: pluginStatusSchema
+			.optional()
+			.describe("Filter by status — omit to list all"),
+		source: pluginSourceSchema
+			.optional()
+			.describe("Filter by source: 'internal' or 'external'"),
+		team: z.string().optional().describe("Filter by owning team"),
+		fields: z
+			.enum(["lite", "full"])
+			.optional()
+			.describe("Projection: 'lite' (compact) or 'full' (complete document)"),
+	},
+	async ({ status, source, team, fields }) => {
+		const results = await convex.query(api.plugins.list, {
+			status,
+			source,
+			team,
+			fields,
+		});
 		return {
 			content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
 		};
@@ -743,13 +969,20 @@ server.tool(
 	"upsert_hook",
 	"Create or update a hook in VantageRegistry. Upserts by name.",
 	{
-		name: z.string().describe("Hook name — e.g. 'check-pii', 'enforce-skill-references'"),
+		name: z
+			.string()
+			.describe("Hook name — e.g. 'check-pii', 'enforce-skill-references'"),
 		event: hookEventSchema,
-		matcher: z.string().optional().describe("Tool matcher pattern — e.g. 'Bash', 'Agent'"),
+		matcher: z
+			.string()
+			.optional()
+			.describe("Tool matcher pattern — e.g. 'Bash', 'Agent'"),
 		description: z.string().describe("What this hook does"),
 		content: z.string().describe("Full hook script content"),
 		filePath: z.string().describe("File path relative to project root"),
-		registered: z.boolean().describe("Whether this hook is registered in settings.json"),
+		registered: z
+			.boolean()
+			.describe("Whether this hook is registered in settings.json"),
 		status: hookStatusSchema,
 		version: z.string().optional().describe("Semantic version — e.g. '1.0.0'"),
 	},
@@ -759,7 +992,11 @@ server.tool(
 			content: [
 				{
 					type: "text",
-					text: JSON.stringify({ id, name: args.name, event: args.event }, null, 2),
+					text: JSON.stringify(
+						{ id, name: args.name, event: args.event },
+						null,
+						2,
+					),
 				},
 			],
 		};
@@ -768,12 +1005,30 @@ server.tool(
 
 server.tool(
 	"list_hooks",
-	"List all hooks in VantageRegistry. Optionally filter by status.",
+	"List all hooks in VantageRegistry. Optionally filter by status or lifecycle event. " +
+		"fields='lite' returns compact {_id, name, status, event, registered}. fields='full' returns the complete document including content.",
 	{
-		status: hookStatusSchema.optional().describe("Filter by status — omit to list all"),
+		status: hookStatusSchema
+			.optional()
+			.describe("Filter by status — omit to list all"),
+		event: hookEventSchema
+			.optional()
+			.describe(
+				"Filter by lifecycle event — e.g. 'PreToolUse', 'SessionStart'",
+			),
+		fields: z
+			.enum(["lite", "full"])
+			.optional()
+			.describe(
+				"Projection: 'lite' (compact) or 'full' (complete document with content)",
+			),
 	},
-	async ({ status }) => {
-		const results = await convex.query(api.hooks.list, { status });
+	async ({ status, event, fields }) => {
+		const results = await convex.query(api.hooks.list, {
+			status,
+			event,
+			fields,
+		});
 		return {
 			content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
 		};
@@ -802,8 +1057,13 @@ server.tool(
 	"upsert_prompt",
 	"Create or update a prompt in VantageRegistry. Upserts by name.",
 	{
-		name: z.string().describe("Prompt name — e.g. 'system-prompt', 'review-checklist'"),
-		team: z.string().optional().describe("Team this prompt belongs to — defaults to 'global'"),
+		name: z
+			.string()
+			.describe("Prompt name — e.g. 'system-prompt', 'review-checklist'"),
+		team: z
+			.string()
+			.optional()
+			.describe("Team this prompt belongs to — defaults to 'global'"),
 		purpose: z.string().describe("What this prompt is used for"),
 		content: z.string().describe("Full prompt content"),
 		version: z.string().optional().describe("Semantic version — e.g. '1.0.0'"),
@@ -858,7 +1118,10 @@ server.tool(
 	"Create or update a template in VantageRegistry. Upserts by name.",
 	{
 		name: z.string().describe("Template name — e.g. 'agent-brief', 'skill-md'"),
-		team: z.string().optional().describe("Team this template belongs to — defaults to 'global'"),
+		team: z
+			.string()
+			.optional()
+			.describe("Team this template belongs to — defaults to 'global'"),
 		purpose: z.string().describe("What this template is used for"),
 		content: z.string().describe("Full template content"),
 		version: z.string().optional().describe("Semantic version — e.g. '1.0.0'"),
@@ -881,10 +1144,15 @@ server.tool(
 	"List all templates in VantageRegistry. Optionally filter by team and/or template_type.",
 	{
 		team: z.string().optional().describe("Filter by team — omit to list all"),
-		template_type: templateTypeSchema.optional().describe("Filter by template type: mission, document, or checklist"),
+		template_type: templateTypeSchema
+			.optional()
+			.describe("Filter by template type: mission, document, or checklist"),
 	},
 	async ({ team, template_type }) => {
-		const results = await convex.query(api.templates.list, { team, template_type });
+		const results = await convex.query(api.templates.list, {
+			team,
+			template_type,
+		});
 		return {
 			content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
 		};
@@ -915,25 +1183,54 @@ server.tool(
 		"(lastTestedAt, lastReviewerScore, lastEvalDelta, testStatus). " +
 		"reviewerScore format is 'X/Y' e.g. '37/45'. evalDelta is pp delta vs without-skill baseline.",
 	{
-		skillId: z.string().describe("Convex document ID of the skill being tested"),
-		runDate: z.number().describe("Unix timestamp (ms) when the run was executed"),
-		runByOrchestrator: z.string().describe("Orchestrator that ran the test — e.g. 'alpha', 'pi'"),
-		runByMission: z.string().optional().describe("Mission reference — e.g. 'D70'"),
+		skillId: z
+			.string()
+			.describe("Convex document ID of the skill being tested"),
+		runDate: z
+			.number()
+			.describe("Unix timestamp (ms) when the run was executed"),
+		runByOrchestrator: z
+			.string()
+			.describe("Orchestrator that ran the test — e.g. 'alpha', 'pi'"),
+		runByMission: z
+			.string()
+			.optional()
+			.describe("Mission reference — e.g. 'D70'"),
 		reviewerScore: z.string().describe("Score as 'X/Y' — e.g. '37/45'"),
-		evalDelta: z.number().describe("Percentage-point delta vs without-skill baseline"),
+		evalDelta: z
+			.number()
+			.describe("Percentage-point delta vs without-skill baseline"),
 		evalAbsoluteWith: z.number().describe("Absolute score with skill (0-100)"),
-		evalAbsoluteWithout: z.number().describe("Absolute score without skill (0-100)"),
-		runnerModel: z.string().describe("Model used to run the skill — e.g. 'claude-sonnet-4-6'"),
-		judgeModel: z.string().describe("Model used as judge — e.g. 'claude-haiku-4-5'"),
-		corpusVersion: z.string().describe("Eval corpus version used — e.g. '2.0.0'"),
+		evalAbsoluteWithout: z
+			.number()
+			.describe("Absolute score without skill (0-100)"),
+		runnerModel: z
+			.string()
+			.describe("Model used to run the skill — e.g. 'claude-sonnet-4-6'"),
+		judgeModel: z
+			.string()
+			.describe("Model used as judge — e.g. 'claude-haiku-4-5'"),
+		corpusVersion: z
+			.string()
+			.describe("Eval corpus version used — e.g. '2.0.0'"),
 		harnessVersion: z.string().describe("Test harness version — e.g. '0.1.0'"),
 		skillSha: z.string().describe("Git SHA of the skill file at test time"),
-		gradingJsonPath: z.string().optional().describe("Path to grading output JSON"),
-		benchmarkJsonPath: z.string().optional().describe("Path to benchmark output JSON"),
+		gradingJsonPath: z
+			.string()
+			.optional()
+			.describe("Path to grading output JSON"),
+		benchmarkJsonPath: z
+			.string()
+			.optional()
+			.describe("Path to benchmark output JSON"),
 		reportPath: z.string().optional().describe("Path to human-readable report"),
-		timeSpentMinutes: z.number().optional().describe("Time spent running the test in minutes"),
+		timeSpentMinutes: z
+			.number()
+			.optional()
+			.describe("Time spent running the test in minutes"),
 		notes: z.string().optional().describe("Free-form notes about this run"),
-		testStatus: z.enum(["untested", "tested", "needs_retest", "improving", "untestable"])
+		testStatus: z
+			.enum(["untested", "tested", "needs_retest", "improving", "untestable"])
 			.optional()
 			.describe("Override test status — defaults to 'tested'"),
 	},
@@ -943,7 +1240,16 @@ server.tool(
 			skillId: args.skillId as any,
 		});
 		return {
-			content: [{ type: "text", text: JSON.stringify({ id, skillId: args.skillId, runDate: args.runDate }, null, 2) }],
+			content: [
+				{
+					type: "text",
+					text: JSON.stringify(
+						{ id, skillId: args.skillId, runDate: args.runDate },
+						null,
+						2,
+					),
+				},
+			],
 		};
 	},
 );
@@ -953,7 +1259,10 @@ server.tool(
 	"Return test run history for a skill, ordered newest-first.",
 	{
 		skillId: z.string().describe("Convex document ID of the skill"),
-		limit: z.number().optional().describe("Max number of runs to return — defaults to 50"),
+		limit: z
+			.number()
+			.optional()
+			.describe("Max number of runs to return — defaults to 50"),
 	},
 	async ({ skillId, limit }) => {
 		const results = await convex.query(api.skillTestRuns.getSkillTestHistory, {
@@ -969,12 +1278,31 @@ server.tool(
 server.tool(
 	"list_skills_by_freshness",
 	"Return skills that have never been tested or were last tested more than staleDays ago. " +
-		"Use this to find skills that need a quality test run.",
+		"Use this to find skills that need a quality test run. " +
+		"Defaults to fields='lite' (bounded output) to stay under MCP token cap. " +
+		"Use fields='full' to retrieve complete skill documents.",
 	{
-		staleDays: z.number().describe("Number of days since last test run to consider stale"),
+		staleDays: z
+			.number()
+			.describe("Number of days since last test run to consider stale"),
+		fields: z
+			.enum(["lite", "full"])
+			.optional()
+			.default("lite")
+			.describe(
+				"Projection: 'lite' (default, compact — bounded output) or 'full' (complete document)",
+			),
+		limit: z
+			.number()
+			.int()
+			.optional()
+			.describe("Max results — defaults to 100, max 500"),
 	},
-	async ({ staleDays }) => {
-		const results = await convex.query(api.skillTestRuns.listSkillsByFreshness, { staleDays });
+	async ({ staleDays, fields, limit }) => {
+		const results = await convex.query(
+			api.skillTestRuns.listSkillsByFreshness,
+			{ staleDays, fields, limit },
+		);
 		return {
 			content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
 		};
@@ -984,13 +1312,33 @@ server.tool(
 server.tool(
 	"list_skills_below_threshold",
 	"Return skills whose last test run was below a score ratio (scoreMin as 0-1 fraction of 'X/Y') " +
-		"or below a delta threshold (deltaMin in pp). Omit a param to skip that filter.",
+		"or below a delta threshold (deltaMin in pp). Omit a param to skip that filter. " +
+		"fields='lite' returns compact output. fields='full' returns complete skill documents.",
 	{
-		scoreMin: z.number().optional().describe("Minimum acceptable score ratio (0-1). Skills below this are returned."),
-		deltaMin: z.number().optional().describe("Minimum acceptable eval delta in pp. Skills below this are returned."),
+		scoreMin: z
+			.number()
+			.optional()
+			.describe(
+				"Minimum acceptable score ratio (0-1). Skills below this are returned.",
+			),
+		deltaMin: z
+			.number()
+			.optional()
+			.describe(
+				"Minimum acceptable eval delta in pp. Skills below this are returned.",
+			),
+		fields: z
+			.enum(["lite", "full"])
+			.optional()
+			.describe(
+				"Projection: 'lite' (compact) or 'full' (complete document). Omit for full (backward compat).",
+			),
 	},
-	async ({ scoreMin, deltaMin }) => {
-		const results = await convex.query(api.skillTestRuns.listSkillsBelowThreshold, { scoreMin, deltaMin });
+	async ({ scoreMin, deltaMin, fields }) => {
+		const results = await convex.query(
+			api.skillTestRuns.listSkillsBelowThreshold,
+			{ scoreMin, deltaMin, fields },
+		);
 		return {
 			content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
 		};
@@ -1004,20 +1352,46 @@ server.tool(
 		skillId: z.string().describe("Convex document ID of the skill"),
 		version: z.string().describe("Corpus version — e.g. '2.0.0'"),
 		casesCount: z.number().int().describe("Number of eval cases"),
-		assertionsCount: z.number().int().describe("Total number of assertions across all cases"),
-		baselinePrompt: z.string().describe("The baseline prompt used without the skill"),
-		evalsJsonContent: z.string().describe("Full JSON content of the evals file, or '{}' as placeholder"),
-		authoredBy: z.string().describe("Orchestrator or person who authored this corpus"),
-		authoredAt: z.number().describe("Unix timestamp (ms) when the corpus was authored"),
-		supersedesVersion: z.string().optional().describe("Version this corpus supersedes — e.g. '1.0.0'"),
+		assertionsCount: z
+			.number()
+			.int()
+			.describe("Total number of assertions across all cases"),
+		baselinePrompt: z
+			.string()
+			.describe("The baseline prompt used without the skill"),
+		evalsJsonContent: z
+			.string()
+			.describe("Full JSON content of the evals file, or '{}' as placeholder"),
+		authoredBy: z
+			.string()
+			.describe("Orchestrator or person who authored this corpus"),
+		authoredAt: z
+			.number()
+			.describe("Unix timestamp (ms) when the corpus was authored"),
+		supersedesVersion: z
+			.string()
+			.optional()
+			.describe("Version this corpus supersedes — e.g. '1.0.0'"),
 	},
 	async (args) => {
-		const id = await convex.mutation(api.skillEvalCorpus.upsertSkillEvalCorpus, {
-			...args,
-			skillId: args.skillId as any,
-		});
+		const id = await convex.mutation(
+			api.skillEvalCorpus.upsertSkillEvalCorpus,
+			{
+				...args,
+				skillId: args.skillId as any,
+			},
+		);
 		return {
-			content: [{ type: "text", text: JSON.stringify({ id, skillId: args.skillId, version: args.version }, null, 2) }],
+			content: [
+				{
+					type: "text",
+					text: JSON.stringify(
+						{ id, skillId: args.skillId, version: args.version },
+						null,
+						2,
+					),
+				},
+			],
 		};
 	},
 );
@@ -1042,21 +1416,34 @@ const runbookInputSchema = z.object({
 const runbookOutputSchema = z.object({
 	name: z.string().describe("Output artifact name"),
 	description: z.string().describe("What this output contains"),
-	path_pattern: z.string().optional().describe("File path pattern — e.g. 'reports/{name}.md'"),
+	path_pattern: z
+		.string()
+		.optional()
+		.describe("File path pattern — e.g. 'reports/{name}.md'"),
 });
 
 const applicabilitySchema = z.object({
-	orchestrators: z.array(z.string()).describe("Orchestrator slugs this runbook applies to"),
-	business_units: z.array(z.string()).describe("Business unit slugs this runbook applies to"),
-	use_cases: z.array(z.string()).describe("Use case slugs this runbook applies to"),
+	orchestrators: z
+		.array(z.string())
+		.describe("Orchestrator slugs this runbook applies to"),
+	business_units: z
+		.array(z.string())
+		.describe("Business unit slugs this runbook applies to"),
+	use_cases: z
+		.array(z.string())
+		.describe("Use case slugs this runbook applies to"),
 });
 
 const linkedTemplateSchema = z.object({
 	name: z.string().describe("Template name"),
-	template_type: z.string().describe("Template type — mission, document, or checklist"),
+	template_type: z
+		.string()
+		.describe("Template type — mission, document, or checklist"),
 	version: z.string().describe("Template version — e.g. '1.0.0'"),
 	usage_phase: z.string().describe("Phase name where this template is used"),
-	required: z.boolean().describe("Whether this template is required for the runbook"),
+	required: z
+		.boolean()
+		.describe("Whether this template is required for the runbook"),
 	description: z.string().describe("How this template is used in this runbook"),
 });
 
@@ -1064,32 +1451,60 @@ server.tool(
 	"upsert_runbook",
 	"Create or update a runbook in VantageRegistry. Upserts by name — if a runbook with the same name exists, it is updated.",
 	{
-		name: z.string().describe("Runbook slug — e.g. 'deploy-production', 'onboard-agent'"),
+		name: z
+			.string()
+			.describe("Runbook slug — e.g. 'deploy-production', 'onboard-agent'"),
 		description: z.string().describe("What this runbook accomplishes"),
 		version: z.string().describe("Semantic version — e.g. '1.0.0'"),
 		status: runbookStatusSchema,
-		category: z.string().describe("Category — e.g. 'deployment', 'onboarding', 'quality'"),
+		category: z
+			.string()
+			.describe("Category — e.g. 'deployment', 'onboarding', 'quality'"),
 		tags: z.array(z.string()).describe("Searchable tags"),
 		content: z.string().describe("Full runbook content (markdown)"),
 		phases: z.array(phaseSchema).describe("Ordered phases of the runbook"),
-		inputs: z.array(runbookInputSchema).describe("Input parameters for the runbook"),
-		outputs: z.array(runbookOutputSchema).describe("Output artifacts produced by the runbook"),
+		inputs: z
+			.array(runbookInputSchema)
+			.describe("Input parameters for the runbook"),
+		outputs: z
+			.array(runbookOutputSchema)
+			.describe("Output artifacts produced by the runbook"),
 		applicability: applicabilitySchema,
 		author: z.string().describe("Author slug — e.g. 'omega'"),
 		team: z.string().describe("Owning team slug — e.g. 'core', 'dev'"),
-		related_skills: z.array(z.string()).describe("Skill slugs referenced by this runbook"),
-		related_agents: z.array(z.string()).describe("Agent slugs referenced by this runbook"),
-		linked_templates: z.array(linkedTemplateSchema).describe("Templates used during this runbook"),
+		related_skills: z
+			.array(z.string())
+			.describe("Skill slugs referenced by this runbook"),
+		related_agents: z
+			.array(z.string())
+			.describe("Agent slugs referenced by this runbook"),
+		linked_templates: z
+			.array(linkedTemplateSchema)
+			.describe("Templates used during this runbook"),
 	},
 	async (args) => {
 		try {
 			const result = await convex.mutation(api.runbooks.upsertRunbook, args);
 			return {
-				content: [{ type: "text", text: JSON.stringify({ success: true, data: result }, null, 2) }],
+				content: [
+					{
+						type: "text",
+						text: JSON.stringify({ success: true, data: result }, null, 2),
+					},
+				],
 			};
 		} catch (err) {
 			return {
-				content: [{ type: "text", text: JSON.stringify({ success: false, error: String(err) }, null, 2) }],
+				content: [
+					{
+						type: "text",
+						text: JSON.stringify(
+							{ success: false, error: String(err) },
+							null,
+							2,
+						),
+					},
+				],
 			};
 		}
 	},
@@ -1100,17 +1515,37 @@ server.tool(
 	"Get a single runbook by name. Optionally guard by exact version.",
 	{
 		name: z.string().describe("Runbook slug — e.g. 'deploy-production'"),
-		version: z.string().optional().describe("If provided, returns null when stored version differs"),
+		version: z
+			.string()
+			.optional()
+			.describe("If provided, returns null when stored version differs"),
 	},
 	async ({ name, version }) => {
 		try {
-			const result = await convex.query(api.runbooks.getRunbook, { name, version });
+			const result = await convex.query(api.runbooks.getRunbook, {
+				name,
+				version,
+			});
 			return {
-				content: [{ type: "text", text: JSON.stringify({ success: true, data: result }, null, 2) }],
+				content: [
+					{
+						type: "text",
+						text: JSON.stringify({ success: true, data: result }, null, 2),
+					},
+				],
 			};
 		} catch (err) {
 			return {
-				content: [{ type: "text", text: JSON.stringify({ success: false, error: String(err) }, null, 2) }],
+				content: [
+					{
+						type: "text",
+						text: JSON.stringify(
+							{ success: false, error: String(err) },
+							null,
+							2,
+						),
+					},
+				],
 			};
 		}
 	},
@@ -1120,23 +1555,55 @@ server.tool(
 	"list_runbooks",
 	"List runbooks in VantageRegistry. Defaults to published status. Supports applicability filters.",
 	{
-		status: runbookStatusSchema.optional().describe("Filter by status — defaults to 'published'"),
-		category: z.string().optional().describe("Filter by category — e.g. 'deployment'"),
+		status: runbookStatusSchema
+			.optional()
+			.describe("Filter by status — defaults to 'published'"),
+		category: z
+			.string()
+			.optional()
+			.describe("Filter by category — e.g. 'deployment'"),
 		team: z.string().optional().describe("Filter by owning team"),
-		applicability_orchestrator: z.string().optional().describe("Filter by orchestrator slug in applicability"),
-		applicability_bu: z.string().optional().describe("Filter by business unit slug in applicability"),
-		applicability_use_case: z.string().optional().describe("Filter by use case slug in applicability"),
-		limit: z.number().int().optional().describe("Max results to return — defaults to 50, max 200"),
+		applicability_orchestrator: z
+			.string()
+			.optional()
+			.describe("Filter by orchestrator slug in applicability"),
+		applicability_bu: z
+			.string()
+			.optional()
+			.describe("Filter by business unit slug in applicability"),
+		applicability_use_case: z
+			.string()
+			.optional()
+			.describe("Filter by use case slug in applicability"),
+		limit: z
+			.number()
+			.int()
+			.optional()
+			.describe("Max results to return — defaults to 50, max 200"),
 	},
 	async (args) => {
 		try {
 			const result = await convex.query(api.runbooks.listRunbooks, args);
 			return {
-				content: [{ type: "text", text: JSON.stringify({ success: true, data: result }, null, 2) }],
+				content: [
+					{
+						type: "text",
+						text: JSON.stringify({ success: true, data: result }, null, 2),
+					},
+				],
 			};
 		} catch (err) {
 			return {
-				content: [{ type: "text", text: JSON.stringify({ success: false, error: String(err) }, null, 2) }],
+				content: [
+					{
+						type: "text",
+						text: JSON.stringify(
+							{ success: false, error: String(err) },
+							null,
+							2,
+						),
+					},
+				],
 			};
 		}
 	},
@@ -1146,18 +1613,41 @@ server.tool(
 	"list_runbooks_by_category",
 	"List runbooks for a specific category using the byCategory index.",
 	{
-		category: z.string().describe("Category to filter by — e.g. 'deployment', 'quality'"),
-		status: runbookStatusSchema.optional().describe("Filter by status — omit to list all statuses in this category"),
+		category: z
+			.string()
+			.describe("Category to filter by — e.g. 'deployment', 'quality'"),
+		status: runbookStatusSchema
+			.optional()
+			.describe(
+				"Filter by status — omit to list all statuses in this category",
+			),
 	},
 	async ({ category, status }) => {
 		try {
-			const result = await convex.query(api.runbooks.listRunbooksByCategory, { category, status });
+			const result = await convex.query(api.runbooks.listRunbooksByCategory, {
+				category,
+				status,
+			});
 			return {
-				content: [{ type: "text", text: JSON.stringify({ success: true, data: result }, null, 2) }],
+				content: [
+					{
+						type: "text",
+						text: JSON.stringify({ success: true, data: result }, null, 2),
+					},
+				],
 			};
 		} catch (err) {
 			return {
-				content: [{ type: "text", text: JSON.stringify({ success: false, error: String(err) }, null, 2) }],
+				content: [
+					{
+						type: "text",
+						text: JSON.stringify(
+							{ success: false, error: String(err) },
+							null,
+							2,
+						),
+					},
+				],
 			};
 		}
 	},
@@ -1168,17 +1658,36 @@ server.tool(
 	"List runbooks for a specific team using the byTeam index.",
 	{
 		team: z.string().describe("Team slug to filter by — e.g. 'core', 'dev'"),
-		status: runbookStatusSchema.optional().describe("Filter by status — omit to list all statuses for this team"),
+		status: runbookStatusSchema
+			.optional()
+			.describe("Filter by status — omit to list all statuses for this team"),
 	},
 	async ({ team, status }) => {
 		try {
-			const result = await convex.query(api.runbooks.listRunbooksByTeam, { team, status });
+			const result = await convex.query(api.runbooks.listRunbooksByTeam, {
+				team,
+				status,
+			});
 			return {
-				content: [{ type: "text", text: JSON.stringify({ success: true, data: result }, null, 2) }],
+				content: [
+					{
+						type: "text",
+						text: JSON.stringify({ success: true, data: result }, null, 2),
+					},
+				],
 			};
 		} catch (err) {
 			return {
-				content: [{ type: "text", text: JSON.stringify({ success: false, error: String(err) }, null, 2) }],
+				content: [
+					{
+						type: "text",
+						text: JSON.stringify(
+							{ success: false, error: String(err) },
+							null,
+							2,
+						),
+					},
+				],
 			};
 		}
 	},
@@ -1192,13 +1701,29 @@ server.tool(
 	},
 	async ({ name }) => {
 		try {
-			const result = await convex.mutation(api.runbooks.deleteRunbook, { name });
+			const result = await convex.mutation(api.runbooks.deleteRunbook, {
+				name,
+			});
 			return {
-				content: [{ type: "text", text: JSON.stringify({ success: true, data: result }, null, 2) }],
+				content: [
+					{
+						type: "text",
+						text: JSON.stringify({ success: true, data: result }, null, 2),
+					},
+				],
 			};
 		} catch (err) {
 			return {
-				content: [{ type: "text", text: JSON.stringify({ success: false, error: String(err) }, null, 2) }],
+				content: [
+					{
+						type: "text",
+						text: JSON.stringify(
+							{ success: false, error: String(err) },
+							null,
+							2,
+						),
+					},
+				],
 			};
 		}
 	},
@@ -1416,6 +1941,306 @@ server.tool(
 	},
 );
 
+// ═══════════════════════════════════════════════════════════════════════════════
+// COMPONENTS CATALOG (D90 — closes orphaned list_components tool)
+// ═══════════════════════════════════════════════════════════════════════════════
+
+const componentKindSchema = z
+	.enum(["skill", "agent", "hook", "plugin", "prompt", "runbook", "template"])
+	.describe("Component kind");
+
+const componentStatusSchema = z
+	.enum(["active", "deprecated", "experimental"])
+	.describe("Component status");
+
+server.tool(
+	"register_component",
+	"Create or update a component in the VantageRegistry components catalog. " +
+		"Upserts by name+kind — if a component with the same name and kind exists it is updated. " +
+		"Use this to register any VantageOS primitive: skill, agent, hook, plugin, prompt, runbook, or template.",
+	{
+		name: z
+			.string()
+			.describe(
+				"Component name slug — e.g. 'check-messages', 'dev-convex-expert'",
+			),
+		kind: componentKindSchema,
+		status: componentStatusSchema,
+		ownerTeam: z
+			.string()
+			.optional()
+			.describe("Team that owns this component — e.g. 'core', 'dev'"),
+		description: z
+			.string()
+			.optional()
+			.describe("Short description of what this component does"),
+		vrEntityId: z
+			.string()
+			.optional()
+			.describe("ID of the backing VR entity (skill _id, agent _id, etc.)"),
+		metadata: z
+			.record(z.string(), z.unknown())
+			.optional()
+			.describe("Arbitrary metadata bag — store extra fields here"),
+		tags: z
+			.array(z.string())
+			.optional()
+			.describe("Searchable tags — e.g. ['ai', 'backend']"),
+	},
+	async (args) => {
+		try {
+			const id = await convex.mutation(api.components.registerComponent, args);
+			return {
+				content: [
+					{
+						type: "text",
+						text: JSON.stringify(
+							{ id, name: args.name, kind: args.kind },
+							null,
+							2,
+						),
+					},
+				],
+			};
+		} catch (err) {
+			return {
+				content: [
+					{
+						type: "text",
+						text: JSON.stringify(
+							{ success: false, error: String(err) },
+							null,
+							2,
+						),
+					},
+				],
+			};
+		}
+	},
+);
+
+server.tool(
+	"list_components",
+	"List components in the VantageRegistry catalog. " +
+		"Supports filtering by kind, ownerTeam, status, and tags. " +
+		"fields='lite' (default) returns compact {_id, name, kind, status, ownerTeam}. " +
+		"fields='full' returns the complete document including description, tags, metadata, vrEntityId. " +
+		"limit defaults to 100, max 500.",
+	{
+		kind: componentKindSchema
+			.optional()
+			.describe("Filter by kind — omit to return all kinds"),
+		ownerTeam: z.string().optional().describe("Filter by owning team"),
+		status: componentStatusSchema
+			.optional()
+			.describe("Filter by status — omit to return all statuses"),
+		tags: z
+			.array(z.string())
+			.optional()
+			.describe("Filter by tags — ALL specified tags must match"),
+		fields: z
+			.enum(["lite", "full"])
+			.optional()
+			.describe("Projection: 'lite' (default) or 'full'"),
+		limit: z
+			.number()
+			.int()
+			.optional()
+			.describe("Max results — defaults to 100, max 500"),
+	},
+	async ({ kind, ownerTeam, status, tags, fields, limit }) => {
+		try {
+			const filter =
+				kind !== undefined ||
+				ownerTeam !== undefined ||
+				status !== undefined ||
+				tags !== undefined
+					? { kind, ownerTeam, status, tags }
+					: undefined;
+			const results = await convex.query(api.components.listComponents, {
+				filter,
+				fields,
+				limit,
+			});
+			return {
+				content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
+			};
+		} catch (err) {
+			return {
+				content: [
+					{
+						type: "text",
+						text: JSON.stringify(
+							{ success: false, error: String(err) },
+							null,
+							2,
+						),
+					},
+				],
+			};
+		}
+	},
+);
+
+server.tool(
+	"get_component",
+	"Get a single component by its Convex document ID. Returns the full document or null if not found.",
+	{
+		id: z.string().describe("Convex document ID of the component"),
+	},
+	async ({ id }) => {
+		try {
+			const result = await convex.query(api.components.getComponent, {
+				id: id as any,
+			});
+			return {
+				content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+			};
+		} catch (err) {
+			return {
+				content: [
+					{
+						type: "text",
+						text: JSON.stringify(
+							{ success: false, error: String(err) },
+							null,
+							2,
+						),
+					},
+				],
+			};
+		}
+	},
+);
+
+server.tool(
+	"search_components",
+	"Search components by name prefix. Returns up to `limit` lite results whose name starts with the query string. " +
+		"Case-sensitive index range scan. Use list_components with filters for kind/status/tags filtering.",
+	{
+		query: z
+			.string()
+			.describe("Name prefix to search for — e.g. 'check', 'dev-'"),
+		limit: z
+			.number()
+			.int()
+			.optional()
+			.describe("Max results — defaults to 50, max 200"),
+	},
+	async ({ query, limit }) => {
+		try {
+			const results = await convex.query(api.components.searchComponents, {
+				query,
+				limit,
+			});
+			return {
+				content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
+			};
+		} catch (err) {
+			return {
+				content: [
+					{
+						type: "text",
+						text: JSON.stringify(
+							{ success: false, error: String(err) },
+							null,
+							2,
+						),
+					},
+				],
+			};
+		}
+	},
+);
+
+server.tool(
+	"update_component",
+	"Patch individual fields on an existing component. Only provided fields are updated. Throws if not found.",
+	{
+		id: z.string().describe("Convex document ID of the component to update"),
+		name: z.string().optional().describe("New name slug"),
+		kind: componentKindSchema.optional().describe("New kind"),
+		ownerTeam: z.string().optional().describe("New owning team"),
+		description: z.string().optional().describe("New description"),
+		status: componentStatusSchema.optional().describe("New status"),
+		vrEntityId: z.string().optional().describe("Updated vrEntityId reference"),
+		metadata: z
+			.record(z.string(), z.unknown())
+			.optional()
+			.describe("Updated metadata bag"),
+		tags: z.array(z.string()).optional().describe("Updated tags array"),
+	},
+	async (args) => {
+		try {
+			await convex.mutation(api.components.updateComponent, {
+				...args,
+				id: args.id as any,
+			});
+			return {
+				content: [
+					{
+						type: "text",
+						text: JSON.stringify({ success: true, id: args.id }, null, 2),
+					},
+				],
+			};
+		} catch (err) {
+			return {
+				content: [
+					{
+						type: "text",
+						text: JSON.stringify(
+							{ success: false, error: String(err) },
+							null,
+							2,
+						),
+					},
+				],
+			};
+		}
+	},
+);
+
+server.tool(
+	"delete_component",
+	"Soft-delete a component by ID — sets status to 'deprecated'. " +
+		"The document remains in the database and is still retrievable. " +
+		"Returns {deleted: true} if found, {deleted: false} if not found.",
+	{
+		id: z
+			.string()
+			.describe("Convex document ID of the component to soft-delete"),
+	},
+	async ({ id }) => {
+		try {
+			const result = await convex.mutation(api.components.deleteComponent, {
+				id: id as any,
+			});
+			return {
+				content: [
+					{
+						type: "text",
+						text: JSON.stringify({ success: true, ...result }, null, 2),
+					},
+				],
+			};
+		} catch (err) {
+			return {
+				content: [
+					{
+						type: "text",
+						text: JSON.stringify(
+							{ success: false, error: String(err) },
+							null,
+							2,
+						),
+					},
+				],
+			};
+		}
+	},
+);
+
 // ═══════════════════════════════════════════════════════════════════════════════
 // STATS
 // ═══════════════════════════════════════════════════════════════════════════════
@@ -1427,15 +2252,30 @@ server.tool(
 		"Use this to get a quick overview of the registry contents.",
 	{},
 	async () => {
-		const [teams, agents, skills, plugins, hooks, rbDraft, rbPublished, rbDeprecated] = await Promise.all([
+		const [
+			teams,
+			agents,
+			skills,
+			plugins,
+			hooks,
+			rbDraft,
+			rbPublished,
+			rbDeprecated,
+		] = await Promise.all([
 			convex.query(api.teams.list, {}),
 			convex.query(api.agents.list, {}),
 			convex.query(api.skills.list, {}),
 			convex.query(api.plugins.list, {}),
 			convex.query(api.hooks.list, {}),
 			convex.query(api.runbooks.listRunbooks, { status: "draft", limit: 1000 }),
-			convex.query(api.runbooks.listRunbooks, { status: "published", limit: 1000 }),
-			convex.query(api.runbooks.listRunbooks, { status: "deprecated", limit: 1000 }),
+			convex.query(api.runbooks.listRunbooks, {
+				status: "published",
+				limit: 1000,
+			}),
+			convex.query(api.runbooks.listRunbooks, {
+				status: "deprecated",
+				limit: 1000,
+			}),
 		]);
 
 		// Build by_category map across all statuses
@@ -1444,7 +2284,8 @@ server.tool(
 			byCategoryMap[rb.category] = (byCategoryMap[rb.category] ?? 0) + 1;
 		}
 
-		const runbooksTotal = rbDraft.length + rbPublished.length + rbDeprecated.length;
+		const runbooksTotal =
+			rbDraft.length + rbPublished.length + rbDeprecated.length;
 
 		const stats = {
 			teams: teams.length,
@@ -1461,7 +2302,13 @@ server.tool(
 				},
 				by_category: byCategoryMap,
 			},
-			total: teams.length + agents.length + skills.length + plugins.length + hooks.length + runbooksTotal,
+			total:
+				teams.length +
+				agents.length +
+				skills.length +
+				plugins.length +
+				hooks.length +
+				runbooksTotal,
 		};
 
 		return {