@soulcraft/kit-schema 2.0.0

package/src/schema.ts

@@ -0,0 +1,705 @@
+/**
+ * @module @soulcraft/kit-schema/schema
+ * @description Zod v4 validation schemas for the Soulcraft kit manifest format.
+ *
+ * These schemas are used by the kit loader to validate `kit.json` files before
+ * mounting them in a platform deployment. Invalid kit manifests are rejected with
+ * descriptive error messages pointing to the offending field.
+ *
+ * @example
+ * ```ts
+ * import { VenueKitSchema } from '@soulcraft/kit-schema/schema';
+ *
+ * const result = VenueKitSchema.safeParse(rawManifest);
+ * if (!result.success) {
+ *   console.error('Invalid kit manifest:', result.error.format());
+ * }
+ * ```
+ */
+
+import { z } from 'zod';
+
+// ──────────────────────────────────────────────
+// Shared base schemas
+// ──────────────────────────────────────────────
+
+/** Author metadata schema. */
+const KitAuthorSchema = z.object({
+	name: z.string().min(1).max(200),
+	email: z.string().email().optional(),
+	url: z.string().url().optional()
+});
+
+/** Kit variable definition schema. */
+const KitVariableSchema = z.object({
+	key: z.string().min(1).max(100).regex(/^[a-zA-Z][a-zA-Z0-9_]*$/),
+	label: z.string().min(1).max(200),
+	description: z.string().max(500).optional(),
+	type: z.enum(['string', 'email', 'url', 'phone', 'timezone', 'address', 'color', 'number']),
+	required: z.boolean().optional(),
+	example: z.string().max(200).optional(),
+	default: z.string().max(200).optional()
+});
+
+// ──────────────────────────────────────────────
+// Venue kit schemas
+// ──────────────────────────────────────────────
+
+/** Venue theme configuration schema. */
+const VenueKitThemeSchema = z.object({
+	primary: z.string().min(1),
+	bgBase: z.string().min(1),
+	accent: z.string().min(1).optional(),
+	textPrimary: z.string().min(1).optional(),
+	displayFont: z.string().max(100).optional(),
+	bodyFont: z.string().max(100).optional()
+});
+
+/** Feature flags schema — includes Venue-native flags and Workshop-published content flags. */
+const VenueFeaturesSchema = z.object({
+	animals: z.boolean().optional(),
+	adoption: z.boolean().optional(),
+	memories: z.boolean().optional(),
+	loyalty: z.boolean().optional(),
+	giftCards: z.boolean().optional(),
+	waivers: z.boolean().optional(),
+	blog: z.boolean().optional(),
+	pos: z.boolean().optional(),
+	cms: z.boolean().optional(),
+	partners: z.boolean().optional(),
+	franchise: z.boolean().optional(),
+	customerAccounts: z.boolean().optional(),
+	/** Enable hosting of Workshop-published apps (Svelte component bundles). */
+	apps: z.boolean().optional(),
+	/** Enable hosting of Workshop-published documents. */
+	documents: z.boolean().optional(),
+	/** Enable hosting of Workshop-published visualizations. */
+	visualizations: z.boolean().optional(),
+	/** Enable WebSocket real-time features for Workshop apps hosted on this instance. */
+	realtime: z.boolean().optional(),
+	/** Enable push/email/SMS notifications via the notify prop of AppRuntimeContext. */
+	notifications: z.boolean().optional(),
+	/** Enable the public-facing website with CMS-managed pages, blog, and gallery. */
+	website: z.boolean().optional(),
+	/** Enable recurring subscription billing via Stripe Subscriptions. */
+	subscriptions: z.boolean().optional(),
+	/** Enable the customer support ticketing system. */
+	support: z.boolean().optional(),
+	/** Enable the built-in analytics pipeline (event tracking, funnel analysis, dashboards). */
+	analytics: z.boolean().optional(),
+	/** Enable outbound webhook delivery to external services (Zapier, Slack, custom HTTP). */
+	webhooks: z.boolean().optional(),
+	/** Enable API key management for third-party integrations and kiosk devices. */
+	apiKeys: z.boolean().optional(),
+	/** Enable the scheduled jobs system for time-based automation (cron tasks). */
+	scheduledJobs: z.boolean().optional()
+});
+
+/** Session attribute definition schema — declares what staff should log post-session. */
+const SessionAttributeDefinitionSchema = z.object({
+	key: z.string().min(1).max(100).regex(/^[a-zA-Z][a-zA-Z0-9_]*$/),
+	label: z.string().min(1).max(200),
+	type: z.enum(['text', 'select', 'multiselect']),
+	perGuest: z.boolean(),
+	options: z.array(z.string().min(1).max(200)).optional(),
+	required: z.boolean().optional()
+});
+
+/** Experience type definition schema. */
+const VenueExperienceTypeSchema = z.object({
+	slug: z.string().min(1).max(100).regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/),
+	name: z.string().min(1).max(200),
+	description: z.string().min(1),
+	priceInCents: z.number().int().min(0),
+	durationMinutes: z.number().int().min(5),
+	minGuests: z.number().int().min(1),
+	maxGuests: z.number().int().min(1),
+	requiresWaiver: z.boolean(),
+	isCombo: z.boolean().optional(),
+	componentSlugs: z.array(z.string()).optional(),
+	sortOrder: z.number().int().min(0),
+	color: z.string().optional(),
+	imageUrl: z.string().url().optional(),
+	pricingTiers: z.array(z.object({
+		minGuests: z.number().int().min(1),
+		maxGuests: z.number().int().min(1),
+		pricePerPersonInCents: z.number().int().min(0)
+	})).optional(),
+	sessionAttributeDefinitions: z.array(SessionAttributeDefinitionSchema).optional()
+});
+
+/** Inventory category schema. */
+const VenueInventoryCategorySchema = z.object({
+	id: z.string().min(1).max(100),
+	label: z.string().min(1).max(200),
+	icon: z.string().optional()
+});
+
+/** Staff role extension schema. */
+const VenueStaffRoleSchema = z.object({
+	id: z.string().min(1).max(100),
+	label: z.string().min(1).max(200),
+	defaultCapabilities: z.array(z.string()).optional()
+});
+
+/** Chatbot suggestion chip schema. */
+const VenueChatSuggestionSchema = z.object({
+	label: z.string().min(1).max(100),
+	message: z.string().min(1).max(500),
+	emoji: z.string().max(10).optional()
+});
+
+/** Pluggable back-office station schema. */
+const VenueStationSchema = z.object({
+	id: z
+		.string()
+		.min(1)
+		.max(100)
+		.regex(/^[a-z0-9-]+$/, 'Station ID must be lowercase alphanumeric with hyphens'),
+	label: z.string().min(1).max(200),
+	route: z.string().min(1).max(500),
+	icon: z.string().min(1),
+	roles: z.array(z.enum(['staff', 'manager', 'owner'])).min(1),
+	scope: z.enum(['platform', 'kit']).optional(),
+	context: z.enum(['physical', 'digital', 'both']).optional(),
+	bundle: z.string().min(1).max(500).optional(),
+	group: z.string().min(1).max(100).optional()
+});
+
+/** Venue-specific config block schema. */
+const VenueConfigSchema = z.object({
+	experienceTypes: z.array(VenueExperienceTypeSchema).default([]),
+	features: VenueFeaturesSchema,
+	theme: VenueKitThemeSchema.optional(),
+	inventoryCategories: z.array(VenueInventoryCategorySchema).optional(),
+	staffRoles: z.array(VenueStaffRoleSchema).optional(),
+	bookingNumberPrefix: z
+		.string()
+		.min(1)
+		.max(6)
+		.regex(/^[A-Z0-9]+$/)
+		.optional(),
+	subdomainPrefix: z
+		.string()
+		.min(1)
+		.max(30)
+		.regex(/^[a-z0-9-]+$/)
+		.optional(),
+	chatSuggestions: z.array(VenueChatSuggestionSchema).optional(),
+	inventoryLevelDetection: z.enum(['vision', 'manual', 'hybrid']).optional(),
+	stations: z.array(VenueStationSchema).optional()
+});
+
+/**
+ * Zod schema for validating a Venue kit manifest (`kit.json`).
+ *
+ * @example
+ * ```ts
+ * const parsed = VenueKitSchema.parse(rawJson);
+ * // parsed is typed as VenueKitConfig
+ * ```
+ */
+export const VenueKitSchema = z
+	.object({
+		id: z
+			.string()
+			.min(1)
+			.max(100)
+			.regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/),
+		type: z.literal('venue'),
+		name: z.string().min(1).max(200),
+		description: z.string().min(1).max(500),
+		version: z.string().regex(/^\d+\.\d+\.\d+$/),
+		author: KitAuthorSchema,
+		minPlatformVersion: z.string().optional(),
+		tags: z.array(z.string()).optional(),
+		previewImageUrl: z.string().url().optional(),
+		role: z.enum(['primary', 'extension']).optional(),
+		requires: z.array(z.string().min(1).max(100)).optional(),
+		conflicts: z.array(z.string().min(1).max(100)).optional(),
+		variables: z.array(KitVariableSchema),
+		venue: VenueConfigSchema
+	})
+	.strict();
+
+/** Inferred TypeScript type from the Venue kit schema. */
+export type VenueKitInput = z.infer<typeof VenueKitSchema>;
+
+// ──────────────────────────────────────────────
+// Workshop kit schemas
+// ──────────────────────────────────────────────
+
+const WorkshopExploreViewSchema = z.enum([
+	'graph', 'mindmap', 'timeline', 'board', 'matrix',
+	'gallery', 'calendar', 'tree', 'stats', 'map', 'dev', 'app'
+]);
+
+const WorkshopWorkspaceParadigmSchema = z.enum([
+	'writer', 'researcher', 'planner', 'developer', 'creative', 'analyst', 'builder', 'custom'
+]);
+
+const WorkshopWorkspaceConfigSchema = z.object({
+	paradigm: WorkshopWorkspaceParadigmSchema.optional(),
+	defaultTab: z.enum(['edit', 'explore', 'app']).optional(),
+	defaultView: WorkshopExploreViewSchema.optional(),
+	defaultFile: z.string().optional(),
+	fallbackFiles: z.array(z.string()).optional()
+}).optional();
+
+const WorkshopAIPersonaSchema = z.object({
+	role: z.string().min(1),
+	expertise: z.array(z.string().min(1)),
+	tone: z.enum(['mentor', 'editor', 'collaborator', 'assistant']),
+	avoidances: z.array(z.string()).optional()
+}).optional();
+
+const WorkshopDomainKnowledgeSchema = z.object({
+	glossary: z.record(z.string(), z.string()).optional(),
+	conventions: z.array(z.string()).optional(),
+	antiPatterns: z.array(z.string()).optional(),
+	formatting: z.array(z.string()).optional(),
+	references: z.array(z.object({
+		title: z.string().min(1),
+		description: z.string().min(1),
+		url: z.string().url().optional()
+	})).optional()
+}).optional();
+
+const WorkshopWorkflowSchema = z.object({
+	id: z.string().min(1).max(100),
+	name: z.string().min(1).max(200),
+	description: z.string().min(1),
+	steps: z.array(z.string().min(1)).min(1),
+	inputs: z.array(z.object({
+		name: z.string().min(1),
+		description: z.string().min(1),
+		required: z.boolean().optional()
+	})).optional(),
+	outputs: z.array(z.string()).optional(),
+	triggers: z.array(z.string()).optional(),
+	autoExecute: z.boolean().optional()
+});
+
+const WorkshopGraphGuidanceSchema = z.object({
+	conceptCreation: z.object({
+		triggers: z.array(z.string()).optional(),
+		typeMapping: z.record(z.string(), z.string())
+	}).optional(),
+	relationshipPatterns: z.array(z.object({
+		from: z.string().min(1),
+		to: z.string().min(1),
+		verb: z.string().min(1),
+		description: z.string().min(1)
+	})).optional(),
+	rules: z.array(z.string()).optional()
+}).optional();
+
+const WorkshopQualityGatesSchema = z.object({
+	fileChecks: z.array(z.object({
+		path: z.string().min(1),
+		required: z.array(z.string()).optional(),
+		optional: z.array(z.string()).optional()
+	})).optional(),
+	projectChecks: z.array(z.string()).optional(),
+	exportReady: z.array(z.string()).optional()
+}).optional();
+
+const WorkshopExporterSchema = z.object({
+	id: z.string().min(1).max(100),
+	name: z.string().min(1).max(200),
+	description: z.string().min(1),
+	icon: z.string().min(1),
+	format: z.string().min(1).max(20),
+	category: z.enum([
+		'manuscript', 'ebook', 'archive', 'web', 'document', 'data', 'presentation', 'other'
+	]),
+	handler: z.string().min(1)
+});
+
+const WorkshopExportPreferencesSchema = z.object({
+	defaultExporter: z.string().optional(),
+	fileNameTemplate: z.string().optional(),
+	instructions: z.string().optional(),
+	globalPrerequisites: z.array(z.string()).optional()
+}).optional();
+
+const WorkshopExportStructureSchema = z.object({
+	combineStrategy: z.enum(['graph-order', 'path-order', 'manual']),
+	orderRelationship: z.string().optional(),
+	includePatterns: z.array(z.string()).optional(),
+	excludePatterns: z.array(z.string()).optional(),
+	fileOrder: z.array(z.string()).optional()
+}).optional();
+
+/**
+ * Cross-product suggestion chip schema.
+ * Used in `SharedKitFoundationSchema.suggestions` and (deprecated) `WorkshopConfigSchema.suggestions`.
+ */
+const KitSuggestionSchema = z.object({
+	label: z.string().min(1).max(50),
+	prompt: z.string().min(1).max(500)
+});
+
+/** @deprecated Suggestions moved to `SharedKitFoundationSchema.suggestions`. Alias preserved for backward compat. */
+const WorkshopSuggestionSchema = KitSuggestionSchema;
+
+const WorkshopPublishConfigSchema = z.object({
+	contentType: z.enum(['app', 'document', 'visualization', 'slideshow', 'static']),
+	publishable: z.boolean().optional(),
+	defaultSlug: z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/).optional()
+}).optional();
+
+/** Template identity metadata schema. */
+const WorkshopTemplateMetadataSchema = z.object({
+	identifyByStructure: z.boolean().optional(),
+	runnable: z.boolean().optional(),
+	runnableCommand: z.string().max(500).optional()
+}).optional();
+
+/** Cloud deployment configuration schema. */
+const WorkshopDeployConfigSchema = z.object({
+	provider: z.string().max(100).optional(),
+	buildCommand: z.string().max(500).optional(),
+	outputDir: z.string().max(500).optional(),
+	config: z.record(z.string(), z.unknown()).optional(),
+	oneClickCommand: z.string().max(500).optional()
+}).optional();
+
+/** Sample data entity schema. */
+const WorkshopSampleEntitySchema = z.object({
+	type: z.string().min(1).max(100),
+	name: z.string().min(1).max(500),
+	properties: z.record(z.string(), z.unknown()).optional()
+});
+
+/** Sample data schema for pre-populating a new project's knowledge graph. */
+const WorkshopSampleDataSchema = z.object({
+	description: z.string().max(1000).optional(),
+	entities: z.array(WorkshopSampleEntitySchema).min(1),
+	relationships: z.array(z.object({
+		from: z.string().min(1).max(500),
+		verb: z.string().min(1).max(100),
+		to: z.string().min(1).max(500)
+	})).optional()
+}).optional();
+
+/** Connected workbench definition schema for Workshop remote sessions. */
+const WorkshopConnectedWorkbenchSchema = z.object({
+	name: z.string().min(1).max(200),
+	view: z.enum(['graph', 'mindmap', 'tree', 'timeline', 'board', 'gallery', 'stats', 'matrix', 'calendar']),
+	entityTypes: z.array(z.string().min(1).max(100)).min(1),
+	description: z.string().max(500).optional()
+});
+
+/** Remote workspace configuration schema for Workshop remote sessions. */
+const WorkshopRemoteWorkspaceSchema = z.object({
+	connectedWorkbenches: z.array(WorkshopConnectedWorkbenchSchema).optional()
+}).optional();
+
+/** Workshop-specific config block schema. */
+const WorkshopConfigSchema = z
+	.object({
+		workspaceConfig: WorkshopWorkspaceConfigSchema,
+		graphGuidance: WorkshopGraphGuidanceSchema,
+		qualityGates: WorkshopQualityGatesSchema,
+		publishConfig: WorkshopPublishConfigSchema,
+		aiPersona: WorkshopAIPersonaSchema,
+		domainKnowledge: WorkshopDomainKnowledgeSchema,
+		workflows: z.array(WorkshopWorkflowSchema).optional(),
+		exporters: z.array(WorkshopExporterSchema).optional(),
+		exportPreferences: WorkshopExportPreferencesSchema,
+		exportStructure: WorkshopExportStructureSchema,
+		remoteWorkspace: WorkshopRemoteWorkspaceSchema,
+		difficulty: z.enum(['beginner', 'intermediate', 'advanced']).optional(),
+		templateTier: z.number().int().min(1).max(5).optional(),
+		templateMetadata: WorkshopTemplateMetadataSchema,
+		deploy: WorkshopDeployConfigSchema,
+		sampleData: WorkshopSampleDataSchema
+	})
+	.optional();
+
+/**
+ * Zod schema for validating a Workshop kit manifest.
+ */
+export const WorkshopKitSchema = z
+	.object({
+		id: z
+			.string()
+			.min(1)
+			.max(100)
+			.regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/),
+		type: z.enum(['content', 'app']),
+		name: z.string().min(1).max(200),
+		description: z.string().min(1).max(500),
+		version: z.string().regex(/^\d+\.\d+\.\d+$/),
+		author: KitAuthorSchema,
+		minPlatformVersion: z.string().optional(),
+		tags: z.array(z.string()).optional(),
+		previewImageUrl: z.string().url().optional(),
+		role: z.enum(['primary', 'extension']).optional(),
+		requires: z.array(z.string().min(1).max(100)).optional(),
+		conflicts: z.array(z.string().min(1).max(100)).optional(),
+		variables: z.array(KitVariableSchema).optional(),
+		workshop: WorkshopConfigSchema
+	})
+	.strict();
+
+/** Inferred TypeScript type from the Workshop kit schema. */
+export type WorkshopKitInput = z.infer<typeof WorkshopKitSchema>;
+
+// ──────────────────────────────────────────────
+// Academy kit schema (reserved placeholder)
+// ──────────────────────────────────────────────
+
+/**
+ * Zod schema for validating an Academy kit manifest (reserved placeholder).
+ * The `academy` config block is intentionally permissive to allow future fields
+ * without breaking schema validation as the product design evolves.
+ */
+export const AcademyKitSchema = z
+	.object({
+		id: z
+			.string()
+			.min(1)
+			.max(100)
+			.regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/),
+		type: z.literal('academy'),
+		name: z.string().min(1).max(200),
+		description: z.string().min(1).max(500),
+		version: z.string().regex(/^\d+\.\d+\.\d+$/),
+		author: KitAuthorSchema,
+		minPlatformVersion: z.string().optional(),
+		tags: z.array(z.string()).optional(),
+		previewImageUrl: z.string().url().optional(),
+		variables: z.array(KitVariableSchema).optional(),
+		academy: z.record(z.string(), z.unknown()).optional()
+	})
+	.strict();
+
+/** Inferred TypeScript type from the Academy kit schema. */
+export type AcademyKitInput = z.infer<typeof AcademyKitSchema>;
+
+// ──────────────────────────────────────────────
+// Publish protocol schemas (Workshop → Venue)
+// ──────────────────────────────────────────────
+
+const DocumentPublishContentSchema = z.object({
+	body: z.string().min(1),
+	mimeType: z.enum(['text/markdown', 'text/html']).optional()
+});
+
+const VisualizationPublishContentSchema = z.object({
+	graph: z.object({
+		nodes: z.array(z.object({
+			id: z.string().min(1),
+			label: z.string(),
+			type: z.string(),
+			metadata: z.record(z.string(), z.unknown()).optional()
+		})),
+		edges: z.array(z.object({
+			id: z.string().min(1),
+			from: z.string().min(1),
+			to: z.string().min(1),
+			type: z.string(),
+			metadata: z.record(z.string(), z.unknown()).optional()
+		}))
+	}),
+	viewType: WorkshopExploreViewSchema.optional(),
+	config: z.record(z.string(), z.unknown()).optional()
+});
+
+const SlideshowPublishContentSchema = z.object({
+	slides: z.array(z.string()).min(1),
+	config: z.record(z.string(), z.unknown()).optional()
+});
+
+const StaticPublishContentSchema = z.object({
+	files: z.record(z.string(), z.string()),
+	entryPoint: z.string().min(1)
+});
+
+const AppPublishContentSchema = z.object({
+	bundle: z.string().min(1),
+	sourceMap: z.string().optional(),
+	exportName: z.string().optional()
+});
+
+const PublishPayloadBaseSchema = z.object({
+	kitId: z.string().min(1),
+	title: z.string().min(1).max(500),
+	description: z.string().max(2000).optional(),
+	slug: z.string().min(1).max(100).regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/),
+	version: z.string().regex(/^\d+\.\d+\.\d+$/),
+	sourceWorkshopUserId: z.string().min(1),
+	sourceWorkspaceId: z.string().min(1),
+	deployedAt: z.string().datetime(),
+	/**
+	 * Optional theme catalog ID from `@soulcraft/theme` used to render this content.
+	 * Workshop stores the user's chosen theme here; Venue calls `resolveTheme({ userThemeId })`
+	 * when serving the deployment. `null` means "use the Venue instance's kit theme".
+	 */
+	themeId: z.string().nullable().optional()
+});
+
+/**
+ * Zod schema for validating a Workshop-to-Venue publish payload.
+ *
+ * @example
+ * ```ts
+ * const result = PublishPayloadSchema.safeParse(payload);
+ * if (!result.success) {
+ *   console.error('Invalid publish payload:', result.error.format());
+ * }
+ * ```
+ */
+export const PublishPayloadSchema = z.discriminatedUnion('contentType', [
+	PublishPayloadBaseSchema.extend({
+		contentType: z.literal('document'),
+		content: DocumentPublishContentSchema
+	}),
+	PublishPayloadBaseSchema.extend({
+		contentType: z.literal('visualization'),
+		content: VisualizationPublishContentSchema
+	}),
+	PublishPayloadBaseSchema.extend({
+		contentType: z.literal('slideshow'),
+		content: SlideshowPublishContentSchema
+	}),
+	PublishPayloadBaseSchema.extend({
+		contentType: z.literal('static'),
+		content: StaticPublishContentSchema
+	}),
+	PublishPayloadBaseSchema.extend({
+		contentType: z.literal('app'),
+		content: AppPublishContentSchema
+	})
+]);
+
+/** Inferred TypeScript type from the publish payload schema. */
+export type PublishPayloadInput = z.infer<typeof PublishPayloadSchema>;
+
+// ──────────────────────────────────────────────
+// Unified Soulcraft kit schema
+// ──────────────────────────────────────────────
+
+/** Per-product annotations for a shared data model entity. */
+const SharedDataModelEntityProductsSchema = z.object({
+	workshop: z.object({
+		view: z.string().max(50).optional(),
+		icon: z.string().max(10).optional()
+	}).optional(),
+	venue: z.object({
+		mapsTo: z.string().max(100).optional(),
+		pos: z.boolean().optional(),
+		trackStock: z.boolean().optional()
+	}).optional(),
+	academy: z.object({
+		mapsTo: z.string().max(100).optional(),
+		assessable: z.boolean().optional()
+	}).optional()
+}).optional();
+
+/** Domain entity declaration schema. */
+const SharedDataModelEntitySchema = z.object({
+	domain: z.string().min(1).max(100),
+	type: z.string().min(1).max(100),
+	description: z.string().min(1).max(500),
+	products: SharedDataModelEntityProductsSchema
+});
+
+/** Domain relationship declaration schema. */
+const SharedDataModelRelationshipSchema = z.object({
+	from: z.string().min(1).max(100),
+	to: z.string().min(1).max(100),
+	verb: z.string().min(1).max(100),
+	description: z.string().min(1).max(500),
+	products: z.object({
+		venue: z.object({ triggers: z.string().max(100).optional() }).optional(),
+		academy: z.object({ creates: z.string().max(100).optional() }).optional()
+	}).optional()
+});
+
+/** Unified domain model block schema. */
+const SharedDataModelSchema = z.object({
+	entities: z.array(SharedDataModelEntitySchema).optional(),
+	relationships: z.array(SharedDataModelRelationshipSchema).optional()
+}).optional();
+
+/** Cross-product shared foundation schema. */
+const SharedKitFoundationSchema = z.object({
+	industry: z.string().min(1).max(100),
+	category: z.string().min(1).max(100).optional(),
+	glossary: z.record(z.string(), z.string()).optional(),
+	aiExpertise: z.array(z.string().min(1).max(200)).optional(),
+	dataModelHints: z.array(z.string().min(1).max(100)).optional(),
+	suggestions: z.array(KitSuggestionSchema).optional(),
+	dataModel: SharedDataModelSchema
+}).optional();
+
+/** Base fields common to all kit manifest types, for reuse in discriminated union entries. */
+const BaseKitManifestFields = {
+	$schema: z.string().optional(),
+	id: z.string().min(1).max(100).regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/),
+	name: z.string().min(1).max(200),
+	description: z.string().min(1).max(500),
+	version: z.string().regex(/^\d+\.\d+\.\d+$/),
+	author: KitAuthorSchema,
+	status: z.enum(['released', 'beta', 'draft']).optional(),
+	icon: z.string().max(10).optional(),
+	longDescription: z.string().optional(),
+	allowedUsers: z.array(z.string().min(1).max(500)).optional(),
+	minPlatformVersion: z.string().optional(),
+	tags: z.array(z.string()).optional(),
+	previewImageUrl: z.string().url().optional(),
+	role: z.enum(['primary', 'extension']).optional(),
+	requires: z.array(z.string().min(1).max(100)).optional(),
+	conflicts: z.array(z.string().min(1).max(100)).optional()
+} as const;
+
+/**
+ * Zod schema for validating a unified Soulcraft kit manifest (`type: 'soulcraft'`).
+ *
+ * All product sections (`venue`, `workshop`, `academy`) are optional — a kit
+ * may target only one product or all three. The `shared` block provides cross-product
+ * intelligence (glossary, AI expertise) consumed by all products.
+ *
+ * @example
+ * ```ts
+ * const parsed = SoulcraftKitSchema.parse(rawJson);
+ * // parsed is typed as SoulcraftKitConfig
+ * ```
+ */
+export const SoulcraftKitSchema = z
+	.object({
+		...BaseKitManifestFields,
+		type: z.literal('soulcraft'),
+		variables: z.array(KitVariableSchema).optional(),
+		shared: SharedKitFoundationSchema,
+		venue: VenueConfigSchema.optional(),
+		workshop: WorkshopConfigSchema,
+		academy: z.record(z.string(), z.unknown()).optional()
+	})
+	.strict();
+
+/** Inferred TypeScript type from the Soulcraft unified kit schema. */
+export type SoulcraftKitInput = z.infer<typeof SoulcraftKitSchema>;
+
+/**
+ * Discriminated union schema that validates any Soulcraft kit manifest.
+ *
+ * Selects the appropriate schema based on the `type` field:
+ * - `"venue"` → {@link VenueKitSchema}
+ * - `"content"` | `"app"` → {@link WorkshopKitSchema}
+ * - `"academy"` → {@link AcademyKitSchema}
+ * - `"soulcraft"` → {@link SoulcraftKitSchema}
+ */
+export const KitManifestSchema = z.discriminatedUnion('type', [
+	VenueKitSchema,
+	WorkshopKitSchema.extend({ type: z.literal('content') }),
+	WorkshopKitSchema.extend({ type: z.literal('app') }),
+	AcademyKitSchema,
+	SoulcraftKitSchema
+]);
+
+/** Inferred TypeScript type from the kit manifest union schema. */
+export type KitManifestInput = z.infer<typeof KitManifestSchema>;