npm - @soulcraft/kit-schema - Versions diffs - 2.0.0 - Mend

@soulcraft/kit-schema 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (12) hide show

package/src/types.ts ADDED Viewed

@@ -0,0 +1,2338 @@
+/**
+ * @module @soulcraft/kit-schema/types
+ * @description TypeScript type definitions for the Soulcraft kit manifest format.
+ *
+ * Kits are the unit of customization across all Soulcraft products. A kit bundles
+ * together configuration, content templates, AI skill definitions, and product-specific
+ * extensions that configure a generic platform deployment for a specific vertical.
+ *
+ * The `type` field on every kit manifest is a discriminant that selects the right
+ * product-specific config block:
+ * - `"venue"` — Soulcraft Venue (experience-based businesses: candle studios, cat cafes, etc.)
+ * - `"content"` — Soulcraft Workshop content kit (knowledge management, documents)
+ * - `"app"` — Soulcraft Workshop app kit (runnable SvelteKit applications)
+ * - `"academy"` — Soulcraft Academy (learning/certification platform, reserved)
+ * - `"soulcraft"` — Unified kit spanning all products with optional per-product sections.
+ *   One kit.json transforms Workshop (CREATE), Venue (OPERATE), and Academy (GROW).
+ *
+ * Each kit directory follows this structure:
+ * ```
+ * kits/{kit-id}/
+ * ├── kit.json              # Kit manifest (validated by this package)
+ * ├── files/
+ * │   ├── cms/              # Default CMS content (JSON)
+ * │   ├── emails/           # Notification templates (HTML/text)
+ * │   └── waivers/          # Waiver text templates (Markdown)
+ * └── skills/
+ *     └── {skill-name}/SKILL.md   # AI skill definitions
+ * ```
+ */
+import type { ThemeSeed } from '@soulcraft/theme';
+// ──────────────────────────────────────────────
+// Shared base types
+// ──────────────────────────────────────────────
+/**
+ * Author metadata embedded in a kit manifest.
+ */
+export interface KitAuthor {
+  /** Author display name or organization. */
+  name: string;
+  /** Contact email address. */
+  email?: string;
+  /** Author's website or GitHub URL. */
+  url?: string;
+}
+/**
+ * A suggestion chip for AI assistant interfaces across Soulcraft products.
+ *
+ * Used in Workshop's AI chat intro screen (`shared.suggestions`) and Venue's
+ * customer-facing chatbot. Cross-product unified replacement for the legacy
+ * product-specific suggestion type previously nested under `WorkshopConfig`.
+ *
+ * @example
+ * ```ts
+ * const suggestion: KitSuggestion = {
+ *   label: 'Add a recipe',
+ *   prompt: 'Add a new recipe to my cookbook'
+ * };
+ * ```
+ */
+export interface KitSuggestion {
+  /** Short button text shown on the chip (1–5 words). */
+  label: string;
+  /** Complete sentence the AI acts on when the chip is clicked. */
+  prompt: string;
+}
+/**
+ * A `{{variable}}` that users must fill in during kit installation or onboarding.
+ *
+ * Variables are substituted into kit template files before seeding. The onboarding
+ * wizard renders a form field for each variable defined here.
+ *
+ * @example
+ * ```ts
+ * const variable: KitVariable = {
+ *   key: 'businessName',
+ *   label: 'Business Name',
+ *   description: 'The display name of your business (e.g. "Wicks & Whiskers Charlotte")',
+ *   type: 'string',
+ *   required: true,
+ *   example: 'Wicks & Whiskers Charlotte'
+ * };
+ * ```
+ */
+export interface KitVariable {
+  /** Variable key used in `{{variableKey}}` template substitutions. */
+  key: string;
+  /** Human-readable label shown in the onboarding wizard form. */
+  label: string;
+  /** Explanatory text shown below the form field. */
+  description?: string;
+  /** Input field type, used to render the correct form control. */
+  type: 'string' | 'email' | 'url' | 'phone' | 'timezone' | 'address' | 'color' | 'number';
+  /** Whether this variable must be filled in before installation can proceed. */
+  required?: boolean;
+  /** Placeholder or example value shown in the form field. */
+  example?: string;
+  /** Default value applied when the user leaves the field empty. */
+  default?: string;
+}
+/**
+ * Parsed frontmatter from a `SKILL.md` file.
+ *
+ * Skills teach the AI assistant domain-specific knowledge and capabilities.
+ * Background skills are included in every AI context; invocable skills can be
+ * triggered by name.
+ */
+export interface SkillFrontmatter {
+  /** Unique identifier for this skill within the kit. */
+  id: string;
+  /** Human-readable skill name. */
+  name: string;
+  /** One-line description of what this skill teaches or enables. */
+  description: string;
+  /**
+   * Whether this skill is always active (`"background"`), user-triggered (`"invocable"`),
+   * or injected automatically based on context signals (`"contextual"`).
+   */
+  type: 'background' | 'invocable' | 'contextual';
+  /** Version string for the skill definition. */
+  version?: string;
+  /** Whether this skill requires vision/image analysis capabilities. */
+  requiresVision?: boolean;
+  /** Whether this skill requires access to the business's live Brainy data. */
+  requiresData?: boolean;
+}
+/**
+ * A parsed skill with its frontmatter metadata and body Markdown content.
+ */
+export interface ParsedSkill {
+  /** Resolved filesystem path to the SKILL.md file. */
+  filePath: string;
+  /** Parsed YAML frontmatter from the skill definition. */
+  frontmatter: SkillFrontmatter;
+  /** The body of the SKILL.md file (everything after the frontmatter block). */
+  body: string;
+}
+// ──────────────────────────────────────────────
+// Base kit manifest (product-agnostic fields)
+// ──────────────────────────────────────────────
+/**
+ * A documentation callout for a specific platform feature, surfaced in the admin UI.
+ *
+ * Kit authors use this to explain hardware requirements, external service setup steps,
+ * or other feature-specific information that admins need when enabling a feature.
+ *
+ * @example
+ * ```json
+ * {
+ *   "title": "Compatible Card Readers",
+ *   "body": "This kit uses Stripe Terminal for in-person card payments...",
+ *   "links": [{ "label": "Order from Stripe", "url": "https://dashboard.stripe.com/terminal/hardware" }]
+ * }
+ * ```
+ */
+export interface KitFeatureDoc {
+  /** Short heading shown above the callout body. */
+  title: string;
+  /**
+   * Markdown-formatted body content explaining setup requirements, compatible
+   * hardware, external accounts needed, or any other admin-facing guidance.
+   */
+  body: string;
+  /** Optional links rendered as a list below the body. */
+  links?: Array<{
+    /** Link display text. */
+    label: string;
+    /** Absolute URL. */
+    url: string;
+  }>;
+}
+/**
+ * Base fields shared by all kit manifests regardless of product type.
+ *
+ * Extended by {@link VenueKitConfig}, {@link WorkshopKitConfig},
+ * {@link AcademyKitConfig}, and {@link SoulcraftKitConfig} via the `type` discriminant.
+ */
+export interface BaseKitManifest {
+  /**
+   * JSON Schema URL for editor autocompletion and validation.
+   * @example "https://soulcraft.com/schemas/kit/v2.json"
+   */
+  $schema?: string;
+  /** Unique kebab-case identifier for this kit. @example "wicks-and-whiskers" */
+  id: string;
+  /** Human-readable name. @example "Wicks & Whiskers" */
+  name: string;
+  /** One-line description of the vertical or use case. */
+  description: string;
+  /** Semantic version of this kit definition. @example "1.0.0" */
+  version: string;
+  /** Author or publishing organization. */
+  author: KitAuthor;
+  /**
+   * Release status of this kit. Controls visibility in the kit gallery:
+   * - `'released'` — Publicly available to all users.
+   * - `'beta'` — Restricted to users listed in `allowedUsers`.
+   * - `'draft'` — Hidden from the gallery; only loadable by kit authors.
+   * @default 'released'
+   */
+  status?: 'released' | 'beta' | 'draft';
+  /**
+   * Emoji icon displayed on the kit gallery card and in product selection UIs.
+   * @example "🕯️" | "🍳" | "🎸"
+   */
+  icon?: string;
+  /**
+   * Markdown-formatted extended description for the kit gallery detail view.
+   * Supports headings, bullet lists, and inline code. Used by Workshop's kit
+   * browser and Venue's onboarding wizard.
+   */
+  longDescription?: string;
+  /**
+   * User IDs or email addresses permitted to install this kit when `status` is `'beta'`.
+   * An empty array means the kit is publicly available regardless of status.
+   * Only enforced when {@link status} is `"beta"`.
+   */
+  allowedUsers?: string[];
+  /**
+   * Minimum required platform version. Enforced by the kit loader to prevent
+   * incompatibility between older platform deployments and newer kit features.
+   * @example "1.0.0"
+   */
+  minPlatformVersion?: string;
+  /** Tags used for kit discovery and filtering in the onboarding gallery. */
+  tags?: string[];
+  /**
+   * URL to a screenshot or preview image shown on the kit selection card
+   * during onboarding.
+   */
+  previewImageUrl?: string;
+  /**
+   * Whether this kit is a primary vertical kit or an extension that augments
+   * an already-installed primary kit.
+   *
+   * - `'primary'` — Defines the core identity of the deployment (the vertical).
+   *   Only one primary kit should be active at a time. Provides the base theme,
+   *   experience types, and core feature set.
+   * - `'extension'` — Adds capabilities on top of the primary kit (e.g. loyalty
+   *   program, content studio, franchise ops). Multiple extensions can be active.
+   *   Extensions declare their dependencies via `requires`.
+   *
+   * @default 'primary'
+   */
+  role?: 'primary' | 'extension';
+  /**
+   * Kit IDs that must be installed (and active) before this kit can be activated.
+   * The kit loader validates these at install time; missing dependencies are errors.
+   * Only relevant when `role` is `'extension'`.
+   * @example ["wicks-and-whiskers"] — this extension only works with W&W
+   */
+  requires?: string[];
+  /**
+   * Kit IDs that cannot be active at the same time as this kit.
+   * The kit manager enforces mutual exclusion — activating one automatically
+   * prompts the admin to deactivate conflicting kits.
+   * @example ["retail-store"] — booking-based kit conflicts with retail-only kit
+   */
+  conflicts?: string[];
+  /**
+   * Workshop apps declared by this kit.
+   *
+   * When this kit is activated in a Venue instance, these entries tell Venue's
+   * dynamic loader which Workshop app component to mount at which URL path for
+   * which user roles. Multiple entries can share the same `mountPath` with
+   * different `roles` for role-aware mounting (e.g. rider vs. driver both at `/app`,
+   * but Venue mounts the correct component based on the authenticated user's role).
+   *
+   * Apps are deployed via `POST /api/deploy` from Workshop and then matched
+   * to these declarations by slug. Venue cross-references this list against
+   * live deployments to resolve the correct bundle at mount time.
+   */
+  apps?: KitAppEntry[];
+  /**
+   * Per-feature documentation shown in the admin Kit Management page.
+   *
+   * Keys are feature flag names as they appear in the platform's feature config
+   * (e.g. `"pos"`, `"loyalty"`, `"subscriptions"`). When the corresponding feature
+   * is enabled in an installed kit, this callout appears in the Kit Management
+   * admin page to guide the operator through any required setup.
+   *
+   * @example
+   * ```json
+   * {
+   *   "pos": {
+   *     "title": "Compatible Card Readers",
+   *     "body": "Use Stripe Terminal internet-connected readers: S700, WisePOS E, or WisePad 3.",
+   *     "links": [{ "label": "Order from Stripe", "url": "https://dashboard.stripe.com/terminal/hardware" }]
+   *   }
+   * }
+   * ```
+   */
+  docs?: Record<string, KitFeatureDoc>;
+}
+// ──────────────────────────────────────────────
+// Venue kit (Soulcraft Venue product)
+// ──────────────────────────────────────────────
+/**
+ * Theme seed configuration embedded in a Venue kit manifest.
+ *
+ * Aliased directly to {@link ThemeSeed} from `@soulcraft/theme` so that kit authors
+ * work with the canonical type and any future additions to ThemeSeed automatically
+ * propagate here. All color values use OKLCH notation; fonts are Google Font names.
+ *
+ * @example
+ * ```ts
+ * const theme: VenueKitTheme = {
+ *   primary: 'oklch(0.72 0.15 25)',
+ *   bgBase: 'oklch(0.96 0.02 80)',
+ *   accent: 'oklch(0.80 0.12 75)',
+ *   textPrimary: 'oklch(0.30 0.02 60)',
+ *   displayFont: 'Fraunces',
+ *   bodyFont: 'Inter'
+ * };
+ * ```
+ *
+ * @see {@link ThemeSeed} in `@soulcraft/theme` — the canonical source of truth.
+ */
+export type VenueKitTheme = ThemeSeed;
+/**
+ * Feature flags controlling which platform capabilities are available for a kit.
+ *
+ * When a feature is `false`, the corresponding routes return 404, nav items are
+ * hidden, and admin sections are not rendered. All features default to `false`
+ * unless explicitly enabled.
+ */
+export interface VenueFeatures {
+  /** Enable live animals (kittens, cats) in the lounge. Activates `/kittens` route and session tracking. */
+  animals?: boolean;
+  /** Enable the adoption application workflow. Requires `animals: true`. */
+  adoption?: boolean;
+  /** Enable AI-generated Experience Memory storybooks after each visit. */
+  memories?: boolean;
+  /** Enable customer loyalty program (points, tiers, rewards). */
+  loyalty?: boolean;
+  /** Enable digital and physical gift card sales and redemption. */
+  giftCards?: boolean;
+  /** Enable liability waiver collection before check-in. */
+  waivers?: boolean;
+  /** Enable the public blog and admin blog editor. */
+  blog?: boolean;
+  /** Enable the in-store Point of Sale terminal. */
+  pos?: boolean;
+  /** Enable CMS-managed content pages (About, FAQ, Policies). */
+  cms?: boolean;
+  /** Enable partner/sponsor listings on the About page. */
+  partners?: boolean;
+  /** Enable franchise multi-location management. */
+  franchise?: boolean;
+  /** Enable customer loyalty accounts. */
+  customerAccounts?: boolean;
+  /**
+   * Enable hosting of Workshop-published apps (Svelte component bundles).
+   * Activates the `/apps/{slug}` route and the "Apps & Content" admin section.
+   */
+  apps?: boolean;
+  /**
+   * Enable hosting of Workshop-published documents (markdown/rich text).
+   * Activates the `/docs/{slug}` route and document management in admin.
+   */
+  documents?: boolean;
+  /**
+   * Enable hosting of Workshop-published visualizations (knowledge graphs, mind maps, etc.).
+   * Activates the `/viz/{slug}` route and visualization management in admin.
+   */
+  visualizations?: boolean;
+  /**
+   * Enable WebSocket real-time features for Workshop apps hosted on this instance.
+   *
+   * Required for apps that use `ws.on()` / `ws.emit()` from {@link AppRuntimeContext}.
+   * Activates Venue's WebSocket bridge server, which forwards Brainy entity change
+   * events and custom app events to connected clients.
+   *
+   * Needed for: live dispatch boards, location tracking, in-app chat, real-time
+   * inventory updates, collaborative features.
+   */
+  realtime?: boolean;
+  /**
+   * Enable push/email/SMS notifications via the `notify` prop of {@link AppRuntimeContext}.
+   *
+   * Required for Workshop apps that send notifications to customers or staff.
+   * Venue handles delivery via Resend (email), Twilio (SMS), and Web Push (PWA).
+   * Includes rate limiting, unsubscribe management, and compliance templates.
+   */
+  notifications?: boolean;
+  /**
+   * Enable the public-facing website with CMS-managed pages, blog, and gallery.
+   *
+   * Activates the homepage, `/[page]` CMS routes, `/blog`, and the website admin section.
+   *
+   * **Standalone mode** (without Workshop): uses built-in templates from the kit's
+   * `theme` config — business picks a design template and edits content in Venue admin.
+   *
+   * **With Workshop**: a `website-kit` deployed from Workshop provides custom component
+   * templates and a full design system. Venue's page editor still manages content;
+   * Workshop controls the visual layer. Progressive enhancement — both modes share
+   * the same Brainy content entities.
+   */
+  website?: boolean;
+  /**
+   * Enable recurring subscription billing via Stripe Subscriptions.
+   *
+   * Activates the subscription plan management admin (`/admin/subscriptions`),
+   * customer subscription lifecycle (subscribe, cancel, change plan), and usage
+   * metering endpoints. Required for SaaS, retainer, and membership business models.
+   *
+   * MRR, churn, and ARPU analytics are available in the Financials dashboard
+   * when this feature is enabled.
+   */
+  subscriptions?: boolean;
+  /**
+   * Enable the customer support ticketing system.
+   *
+   * Activates the customer-facing ticket submission portal (`/support`), the
+   * admin ticket queue (`/admin/support`), and the knowledge base (`/help`).
+   * Support tickets are linked to customer accounts for full context.
+   *
+   * Enables the `SupportTicketMeta` and `KnowledgeBaseMeta` entity types
+   * in the data model.
+   */
+  support?: boolean;
+  /**
+   * Enable the built-in analytics pipeline.
+   *
+   * Activates event ingestion (page views, conversions, funnel steps), the
+   * analytics dashboard (`/admin/analytics`), and the `analytics` service
+   * slot on {@link AppServicesContext}. Workshop apps can record domain events
+   * via `services.analytics.track()` — Venue aggregates them for admin reporting.
+   *
+   * Also enables A/B test framework hooks and cohort retention analysis when
+   * combined with `subscriptions`.
+   */
+  analytics?: boolean;
+  /**
+   * Enable outbound webhook delivery to external services.
+   *
+   * Activates the webhook management UI (`/admin/webhooks`), endpoint registration,
+   * event subscription per endpoint, and delivery retry logic with exponential backoff.
+   * Supports Zapier, Slack, custom HTTP endpoints, and any other webhook consumer.
+   *
+   * Venue signs all webhook payloads with HMAC-SHA256 using a per-endpoint secret
+   * for consumer-side verification.
+   */
+  webhooks?: boolean;
+  /**
+   * Enable API key management for third-party integrations.
+   *
+   * Activates the API key admin UI (`/admin/api-keys`), key issuance with
+   * scope-limited permissions, usage tracking, and key revocation. External systems
+   * (scripts, integrations, kiosk devices) authenticate with issued keys.
+   *
+   * Keys are scoped to a subset of Venue's REST API capabilities — no key can
+   * grant more than the issuing admin's own permissions.
+   */
+  apiKeys?: boolean;
+  /**
+   * Enable the scheduled jobs system for time-based automation.
+   *
+   * Activates the job scheduler UI (`/admin/jobs`), cron expression editor, and
+   * job history log. Workshop apps can register named job handlers; Venue's
+   * scheduler calls them on the configured schedule.
+   *
+   * Common uses: daily revenue reports, weekly inventory low-stock digests,
+   * subscription renewal reminders, and automated booking confirmation follow-ups.
+   */
+  scheduledJobs?: boolean;
+}
+/**
+ * Defines a session attribute that staff should log after a booking session.
+ *
+ * Session attribute definitions are declared per experience type in the kit manifest.
+ * The staff UI renders these as a tap-grid of options (for `select`/`multiselect` types)
+ * or a text input (for `text` type) in the post-session log form.
+ *
+ * This generalizes the W&W-specific `candleChoices` pattern across all verticals:
+ * - Canvas & Corks: painting name, skill level, medium, color palette
+ * - Clay & Co: piece type, glaze colors, firing type
+ * - Gather & Grill: dish name, cuisine type, dietary notes
+ *
+ * @example
+ * ```json
+ * {
+ *   "key": "paintingName",
+ *   "label": "Painting Name",
+ *   "type": "text",
+ *   "perGuest": true,
+ *   "required": true
+ * }
+ * ```
+ */
+export interface SessionAttributeDefinition {
+  /**
+   * Unique key matching {@link SessionAttribute.key} in the session log.
+   * Must follow camelCase convention. @example "paintingName"
+   */
+  key: string;
+  /** Human-readable label shown in the staff UI form. @example "Painting Name" */
+  label: string;
+  /**
+   * Input type controlling how the staff UI renders this field:
+   * - `'text'` — free-text entry (name, description)
+   * - `'select'` — single choice from `options` list (skill level, medium)
+   * - `'multiselect'` — multiple choices from `options` list (color palette)
+   */
+  type: 'text' | 'select' | 'multiselect';
+  /**
+   * When `true`, staff logs one value per guest (e.g. painting name per person).
+   * When `false`, one value is logged for the entire booking session (e.g. class theme).
+   */
+  perGuest: boolean;
+  /**
+   * Available options for `'select'` and `'multiselect'` input types.
+   * Not required for `'text'` type.
+   */
+  options?: string[];
+  /** Whether the attribute must be filled in before the session log can be saved. */
+  required?: boolean;
+}
+/**
+ * A bookable experience type defined by the kit.
+ *
+ * These are the template definitions that seed creates `ExperienceMeta` entities
+ * from. The `slug` becomes the entity's `metadata.slug` field.
+ */
+export interface VenueExperienceType {
+  /** URL-safe slug. @example "kandle-experience" */
+  slug: string;
+  /** Display name. @example "Kandle Experience" */
+  name: string;
+  /** Marketing description. */
+  description: string;
+  /** Per-guest price in cents. @example 5500 */
+  priceInCents: number;
+  /** Duration in minutes. @example 90 */
+  durationMinutes: number;
+  /** Minimum guest count. */
+  minGuests: number;
+  /** Maximum guest count. */
+  maxGuests: number;
+  /** Whether guests must sign a waiver. */
+  requiresWaiver: boolean;
+  /** Whether this is a combo of multiple experiences. */
+  isCombo?: boolean;
+  /** Slugs of component experiences (for combos). */
+  componentSlugs?: string[];
+  /** Display sort order. */
+  sortOrder: number;
+  /**
+   * Color for schedule grid color-coding in OKLCH notation.
+   * @example "oklch(0.82 0.10 75)"
+   */
+  color?: string;
+  /** Hero image URL for the storefront card. */
+  imageUrl?: string;
+  /**
+   * Variable per-guest pricing tiers based on party size (e.g. private events).
+   * When present, the booking wizard uses these tiers instead of the flat
+   * {@link priceInCents} rate. Tiers must be listed in ascending `minGuests` order.
+   *
+   * @example
+   * ```json
+   * [
+   *   { "minGuests": 4, "maxGuests": 6, "pricePerPersonInCents": 5500 },
+   *   { "minGuests": 7, "maxGuests": 8, "pricePerPersonInCents": 5000 }
+   * ]
+   * ```
+   */
+  pricingTiers?: Array<{
+    /** Minimum number of guests for this tier (inclusive). */
+    minGuests: number;
+    /** Maximum number of guests for this tier (inclusive). */
+    maxGuests: number;
+    /** Per-person price in cents for this tier. */
+    pricePerPersonInCents: number;
+  }>;
+  /**
+   * Generic post-session attributes staff log for this experience type.
+   *
+   * Used by non-W&W verticals (paint studios, pottery, cooking classes) to capture
+   * experience-specific data without the COGS inventory tracking of `candleChoices`.
+   * The staff UI renders a tap-grid form from these definitions after check-in.
+   *
+   * Leave empty for W&W candle experiences, which use the dedicated `candleChoices` path.
+   */
+  sessionAttributeDefinitions?: SessionAttributeDefinition[];
+}
+/**
+ * An inventory category with display label and icon.
+ */
+export interface VenueInventoryCategory {
+  /** Category identifier used in `InventoryItemMeta.category`. */
+  id: string;
+  /** Human-readable display label. */
+  label: string;
+  /** Optional emoji or icon name for the category. */
+  icon?: string;
+}
+/**
+ * A staff role extension beyond the platform defaults.
+ */
+export interface VenueStaffRole {
+  /** Role identifier. */
+  id: string;
+  /** Display label. */
+  label: string;
+  /** Default capabilities granted to this role. */
+  defaultCapabilities?: string[];
+}
+/**
+ * A suggestion chip shown in the customer-facing AI chatbot widget.
+ */
+export interface VenueChatSuggestion {
+  /** Button label shown to the customer. */
+  label: string;
+  /** Pre-filled message sent when the customer clicks this chip. */
+  message: string;
+  /** Optional emoji decoration for the chip. */
+  emoji?: string;
+}
+/**
+ * A built-in back-office role in the Venue platform.
+ *
+ * These are the three platform-level roles available in the Venue back-office.
+ * Custom roles defined in {@link VenueConfig.staffRoles} use colon-namespaced
+ * strings (e.g. `'staff:driver'`) and are a superset of this type.
+ */
+export type VenueBackOfficeRole = 'staff' | 'manager' | 'owner';
+/**
+ * Who provides a station's back-end route and logic.
+ *
+ * - `'platform'` — Venue provides this route natively. Available to any org
+ *   that enables the associated feature flag; no custom kit logic required.
+ * - `'kit'` — This kit contributes a custom route for this station. In Phase 1
+ *   the route is a built-in Venue SvelteKit page activated only when this kit
+ *   is active. In Phase 4+ the station ships its own `bundle` — a Svelte 5
+ *   component module loaded lazily by the admin shell.
+ */
+export type VenueStationScope = 'platform' | 'kit';
+/**
+ * The deployment context a station is relevant to.
+ *
+ * - `'physical'` — Physical venue with staff, bookings, and on-site operations
+ *   (e.g. candle studio, escape room). Digital-only orgs will not see these.
+ * - `'digital'` — Digital product or service published via Workshop (e.g. SaaS
+ *   app, subscription offering). Physical-only orgs will not see these.
+ * - `'both'` — Relevant to any org regardless of type. Used for shared concerns
+ *   like analytics, notifications, and settings.
+ */
+export type VenueStationContext = 'physical' | 'digital' | 'both';
+/**
+ * A pluggable back-office section contributed by a kit or the Venue platform.
+ *
+ * Stations appear in the Venue admin sidebar under their assigned group.
+ * Each station declares which staff roles can see it, which route it maps to
+ * under `/{org}/admin/`, and whether it applies to physical venues, digital
+ * products, or both. The Venue shell filters visible stations at render time
+ * based on role, context, and active feature flags.
+ *
+ * @example
+ * ```ts
+ * // Platform-provided, physical-only station
+ * const checkin: VenueStation = {
+ *   id: 'staff-checkin', label: 'Check-In', route: 'staff/checkin',
+ *   icon: 'M9 12.75L11.25 15 15 9.75M21 12a9 9 0 11-18 0 9 9 0 0118 0z',
+ *   roles: ['staff', 'manager', 'owner'], scope: 'platform', context: 'physical'
+ * };
+ *
+ * // Kit-contributed station (W&W specific — ships its own bundle in Phase 4)
+ * const kittens: VenueStation = {
+ *   id: 'kittens', label: 'Kittens', route: 'kittens',
+ *   icon: 'M21 8.25c0-2.485-2.099-4.5...',
+ *   roles: ['manager', 'owner'], scope: 'kit', context: 'physical',
+ *   bundle: 'stations/kittens.js', group: 'Operations'
+ * };
+ * ```
+ */
+export interface VenueStation {
+  /** Unique identifier for this station within the kit. */
+  id: string;
+  /** Display label shown in the admin sidebar. */
+  label: string;
+  /**
+   * Route path relative to `/{org}/admin/`.
+   * @example "staff/pos" resolves to "/{org}/admin/staff/pos"
+   * @example "inventory" resolves to "/{org}/admin/inventory"
+   */
+  route: string;
+  /**
+   * SVG `<path>` data for the sidebar icon, sized for a 24×24 viewBox.
+   * The Venue shell wraps this in an `<svg>` element automatically.
+   * Multiple subpaths may be concatenated into a single `d` string.
+   */
+  icon: string;
+  /**
+   * Back-office roles that can see and access this station.
+   * Roles are checked against the authenticated staff member's platform role.
+   */
+  roles: VenueBackOfficeRole[];
+  /**
+   * Who provides this station's route and logic.
+   *
+   * - `'platform'` — The route is a built-in Venue page, always available.
+   * - `'kit'` — Phase 1: the route is a Venue SvelteKit page activated only
+   *   for this kit's vertical. Phase 4+: the station ships its own `bundle`.
+   *
+   * @default 'platform'
+   */
+  scope?: VenueStationScope;
+  /**
+   * The venue context this station applies to.
+   * The shell hides stations whose context doesn't match the org type.
+   * @default 'both'
+   */
+  context?: VenueStationContext;
+  /**
+   * Path to the station's Svelte 5 component module bundle, relative to the
+   * kit's deployed assets directory.
+   *
+   * When present, the Venue admin shell lazy-loads this bundle and mounts the
+   * default-exported component with `{ sdk, config }` props — identical to
+   * how Workshop apps are mounted. When absent, the shell uses the built-in
+   * SvelteKit route at the declared `route` path.
+   *
+   * @example "stations/kittens.js"
+   * @since Phase 4 (kit migration to Svelte 5 modules)
+   */
+  bundle?: string;
+  /**
+   * Optional sidebar group label for grouping related stations.
+   * @example "Staff" | "Operations" | "Business" | "Settings"
+   */
+  group?: string;
+}
+/**
+ * Venue-specific fields in a kit manifest.
+ *
+ * Nested under the `venue` key in the kit.json manifest. These fields configure
+ * the platform for a specific experience-based business vertical.
+ */
+export interface VenueConfig {
+  /** Bookable experience types available at this kind of venue. */
+  experienceTypes: VenueExperienceType[];
+  /** Feature flags controlling which platform capabilities are enabled. */
+  features: VenueFeatures;
+  /**
+   * Default brand theme applied at onboarding (customizable by the business owner).
+   * Optional for extension kits that augment a primary kit without defining a theme.
+   */
+  theme?: VenueKitTheme;
+  /** Inventory categories relevant to this vertical. */
+  inventoryCategories?: VenueInventoryCategory[];
+  /** Additional staff roles beyond the platform defaults (staff, manager, owner). */
+  staffRoles?: VenueStaffRole[];
+  /**
+   * Two-letter booking number prefix.
+   * @example "WW" → booking numbers like "WW-2026-00145"
+   */
+  bookingNumberPrefix?: string;
+  /**
+   * Prefix for the deployment subdomain on the shared hosting tier.
+   * @example "wicks" → "wicks.venue.soulcraft.com"
+   */
+  subdomainPrefix?: string;
+  /** Suggestion chips for the customer-facing AI chatbot. */
+  chatSuggestions?: VenueChatSuggestion[];
+  /**
+   * Default inventory level detection mode for the `/inventory-scan` vision AI skill.
+   *
+   * - `'vision'` — Containers are clear or frosted; AI estimates fill levels from photo automatically.
+   *   Best for: frosted-glass scent bottles (new W&W franchise spec), wine/liquor bottles,
+   *   clear ingredient jars, mixology studios, paint bottles.
+   * - `'manual'` — Containers are opaque (e.g. amber glass); AI reads labels only, then prompts
+   *   staff to tap Full/Half/Low for each item. Used for legacy W&W with existing amber bottles.
+   * - `'hybrid'` — AI auto-detects levels where possible; prompts manual input only for items
+   *   where the liquid line isn't visible. Default for mixed-container setups.
+   *
+   * Staff can always override the mode at scan time regardless of kit default.
+   *
+   * @default 'hybrid'
+   */
+  inventoryLevelDetection?: 'vision' | 'manual' | 'hybrid';
+  /**
+   * Back-office stations contributed by this kit.
+   *
+   * Stations appear in the Venue admin sidebar and map to routes under `/{org}/admin/`.
+   * The Venue shell renders visible stations based on the authenticated staff role.
+   * When omitted, no custom stations are added (the platform's built-in navigation is used).
+   */
+  stations?: VenueStation[];
+}
+/**
+ * A complete Venue kit manifest — the `kit.json` for a Soulcraft Venue kit.
+ *
+ * @example
+ * ```ts
+ * const kit: VenueKitConfig = {
+ *   id: 'wicks-and-whiskers',
+ *   type: 'venue',
+ *   name: 'Wicks & Whiskers',
+ *   description: 'Candle-making + kitten lounge experience platform',
+ *   version: '1.0.0',
+ *   author: { name: 'Soulcraft Labs', email: 'kits@soulcraft.com' },
+ *   variables: [...],
+ *   venue: {
+ *     features: { animals: true, adoption: true, memories: true, ... },
+ *     theme: { primary: 'oklch(0.72 0.15 25)', ... },
+ *     experienceTypes: [...],
+ *   }
+ * };
+ * ```
+ */
+export interface VenueKitConfig extends BaseKitManifest {
+  /** Discriminant identifying this as a Venue kit. */
+  type: 'venue';
+  /** User-configurable variables substituted into template files at onboarding. */
+  variables: KitVariable[];
+  /** Venue-specific configuration block. */
+  venue: VenueConfig;
+}
+// ──────────────────────────────────────────────
+// Workshop kit (Soulcraft Workshop product)
+// ──────────────────────────────────────────────
+/**
+ * Explore view types available in Workshop's ExplorePanel visualization.
+ */
+export type WorkshopExploreView =
+  | 'graph'
+  | 'mindmap'
+  | 'timeline'
+  | 'board'
+  | 'matrix'
+  | 'gallery'
+  | 'calendar'
+  | 'tree'
+  | 'stats'
+  | 'map'
+  | 'dev'
+  | 'app';
+/**
+ * Workspace paradigm presets controlling the first-open experience in Workshop.
+ */
+export type WorkshopWorkspaceParadigm =
+  | 'writer'      // Editor-centric, file tree, word count
+  | 'researcher'  // Graph + Matrix, citations, synthesis
+  | 'planner'     // Calendar + Board, timeline focus
+  | 'developer'   // Code + Graph, dependencies
+  | 'creative'    // Gallery + Graph, visual references
+  | 'analyst'     // Stats + Matrix, data focus
+  | 'builder'     // App-centric, live preview, component tree
+  | 'custom';     // Fully custom configuration
+/**
+ * Workspace layout and view configuration for a Workshop kit's first-open experience.
+ */
+export interface WorkshopWorkspaceConfig {
+  /** Use a preset paradigm (applies sensible defaults). */
+  paradigm?: WorkshopWorkspaceParadigm;
+  /** Which tab opens first: 'edit' (Editor), 'explore' (Visualizations), or 'app' (embedded app view). */
+  defaultTab?: 'edit' | 'explore' | 'app';
+  /** Default view within the Explore tab. */
+  defaultView?: WorkshopExploreView;
+  /** File to open in Editor tab on first load (supports {{variables}}). */
+  defaultFile?: string;
+  /** Fallback files if defaultFile doesn't exist. */
+  fallbackFiles?: string[];
+}
+/**
+ * AI persona giving the assistant domain expertise for a Workshop kit type.
+ */
+export interface WorkshopAIPersona {
+  /** Role description, e.g. "You are an experienced screenwriter..." */
+  role: string;
+  /** Areas of expertise, e.g. ["three-act structure", "character arcs"]. */
+  expertise: string[];
+  /** Interaction style. */
+  tone: 'mentor' | 'editor' | 'collaborator' | 'assistant';
+  /** Things the AI should NOT do, e.g. ["Don't rewrite without asking"]. */
+  avoidances?: string[];
+}
+/**
+ * Domain knowledge that embeds expertise the AI can reference in a Workshop kit.
+ */
+export interface WorkshopDomainKnowledge {
+  /** Term definitions for the domain glossary. */
+  glossary?: Record<string, string>;
+  /** Industry best practices. */
+  conventions?: string[];
+  /** Common mistakes to avoid. */
+  antiPatterns?: string[];
+  /** Format rules for this domain. */
+  formatting?: string[];
+  /** References and external resources. */
+  references?: Array<{
+    title: string;
+    description: string;
+    url?: string;
+  }>;
+}
+/**
+ * A pre-defined workflow the AI can execute within a Workshop kit.
+ */
+export interface WorkshopWorkflow {
+  /** Unique identifier for this workflow. */
+  id: string;
+  /** Display name, e.g. "Develop Character". */
+  name: string;
+  /** What this workflow accomplishes. */
+  description: string;
+  /** Step-by-step instructions for the AI. */
+  steps: string[];
+  /** Required inputs for this workflow. */
+  inputs?: Array<{
+    name: string;
+    description: string;
+    required?: boolean;
+  }>;
+  /** What gets created or modified on completion. */
+  outputs?: string[];
+  /** Keywords that suggest this workflow. */
+  triggers?: string[];
+  /** Whether to auto-run (true) or confirm steps with user (false). */
+  autoExecute?: boolean;
+}
+/**
+ * Guidance for knowledge graph operations within a Workshop kit.
+ */
+export interface WorkshopGraphGuidance {
+  /** When and how to create new concepts. */
+  conceptCreation?: {
+    /** Conditions that trigger concept creation. Optional — typeMapping alone is sufficient. */
+    triggers?: string[];
+    /** Maps domain terms to graph entity types. @example { "character": "person" } */
+    typeMapping: Record<string, string>;
+  };
+  /** Relationship patterns to encourage in the graph. */
+  relationshipPatterns?: Array<{
+    from: string;
+    to: string;
+    verb: string;
+    description: string;
+  }>;
+  /** Graph integrity rules, e.g. "Every character should link to at least one scene". */
+  rules?: string[];
+}
+/**
+ * Quality gates defining what "complete" looks like for a Workshop kit project.
+ */
+export interface WorkshopQualityGates {
+  /** Per-file content requirements. */
+  fileChecks?: Array<{
+    path: string;
+    required?: string[];
+    optional?: string[];
+  }>;
+  /** Project-level requirements. */
+  projectChecks?: string[];
+  /** Requirements that must pass before export/publish. */
+  exportReady?: string[];
+}
+/**
+ * Export handler definition within a Workshop kit.
+ *
+ * The `handler` field references a built-in handler ID (e.g. "manuscript-docx",
+ * "markdown-bundle"). Handler implementations live in Workshop's export registry,
+ * not in this shared package.
+ */
+export interface WorkshopExporter {
+  /** Unique ID for this exporter. */
+  id: string;
+  /** Display name, e.g. "Manuscript (Word)". */
+  name: string;
+  /** What this export produces. */
+  description: string;
+  /** Emoji icon. */
+  icon: string;
+  /** File extension, e.g. "docx", "pdf", "epub". */
+  format: string;
+  /** Export category for grouping in the export dialog. */
+  category: 'manuscript' | 'ebook' | 'archive' | 'web' | 'document' | 'data' | 'presentation' | 'other';
+  /** Built-in handler ID registered in Workshop's export registry. */
+  handler: string;
+}
+/**
+ * Export preferences and defaults for a Workshop kit.
+ */
+export interface WorkshopExportPreferences {
+  /** Default exporter ID to show first in the export dialog. */
+  defaultExporter?: string;
+  /** Kit for output filename (supports {{variables}}). */
+  fileNameTemplate?: string;
+  /** General export instructions shown to the user. */
+  instructions?: string;
+  /** Quality gates that must pass before any export. */
+  globalPrerequisites?: string[];
+}
+/**
+ * Configuration for how to order/combine multiple files when exporting.
+ */
+export interface WorkshopExportStructure {
+  /** How to determine file order: by graph relationships, path, or manual list. */
+  combineStrategy: 'graph-order' | 'path-order' | 'manual';
+  /** Relationship type to use for ordering (e.g. 'precedes') when using graph-order. */
+  orderRelationship?: string;
+  /** Glob patterns for files to include. */
+  includePatterns?: string[];
+  /** Glob patterns for files to exclude. */
+  excludePatterns?: string[];
+  /** Manual file order (when using manual strategy). */
+  fileOrder?: string[];
+}
+/**
+ * Suggestion chip shown on Workshop's AI chat intro screen.
+ *
+ * @deprecated Use {@link KitSuggestion} instead. `WorkshopSuggestion` is now an
+ * alias for the cross-product `KitSuggestion` type. The field has moved from
+ * `WorkshopConfig.suggestions` to `SharedKitFoundation.suggestions`.
+ *
+ * @example
+ * ```json
+ * { "label": "Add a recipe", "prompt": "Add a new recipe to my cookbook" }
+ * ```
+ */
+export type WorkshopSuggestion = KitSuggestion;
+/**
+ * A single field definition in a `manifest.json` config schema.
+ *
+ * `ManifestConfigField` drives Venue's admin config editor for a deployed app.
+ * Venue renders a typed form control for each field and persists the user's values
+ * as the app's runtime config, merging them over the manifest defaults.
+ *
+ * @example
+ * ```ts
+ * const field: ManifestConfigField = {
+ *   type: 'select',
+ *   label: 'Primary Language',
+ *   default: 'en',
+ *   options: ['en', 'es', 'fr'],
+ *   description: 'Default language used by the AI assistant'
+ * };
+ * ```
+ */
+export interface ManifestConfigField {
+  /** Input type — determines the form control rendered in Venue's admin panel. */
+  type: 'string' | 'number' | 'boolean' | 'select';
+  /** Default value applied when the admin has not overridden this field. */
+  default?: string | number | boolean;
+  /** Allowed values for `type: 'select'` fields. */
+  options?: string[];
+  /** Human-readable label shown in Venue's admin config editor. */
+  label?: string;
+  /** Explanatory text shown below the form control. */
+  description?: string;
+}
+/**
+ * Configuration for publishing a Workshop kit's output to Venue.
+ *
+ * When a kit is publishable, Workshop's publish flow calls Venue's `POST /api/deploy`
+ * endpoint with a {@link PublishPayload}. The content type here determines which
+ * renderer Venue uses to serve the published content.
+ *
+ * The three new fields — `permissions`, `configSchema`, `adminConfig` — are used by
+ * Workshop's `buildVenueAppBundle()` to generate `manifest.json` alongside `bundle.js`.
+ * Venue validates permissions at deploy time and uses configSchema to drive its admin
+ * config editor.
+ */
+export interface WorkshopPublishConfig {
+  /** The type of content this kit produces when published to Venue. */
+  contentType: 'app' | 'document' | 'visualization' | 'slideshow' | 'static';
+  /** Whether content from this kit can be published to Venue. @default false */
+  publishable?: boolean;
+  /** Default URL slug for the published content. */
+  defaultSlug?: string;
+  /**
+   * Entry Svelte component for Venue app deployment.
+   * Workshop's buildVenueAppBundle() compiles this component to a single ES module.
+   * Path is relative to the project root (e.g. 'src/App.svelte').
+   * Only applies when contentType is 'app'.
+   * @default 'src/App.svelte'
+   */
+  appEntry?: string;
+  /**
+   * Platform permissions the app requires at runtime.
+   *
+   * Venue validates this list at deploy time and rejects any unknown permission
+   * strings with HTTP 422. At runtime, SDK calls that require a permission not
+   * declared here are rejected with HTTP 403.
+   *
+   * Default permissions by content type (applied when this field is omitted):
+   * - `app`: `['data:read', 'data:write']`
+   * - `document`: `['data:read', 'vfs:read']`
+   * - `static`: `[]` (no runtime permissions)
+   *
+   * @example `['data:read', 'data:write', 'media:read']`
+   */
+  permissions?: string[];
+  /**
+   * Config schema for Venue's admin config editor.
+   *
+   * Each key maps to one admin-editable field. Venue renders a typed form control
+   * for each field and merges admin-set values over the manifest defaults at runtime.
+   * The merged config is passed to the app as the `config` prop via `createSDK()`.
+   *
+   * @example
+   * ```ts
+   * configSchema: {
+   *   theme: { type: 'select', label: 'Color Theme', default: 'light', options: ['light', 'dark'] },
+   *   maxItems: { type: 'number', label: 'Max Items Per Page', default: 20 }
+   * }
+   * ```
+   */
+  configSchema?: Record<string, ManifestConfigField>;
+  /**
+   * Admin panel configuration for this app's Venue presence.
+   *
+   * - `dashboard`: Whether to show a summary dashboard card in Venue admin. @default true for 'app'
+   * - `settings`: Whether to render a settings page driven by `configSchema`. @default true when configSchema is non-empty
+   * - `stations`: Kit-scoped station IDs whose bundles are included in this deploy.
+   *   Each ID maps to `build/stations/{id}.js` in the deploy payload.
+   */
+  adminConfig?: {
+    /** Show a summary dashboard card in Venue admin. @default true for app contentType */
+    dashboard?: boolean;
+    /** Render a settings page driven by configSchema. @default true when configSchema is non-empty */
+    settings?: boolean;
+    /** Kit-scoped station IDs bundled alongside this app. Maps to build/stations/{id}.js */
+    stations?: string[];
+  };
+}
+/**
+ * A pre-built workbench that Workshop creates when connected to a live Venue location.
+ *
+ * Each connected workbench is a named Workshop view scoped to specific entity types
+ * from the live Venue Brainy instance. Defined in `workshop.remoteWorkspace.connectedWorkbenches`
+ * inside `kit.json`.
+ *
+ * @example
+ * ```json
+ * {
+ *   "name": "Order Explorer",
+ *   "view": "graph",
+ *   "entityTypes": ["order", "customer", "product"],
+ *   "description": "Visualize order-to-customer relationships"
+ * }
+ * ```
+ */
+export interface WorkshopConnectedWorkbench {
+  /** Display name shown in Workshop's workbench switcher. */
+  name: string;
+  /**
+   * Explore view type to open for this workbench.
+   * Matches Workshop's ExploreView discriminant.
+   */
+  view: 'graph' | 'mindmap' | 'tree' | 'timeline' | 'board' | 'gallery' | 'stats' | 'matrix' | 'calendar';
+  /**
+   * Brainy entity types to load from the live Venue instance.
+   * Maps to `NounType` values in the connected Brainy graph.
+   */
+  entityTypes: string[];
+  /** Optional description shown below the workbench name. */
+  description?: string;
+}
+/**
+ * Configuration for Workshop's Remote Session mode.
+ *
+ * When a Workshop project has a `.venue-link.json` file (written at deploy time),
+ * Workshop can connect to the live Venue Brainy instance for full read+write access.
+ * The `remoteWorkspace` block defines which workbenches Workshop pre-builds
+ * from that live data.
+ *
+ * Remote Session phases:
+ * - **Phase 1** (`.venue-link.json`): Link file in VFS project root, written at deploy.
+ * - **Phase 2** (Remote Session): WebSocket Brainy proxy — Workshop reads/writes live Venue data.
+ * - **Phase 3** (Hot-patch): `PATCH /api/apps/{slug}/bundle` — push updated bundle without full re-deploy.
+ */
+export interface WorkshopRemoteWorkspace {
+  /**
+   * Workbenches to open automatically when connecting to the live Venue location.
+   * Each workbench queries specific entity types from the Venue Brainy instance.
+   */
+  connectedWorkbenches?: WorkshopConnectedWorkbench[];
+}
+/**
+ * Template identity metadata used by Workshop to recognise and configure kit projects.
+ *
+ * @example
+ * ```json
+ * { "identifyByStructure": true, "runnable": true, "runnableCommand": "npm run dev" }
+ * ```
+ */
+export interface WorkshopTemplateMetadata {
+  /**
+   * When `true`, Workshop infers the project is an existing instance of this kit
+   * by inspecting its file structure rather than requiring an explicit manifest link.
+   */
+  identifyByStructure?: boolean;
+  /** Whether this kit produces a runnable application. */
+  runnable?: boolean;
+  /**
+   * Shell command to start the application locally.
+   * Shown in Workshop's run panel when `runnable` is `true`.
+   * @example "npm run dev"
+   */
+  runnableCommand?: string;
+}
+/**
+ * Cloud deployment configuration for Workshop kits that produce runnable applications.
+ *
+ * @example
+ * ```json
+ * {
+ *   "provider": "cloud-run",
+ *   "buildCommand": "npm run build",
+ *   "outputDir": "build",
+ *   "config": { "port": 3000, "memory": "512Mi" }
+ * }
+ * ```
+ */
+export interface WorkshopDeployConfig {
+  /** Cloud provider identifier. @example "cloud-run" | "vercel" | "netlify" */
+  provider?: string;
+  /** Build command that produces deployable artifacts. @example "npm run build" */
+  buildCommand?: string;
+  /** Output directory for build artifacts. @example "build" | "dist" | ".svelte-kit/output" */
+  outputDir?: string;
+  /** Provider-specific configuration (e.g. memory limits, port, environment vars). */
+  config?: Record<string, unknown>;
+  /** One-click deploy command shown in Workshop's deploy panel. @example "gcloud run deploy" */
+  oneClickCommand?: string;
+}
+/**
+ * A sample entity for pre-populating a Workshop project with demonstration data.
+ *
+ * Entity types correspond to Brainy NounTypes (`document`, `thing`, `person`, `event`, etc.).
+ */
+export interface WorkshopSampleEntity {
+  /** Brainy entity type (NounType). @example "document" | "thing" | "person" | "event" */
+  type: string;
+  /** Display name for the entity. */
+  name: string;
+  /** Arbitrary entity properties stored in Brainy `metadata`. */
+  properties?: Record<string, unknown>;
+}
+/**
+ * A relationship between two sample entities in a Workshop project's seed graph.
+ */
+export interface WorkshopSampleRelationship {
+  /** Name of the source entity (must match a name in the `entities` array). */
+  from: string;
+  /** Relationship verb (VerbType). @example "contains" | "uses" | "precedes" */
+  verb: string;
+  /** Name of the target entity (must match a name in the `entities` array). */
+  to: string;
+}
+/**
+ * Sample data to seed a new Workshop project for demonstration or onboarding.
+ *
+ * When present, Workshop creates these entities and relationships in a new
+ * project's Brainy graph during the "Try with sample data" flow. Sample data
+ * lets new users experience the kit's knowledge graph before adding their own content.
+ *
+ * @example
+ * ```json
+ * {
+ *   "description": "Sample recipes demonstrating the app features",
+ *   "entities": [{ "type": "document", "name": "Pasta Carbonara", "properties": {} }],
+ *   "relationships": [{ "from": "Pasta Carbonara", "verb": "contains", "to": "Spaghetti" }]
+ * }
+ * ```
+ */
+export interface WorkshopSampleData {
+  /** Human-readable description of what this sample dataset represents. */
+  description?: string;
+  /** Entities to create in the new project's Brainy graph. */
+  entities: WorkshopSampleEntity[];
+  /** Relationships to create between the sample entities. */
+  relationships?: WorkshopSampleRelationship[];
+}
+/**
+ * Workshop-specific fields in a kit manifest.
+ *
+ * These fields power Workshop's AI collaboration, workspace configuration,
+ * knowledge graph guidance, export system, and publish-to-Venue flow.
+ * Nested under the `workshop` key in kit.json.
+ */
+export interface WorkshopConfig {
+  /** Workspace layout and first-open experience configuration. */
+  workspaceConfig?: WorkshopWorkspaceConfig;
+  /** Guidance for the AI assistant's knowledge graph operations. */
+  graphGuidance?: WorkshopGraphGuidance;
+  /** Quality gates defining project completion criteria. */
+  qualityGates?: WorkshopQualityGates;
+  /** Configuration for publishing this kit's content to Venue. */
+  publishConfig?: WorkshopPublishConfig;
+  /** AI persona giving the assistant domain expertise for this kit type. */
+  aiPersona?: WorkshopAIPersona;
+  /** Domain knowledge the AI can reference (glossary, conventions, anti-patterns). */
+  domainKnowledge?: WorkshopDomainKnowledge;
+  /** Pre-defined workflows the AI can execute. */
+  workflows?: WorkshopWorkflow[];
+  /** Export handlers available for this kit's content. */
+  exporters?: WorkshopExporter[];
+  /** Export preferences and defaults. */
+  exportPreferences?: WorkshopExportPreferences;
+  /**
+   * Configuration for combining multiple files into a single export
+   * (using knowledge graph for ordering).
+   */
+  exportStructure?: WorkshopExportStructure;
+  /**
+   * Remote Session configuration.
+   * Defines which workbenches Workshop pre-builds when connecting to a live Venue deployment.
+   * Only relevant for `app`-type kits that will be deployed to Venue.
+   */
+  remoteWorkspace?: WorkshopRemoteWorkspace;
+  /**
+   * Experience difficulty level, used in the kit gallery to filter by skill level.
+   * @example 'beginner' | 'intermediate' | 'advanced'
+   */
+  difficulty?: 'beginner' | 'intermediate' | 'advanced';
+  /**
+   * Template quality/completeness tier (1–5). Higher tiers indicate more polished
+   * templates with richer sample data, AI guidance, and export support.
+   * Used by the kit gallery to surface highest-quality templates first.
+   */
+  templateTier?: number;
+  /**
+   * Template identity metadata for structured project recognition and run configuration.
+   * Used by Workshop to detect existing project instances and configure the run panel.
+   */
+  templateMetadata?: WorkshopTemplateMetadata;
+  /**
+   * Cloud deployment configuration for app kits that produce runnable applications.
+   * Drives Workshop's one-click deploy flow.
+   */
+  deploy?: WorkshopDeployConfig;
+  /**
+   * Sample data to pre-populate a new project's knowledge graph for demonstration.
+   * Shown in Workshop's onboarding "Try with sample data" flow.
+   */
+  sampleData?: WorkshopSampleData;
+}
+/**
+ * A Workshop kit manifest — the `kit.json` for a Soulcraft Workshop kit.
+ *
+ * Workshop kits have two types:
+ * - `"content"` — Document/knowledge graph projects (novels, research, knowledge bases)
+ * - `"app"` — Runnable SvelteKit application projects
+ *
+ * @example
+ * ```ts
+ * const kit: WorkshopKitConfig = {
+ *   id: 'novel-writer',
+ *   type: 'content',
+ *   name: 'Novel Writer',
+ *   description: 'Write your novel with AI assistance',
+ *   version: '1.0.0',
+ *   author: { name: 'Soulcraft Labs' },
+ *   variables: [{ key: 'title', label: 'Novel Title', type: 'string', required: true }],
+ *   workshop: {
+ *     workspaceConfig: { paradigm: 'writer', defaultTab: 'edit' },
+ *     suggestions: [
+ *       { label: 'Add a chapter', prompt: 'Add a new chapter to my novel' },
+ *     ],
+ *   }
+ * };
+ * ```
+ */
+export interface WorkshopKitConfig extends BaseKitManifest {
+  /** Discriminant identifying this as a Workshop kit. */
+  type: 'content' | 'app';
+  /** User-configurable variables substituted into template files at project creation. */
+  variables?: KitVariable[];
+  /** Workshop-specific configuration block. */
+  workshop?: WorkshopConfig;
+}
+// ──────────────────────────────────────────────
+// Academy kit (Soulcraft Academy product)
+// ──────────────────────────────────────────────
+/**
+ * Academy-specific configuration block.
+ *
+ * This interface is a reserved placeholder. Academy product design is deferred
+ * until the product vision is clear. Fields for course structure, certification
+ * configuration, and skill trees will be added here in a future release.
+ */
+export interface AcademyConfig {
+  // Reserved for Academy product features.
+  // Course structure, certification config, and skill trees will be defined here.
+}
+/**
+ * An Academy kit manifest — the `kit.json` for a Soulcraft Academy kit.
+ *
+ * Academy is the learning and certification product in the Soulcraft platform.
+ * This type is reserved for future use; internal design is deferred.
+ */
+export interface AcademyKitConfig extends BaseKitManifest {
+  /** Discriminant identifying this as an Academy kit. */
+  type: 'academy';
+  /** User-configurable variables. */
+  variables?: KitVariable[];
+  /** Academy-specific configuration block (reserved, design deferred). */
+  academy?: AcademyConfig;
+}
+// ──────────────────────────────────────────────
+// App Runtime Context (Venue → Workshop app interface)
+// ──────────────────────────────────────────────
+/**
+ * Role specifier for app access control and conditional mounting in Venue.
+ *
+ * Built-in roles correspond to Venue's RBAC system:
+ * - `'public'` — unauthenticated visitors (no login required)
+ * - `'customer'` — authenticated customers with booking history
+ * - `'staff'` — any authenticated staff member
+ * - `'staff:manager'` — managers with elevated admin access
+ *
+ * Custom roles can be defined per-kit in {@link VenueConfig.staffRoles}.
+ * Use colon-namespaced strings for custom roles: `'staff:driver'`, `'staff:barista'`.
+ * The `(string & {})` type preserves string autocompletion for built-in roles
+ * while allowing arbitrary custom role values.
+ */
+export type AppRole =
+  | 'public'
+  | 'customer'
+  | 'staff'
+  | 'staff:manager'
+  | (string & {}); // allow kit-defined custom role strings e.g. 'staff:driver'
+/**
+ * Pricing model declared by a Workshop app for Venue's payment broker.
+ *
+ * Venue acts as a payment broker: it collects from customers via Stripe,
+ * distributes earnings to the business (minus a platform fee), and in future
+ * marketplace mode, to kit authors as well.
+ *
+ * All monetary values are in the smallest currency unit (e.g. cents for USD).
+ */
+export interface AppPricingModel {
+  /** ISO 4217 currency code. @default 'usd' */
+  currency?: string;
+  /** Fixed base price in smallest currency unit. @example 100 = $1.00 */
+  base?: number;
+  /**
+   * Per-use/per-event pricing in smallest currency unit.
+   * @example { per_ride: 15 } means $0.15 per 'ride' event processed.
+   */
+  perUnit?: Record<string, number>;
+  /**
+   * Platform fee percentage retained by Soulcraft. Applied after base + per-unit.
+   * @default 0.05  (5%)
+   */
+  platformFeePercent?: number;
+}
+/**
+ * Declares a Workshop-built app component that is part of a kit.
+ *
+ * When a Venue kit is activated, these entries tell Venue's dynamic loader which
+ * Workshop app to mount at which path for which roles. Multiple entries can share
+ * the same `mountPath` for role-aware mounting — Venue mounts the first entry
+ * whose `roles` includes the authenticated user's role.
+ *
+ * @example
+ * A dispatch kit with three role-aware mounts, two at the same path:
+ * ```json
+ * [
+ *   { "slug": "rider-app",    "roles": ["customer"],      "mountPath": "/app" },
+ *   { "slug": "driver-app",   "roles": ["staff:driver"],  "mountPath": "/app" },
+ *   { "slug": "dispatch-ops", "roles": ["staff:manager"], "mountPath": "/admin/dispatch" }
+ * ]
+ * ```
+ * A customer visiting `/app` sees the rider experience; a logged-in driver sees
+ * their dispatch UI; a manager visits `/admin/dispatch` for the operations board.
+ */
+export interface KitAppEntry {
+  /** Unique slug for this app within the kit. Used to match deployed bundles. */
+  slug: string;
+  /** Human-readable name shown in the admin Apps & Content section. */
+  name: string;
+  /** One-line description. */
+  description?: string;
+  /**
+   * Roles that will see this app mounted at `mountPath`.
+   * Venue resolves the first entry whose roles include the user's current role.
+   */
+  roles: AppRole[];
+  /**
+   * URL path within the Venue instance where this app is mounted.
+   * Multiple entries can share the same path for role-aware mounting.
+   * @example '/app' — primary customer-facing experience
+   * @example '/admin/dispatch' — staff operations board
+   */
+  mountPath: string;
+  /**
+   * Path within the Venue VFS to the compiled ES module bundle.
+   * Populated by Venue after the app is deployed via `POST /api/deploy`.
+   * @example 'deployments/app/rider-app/bundle.js'
+   */
+  bundlePath?: string;
+  /**
+   * Name of the exported Svelte component from the bundle.
+   * @default 'default'
+   */
+  exportName?: string;
+  /**
+   * WebSocket event types this app subscribes to via `ws.on()`.
+   * Venue's WebSocket bridge filters incoming events to only forward
+   * the declared subscription types to this app.
+   * @example ['ride:accepted', 'ride:completed', 'driver:location']
+   */
+  realtimeSubscriptions?: string[];
+  /**
+   * WebSocket event types this app is permitted to emit via `ws.emit()`.
+   * Venue rejects any emitted event not on this allowlist.
+   * @example ['ride:dispatch', 'driver:location:update']
+   */
+  realtimeEmits?: string[];
+  /** Pricing model for Venue's payment broker integration. */
+  pricing?: AppPricingModel;
+}
+/**
+ * Authenticated user identity available to Workshop apps at runtime.
+ * Derived from Venue's better-auth session at mount time.
+ */
+export interface AppAuthContext {
+  /** Currently authenticated user, or null if unauthenticated. */
+  user: {
+    /** Venue user ID (stable, derived from better-auth). */
+    id: string;
+    /** Display name. */
+    name: string;
+    /** Email address. */
+    email: string;
+  } | null;
+  /** The user's role in this Venue instance, or null if unauthenticated. */
+  role: AppRole | null;
+  /**
+   * Returns true if the current user has the given Venue capability string.
+   * Checks against the same capability system as Venue's own admin routes.
+   * @example auth.can('published.manage')
+   */
+  can(capability: string): boolean;
+  /** Sign out the current user and redirect to Venue's login page. */
+  signOut(): Promise<void>;
+}
+/**
+ * WebSocket context for real-time bidirectional communication with Venue.
+ *
+ * Provided by Venue's WebSocket bridge, which forwards Brainy entity change
+ * events and custom app-to-app events. Venue validates all emitted events
+ * against the kit's declared {@link KitAppEntry.realtimeEmits} allowlist.
+ *
+ * Available when {@link VenueFeatures.realtime} is enabled.
+ *
+ * @example
+ * ```ts
+ * // In a Svelte 5 Workshop app:
+ * const unsub = ws.on<{ lat: number; lng: number }>('driver:location', (pos) => {
+ *   updateMarker(pos);
+ * });
+ * onDestroy(unsub); // always clean up subscriptions
+ *
+ * ws.emit('ride:dispatch', { driverId: 'drv-001', rideId: 'ride-123' });
+ * ```
+ */
+export interface AppWebSocketContext {
+  /**
+   * Subscribe to a named event stream.
+   * Returns an unsubscribe function — call it in `onDestroy` to prevent leaks.
+   */
+  on<T = unknown>(event: string, handler: (data: T) => void): () => void;
+  /**
+   * Emit an event to Venue. Only events declared in `realtimeEmits` are permitted;
+   * Venue silently rejects others in development and throws in production.
+   */
+  emit(event: string, data: unknown): void;
+  /** Whether the WebSocket connection is currently open and authenticated. */
+  readonly connected: boolean;
+}
+/**
+ * Venue service layer available to Workshop apps at runtime.
+ *
+ * Provides type-safe access to Venue's operational services. Each service
+ * enforces Venue's business rules, capability checks, and audit trails —
+ * identical to how Venue's own admin UI interacts with the same services.
+ *
+ * Concrete TypeScript types are declared in Venue's service layer
+ * (`apps/web/src/lib/server/services/`). The `unknown` placeholders here
+ * avoid a circular dependency; consuming code in Venue uses the concrete types.
+ *
+ * Services are populated based on which {@link VenueFeatures} are enabled.
+ * Accessing a service slot for a disabled feature throws at runtime with a
+ * descriptive error directing the kit author to enable the feature flag.
+ */
+export interface AppServicesContext {
+  /** Create, read, cancel, and query bookings. */
+  bookings: unknown;
+  /** Charge, refund, and list financial transactions via Stripe. */
+  transactions: unknown;
+  /** List, adjust, and track inventory items. */
+  inventory: unknown;
+  /** Look up, create, and update customer profiles. */
+  customers: unknown;
+  /**
+   * Manage recurring subscription plans and customer subscriptions.
+   * Available when {@link VenueFeatures.subscriptions} is enabled.
+   */
+  subscriptions: unknown;
+  /**
+   * Create, update, and query support tickets and knowledge base articles.
+   * Available when {@link VenueFeatures.support} is enabled.
+   */
+  support: unknown;
+  /**
+   * Earn, redeem, and query loyalty points for customer accounts.
+   * Available when {@link VenueFeatures.loyalty} is enabled.
+   */
+  loyalty: unknown;
+  /**
+   * Record analytics events and query aggregated metrics.
+   * Available when {@link VenueFeatures.analytics} is enabled.
+   *
+   * @example
+   * ```ts
+   * // Record a domain event from a Workshop app:
+   * await services.analytics.track('checkout:completed', {
+   *   value: 4500,
+   *   plan: 'pro',
+   *   userId: auth.user?.id
+   * });
+   * ```
+   */
+  analytics: unknown;
+}
+/**
+ * Claude AI context available to Workshop apps via Venue's Anthropic API key.
+ *
+ * Apps can use AI features — chat, search, generation — without managing their
+ * own API keys. All requests route through Venue's key with rate limiting
+ * applied per Venue instance.
+ */
+export interface AppAIContext {
+  /**
+   * Send a conversation exchange and receive a streaming text response.
+   * @param messages The conversation history.
+   * @param opts Optional system prompt and model ID overrides.
+   * @returns An async iterable of text tokens suitable for streaming display.
+   */
+  chat(
+    messages: Array<{ role: 'user' | 'assistant'; content: string }>,
+    opts?: { system?: string; model?: string }
+  ): AsyncIterable<string>;
+  /**
+   * Generate text embeddings for semantic search or similarity ranking.
+   * @param text Single string or batch of strings.
+   * @returns Array of embedding vectors (one per input string).
+   */
+  embed(text: string | string[]): Promise<number[][]>;
+}
+/**
+ * Venue VFS and CDN file access for Workshop apps.
+ *
+ * Files are stored in a per-app namespace within the Venue VFS.
+ * In production, uploads go to GCS and are served via CDN.
+ * In development, files are served from the local `static/` directory.
+ */
+export interface AppFilesContext {
+  /**
+   * Upload a file to the Venue VFS.
+   * @param file The File or Blob to upload.
+   * @param path Destination path within this app's VFS namespace.
+   * @returns The stable public CDN URL for the uploaded file.
+   */
+  upload(file: File | Blob, path: string): Promise<string>;
+  /**
+   * Read a file from the Venue VFS.
+   * @param path File path within this app's VFS namespace.
+   */
+  read(path: string): Promise<Blob>;
+  /**
+   * Delete a file from the Venue VFS.
+   * @param path File path within this app's VFS namespace.
+   */
+  delete(path: string): Promise<void>;
+  /**
+   * List files under a VFS directory prefix.
+   * @param prefix Directory path prefix within this app's VFS namespace.
+   * @returns Array of matching file paths.
+   */
+  list(prefix: string): Promise<string[]>;
+}
+/**
+ * Notification delivery context for Workshop apps.
+ *
+ * Venue handles delivery infrastructure, queuing, rate limiting, and compliance
+ * (unsubscribe links, CAN-SPAM, TCPA opt-in). Apps declare notification needs
+ * via {@link VenueFeatures.notifications}.
+ *
+ * Email delivery: Resend. SMS: Twilio. Push: Web Push API (requires PWA).
+ */
+export interface AppNotifyContext {
+  /**
+   * Send a transactional email.
+   * @param to Recipient email address.
+   * @param subject Email subject line.
+   * @param body Plain-text email body (auto-generates HTML fallback).
+   * @param opts Optional HTML override and reply-to address.
+   */
+  email(
+    to: string,
+    subject: string,
+    body: string,
+    opts?: { html?: string; replyTo?: string }
+  ): Promise<void>;
+  /**
+   * Send an SMS message via Twilio.
+   * Requires the recipient's phone to be verified and opted in per TCPA rules.
+   * @param to E.164 phone number, e.g. '+17045551234'.
+   * @param message SMS body text (160 chars max for single segment).
+   */
+  sms(to: string, message: string): Promise<void>;
+  /**
+   * Send a Web Push notification to a user's device(s).
+   * Requires the user to have granted push permission via Venue's PWA service worker.
+   * @param userId Venue user ID (may have multiple registered devices).
+   * @param payload Notification title, body text, and optional click-through URL.
+   */
+  push(
+    userId: string,
+    payload: { title: string; body: string; url?: string }
+  ): Promise<void>;
+}
+/**
+ * Full runtime context injected into every Workshop-built app when it mounts in Venue.
+ *
+ * A Workshop app receiving this context is indistinguishable from native Venue code —
+ * it reads and writes the same Brainy database, authenticates the same users, calls
+ * the same operational services, and streams from the same WebSocket bridge.
+ *
+ * This is the central contract between Venue (runtime host) and Workshop (app author).
+ * Changes to this interface are breaking changes for all deployed apps.
+ *
+ * Venue's dynamic loader (Phase 4) constructs and injects this context at mount time.
+ * Workshop's build tooling validates that app components declare compatible prop types.
+ *
+ * @example
+ * ```svelte
+ * <!-- MyWorkshopApp.svelte -->
+ * <script lang="ts">
+ *   import type { AppRuntimeContext } from '@soulcraft/kit-schema';
+ *
+ *   let { brain, auth, kit, ws, services, ai, files, notify, config, slot }: AppRuntimeContext = $props();
+ *
+ *   // Real-time dispatch example:
+ *   const unsub = ws.on<RideAccepted>('ride:accepted', (ride) => mapState.addRide(ride));
+ *   onDestroy(unsub);
+ *
+ *   // AI-powered feature:
+ *   async function suggestRoute() {
+ *     for await (const token of ai.chat([{ role: 'user', content: 'Suggest optimal route' }])) {
+ *       suggestion += token;
+ *     }
+ *   }
+ * </script>
+ * ```
+ */
+export interface AppRuntimeContext {
+  /**
+   * The Venue Brainy instance — identical to the database backing all of Venue's
+   * own features. Apps can freely query, create, update, and delete entities.
+   *
+   * Typed as `unknown` here to avoid a circular dependency on `@soulcraft/brainy`;
+   * import `Brainy` from `@soulcraft/brainy` and cast in consuming code.
+   */
+  brain: unknown;
+  /** Authenticated user identity, role, and Venue capability checks. */
+  auth: AppAuthContext;
+  /** The active kit configuration for this Venue instance. */
+  kit: KitManifest;
+  /**
+   * WebSocket connection to Venue's real-time bridge.
+   * Supports live entity-change streams, dispatch events, in-app chat,
+   * location tracking, and any custom bidirectional event types declared
+   * in the kit's {@link KitAppEntry.realtimeSubscriptions} / {@link KitAppEntry.realtimeEmits}.
+   * Available when {@link VenueFeatures.realtime} is enabled.
+   */
+  ws: AppWebSocketContext;
+  /**
+   * Venue's typed operational service layer — same services as the admin UI.
+   * Bookings, transactions, inventory, customers.
+   */
+  services: AppServicesContext;
+  /**
+   * Claude AI access via Venue's Anthropic API key.
+   * Chat streaming, embeddings, and content generation — no separate key needed.
+   */
+  ai: AppAIContext;
+  /**
+   * Venue VFS and CDN file access.
+   * Upload, read, list, and delete files in this app's VFS namespace.
+   */
+  files: AppFilesContext;
+  /**
+   * Email, SMS, and Web Push notification delivery via Venue's infrastructure.
+   * Available when {@link VenueFeatures.notifications} is enabled.
+   */
+  notify: AppNotifyContext;
+  /**
+   * Admin-configured runtime values for this deployment.
+   *
+   * Keys correspond to entries in the app's `manifest.json` `config` schema
+   * (see {@link ManifestConfigField}). Values are the Venue admin's overrides
+   * merged over the manifest defaults. Absent when the deployment has no config
+   * schema or the admin has not set any overrides.
+   *
+   * Use this for feature flags, API endpoints, display preferences, or any other
+   * per-deployment customization the app author wants to expose to the venue owner.
+   *
+   * @example
+   * ```svelte
+   * <script lang="ts">
+   *   let { config }: AppRuntimeContext = $props();
+   *   const theme = config?.theme ?? 'light';        // 'string' field
+   *   const maxItems = config?.maxItems ?? 10;        // 'number' field
+   *   const showBanner = config?.showBanner ?? true;  // 'boolean' field
+   * </script>
+   * ```
+   */
+  config?: Record<string, string | number | boolean>;
+  /**
+   * The URL mount path this app was loaded at within the Venue instance.
+   * @example '/app' or '/admin/dispatch'
+   */
+  slot?: string;
+}
+// ──────────────────────────────────────────────
+// Publish Protocol (Workshop → Venue deploy API)
+// ──────────────────────────────────────────────
+/**
+ * Content types that Workshop can publish to Venue's deploy API.
+ */
+export type PublishContentType = 'app' | 'document' | 'visualization' | 'slideshow' | 'static';
+/**
+ * Content payload for a document-type deployment.
+ * Stores content inline in Venue's Brainy entity metadata.
+ */
+export interface DocumentPublishContent {
+  /** The document body in markdown or HTML format. */
+  body: string;
+  /** MIME type of the content body. */
+  mimeType?: 'text/markdown' | 'text/html';
+}
+/**
+ * Content payload for a visualization-type deployment (knowledge graphs, mind maps, etc.).
+ */
+export interface VisualizationPublishContent {
+  /** Graph nodes and edges from Workshop's Brainy knowledge graph. */
+  graph: {
+    nodes: Array<{ id: string; label: string; type: string; metadata?: Record<string, unknown> }>;
+    edges: Array<{ id: string; from: string; to: string; type: string; metadata?: Record<string, unknown> }>;
+  };
+  /** Which visualization type to render (graph, mindmap, tree, etc.). */
+  viewType?: WorkshopExploreView;
+  /** Visualization renderer configuration. */
+  config?: Record<string, unknown>;
+}
+/**
+ * Content payload for a slideshow-type deployment.
+ */
+export interface SlideshowPublishContent {
+  /** Slide content as an array of markdown strings (one per slide). */
+  slides: string[];
+  /** Slideshow configuration (theme, transitions, etc.). */
+  config?: Record<string, unknown>;
+}
+/**
+ * Content payload for a static site deployment.
+ */
+export interface StaticPublishContent {
+  /** File map: relative path → base64-encoded file content. */
+  files: Record<string, string>;
+  /** Entry point file path (e.g. "index.html"). */
+  entryPoint: string;
+}
+/**
+ * Content payload for an app-type deployment (Svelte 5 component bundle).
+ *
+ * Workshop compiles app kits into ES module bundles that Venue loads dynamically
+ * via `import()`. The bundle must export a default Svelte 5 component that accepts
+ * the full {@link AppRuntimeContext} as props — giving the app access to Venue's
+ * Brainy instance, authenticated user, operational services, WebSocket, AI, files,
+ * and notification delivery.
+ */
+export interface AppPublishContent {
+  /** ES module bundle as a UTF-8 string. */
+  bundle: string;
+  /** Source map for debugging (optional). */
+  sourceMap?: string;
+  /** The export name of the root component. @default "default" */
+  exportName?: string;
+}
+/**
+ * The content portion of a publish payload, discriminated by `contentType`.
+ *
+ * Use type narrowing on `contentType` to access the typed `content` field:
+ * ```ts
+ * if (payload.contentType === 'document') {
+ *   const { body } = payload.content; // DocumentPublishContent
+ * }
+ * ```
+ */
+export type PublishContentPayload =
+  | { contentType: 'document'; content: DocumentPublishContent }
+  | { contentType: 'visualization'; content: VisualizationPublishContent }
+  | { contentType: 'slideshow'; content: SlideshowPublishContent }
+  | { contentType: 'static'; content: StaticPublishContent }
+  | { contentType: 'app'; content: AppPublishContent };
+/**
+ * The full payload sent from Workshop to Venue's `POST /api/deploy` endpoint.
+ *
+ * Workshop assembles this payload and calls Venue's deploy API with the authenticated
+ * user's SSO token. Venue stores the deployment as a Brainy entity and serves it
+ * at the appropriate route.
+ *
+ * @example
+ * ```ts
+ * const payload: PublishPayload = {
+ *   kitId: 'novel-writer',
+ *   title: 'My Novel',
+ *   slug: 'my-novel',
+ *   version: '1.0.0',
+ *   sourceWorkshopUserId: 'user-abc123',
+ *   sourceWorkspaceId: 'ws-xyz456',
+ *   deployedAt: new Date().toISOString(),
+ *   contentType: 'document',
+ *   content: { body: '# Chapter 1\n\nOnce upon a time...', mimeType: 'text/markdown' },
+ * };
+ * ```
+ */
+export type PublishPayload = {
+  /** The kit that produced this content. */
+  kitId: string;
+  /** Human-readable title for the deployed content. */
+  title: string;
+  /** Optional description shown in Venue's admin. */
+  description?: string;
+  /**
+   * URL-safe slug for routing.
+   * @example "my-novel" → `/docs/my-novel`
+   */
+  slug: string;
+  /** Semantic version of this deployment (for change tracking). */
+  version: string;
+  /** Workshop user ID (for attribution and update authorization). */
+  sourceWorkshopUserId: string;
+  /** Workshop workspace ID this content was created in. */
+  sourceWorkspaceId: string;
+  /** ISO 8601 timestamp of when this deployment was created. */
+  deployedAt: string;
+  /**
+   * Optional theme catalog ID from `@soulcraft/theme` representing the Workshop user's
+   * chosen visual theme for this content. Venue calls `resolveTheme({ userThemeId })` when
+   * rendering the deployment. `null` means inherit the Venue instance's active kit theme.
+   */
+  themeId?: string | null;
+} & PublishContentPayload;
+/**
+ * Response from Venue's `POST /api/deploy` endpoint.
+ */
+export interface PublishResponse {
+  /** Whether the deployment succeeded. */
+  success: boolean;
+  /** The deployment entity ID in Venue's Brainy. Present on success. */
+  deploymentId?: string;
+  /** The public URL where the deployed content is served. Present on success. */
+  url?: string;
+  /** Error message if deployment failed. */
+  error?: string;
+}
+// ──────────────────────────────────────────────
+// Unified Soulcraft kit (spans all products)
+// ──────────────────────────────────────────────
+/**
+ * Cross-product intelligence shared by all three Soulcraft products.
+ *
+ * When a `SoulcraftKitConfig` declares a `shared` block, Workshop uses it to
+ * prime Briggy's domain expertise, Venue uses it to label entities in the admin
+ * UI, and Academy uses it to scaffold training modules.
+ *
+ * This is the single source of industry truth for "install one kit, AI gains
+ * skills everywhere" — the shared glossary and expertise areas propagate to
+ * every product's AI without duplicate configuration.
+ *
+ * @example
+ * ```ts
+ * const shared: SharedKitFoundation = {
+ *   industry: 'saas',
+ *   glossary: { MRR: 'Monthly Recurring Revenue', churn: 'Rate of subscription cancellations' },
+ *   aiExpertise: ['SaaS metrics', 'subscription economics', 'user onboarding', 'pricing strategy'],
+ *   dataModelHints: ['subscription', 'customer', 'transaction', 'usage_event']
+ * };
+ * ```
+ */
+/**
+ * Per-product annotation on a domain entity, declaring how the entity maps
+ * to each product's internal concepts and UI behaviours.
+ */
+export interface SharedDataModelEntityProducts {
+  /** Workshop-specific entity display configuration. */
+  workshop?: {
+    /** Default explore view to use when browsing this entity type. @example "card" | "graph" */
+    view?: string;
+    /** Emoji icon for the entity type in Workshop's graph. */
+    icon?: string;
+  };
+  /** Venue-specific entity mapping for business operations. */
+  venue?: {
+    /** The Venue entity type this domain entity maps to. @example "inventoryItem" | "booking" */
+    mapsTo?: string;
+    /** Whether this entity appears on the Venue POS screen. */
+    pos?: boolean;
+    /** Whether Venue should track stock levels for this entity. */
+    trackStock?: boolean;
+  };
+  /** Academy-specific entity mapping for learning paths. */
+  academy?: {
+    /** The Academy entity type this maps to. @example "lesson" | "module" */
+    mapsTo?: string;
+    /** Whether this entity can be assessed/scored in Academy. */
+    assessable?: boolean;
+  };
+}
+/**
+ * A domain entity declared in `shared.dataModel`.
+ *
+ * Maps a business domain concept (e.g. "recipe") to a Brainy NounType
+ * (e.g. "Document") and declares per-product behaviours.
+ */
+export interface SharedDataModelEntity {
+  /** Business domain name for this entity. @example "recipe" | "booking" | "ingredient" */
+  domain: string;
+  /** Brainy NounType this entity maps to. @example "Document" | "Thing" | "Person" | "Event" */
+  type: string;
+  /** Human-readable description of what this entity represents. */
+  description: string;
+  /** Per-product annotations controlling how this entity surfaces in each product's UI. */
+  products?: SharedDataModelEntityProducts;
+}
+/**
+ * Per-product annotation on a domain relationship.
+ */
+export interface SharedDataModelRelationshipProducts {
+  /** Venue-specific relationship behaviours. */
+  venue?: {
+    /** Business operation triggered by this relationship. @example "inventoryDeduction" */
+    triggers?: string;
+  };
+  /** Academy-specific relationship behaviours. */
+  academy?: {
+    /** Academy concept this relationship creates. @example "prerequisite" */
+    creates?: string;
+  };
+}
+/**
+ * A domain relationship declared in `shared.dataModel`.
+ *
+ * Represents a typed connection between two domain entities.
+ */
+export interface SharedDataModelRelationship {
+  /** Source entity `domain` value. @example "recipe" */
+  from: string;
+  /** Target entity `domain` value. @example "ingredient" */
+  to: string;
+  /** Relationship verb (Brainy VerbType convention). @example "Contains" | "Precedes" */
+  verb: string;
+  /** Human-readable description of what this relationship means. */
+  description: string;
+  /** Per-product annotations for this relationship. */
+  products?: SharedDataModelRelationshipProducts;
+}
+/**
+ * Unified domain model declaration for a kit.
+ *
+ * `shared.dataModel` is the single source of truth for "what domain entities exist in
+ * this kit" — replacing the older scattered `dataModelHints` (string array) and
+ * `workshop.graphGuidance.conceptCreation.typeMapping` (Workshop-specific object).
+ *
+ * One declaration drives all products: Workshop reads it for graph guidance and
+ * AI persona priming; Venue uses it for entity labelling and station auto-generation;
+ * Academy uses it to scaffold training modules.
+ *
+ * @example
+ * ```json
+ * {
+ *   "entities": [
+ *     { "domain": "recipe", "type": "Document", "description": "A cooking recipe",
+ *       "products": { "venue": { "mapsTo": "menuItem", "pos": true } } }
+ *   ],
+ *   "relationships": [
+ *     { "from": "recipe", "to": "ingredient", "verb": "Contains",
+ *       "description": "Recipe uses this ingredient" }
+ *   ]
+ * }
+ * ```
+ */
+export interface SharedDataModel {
+  /** Domain entity declarations. */
+  entities?: SharedDataModelEntity[];
+  /** Domain relationship declarations. */
+  relationships?: SharedDataModelRelationship[];
+}
+export interface SharedKitFoundation {
+  /**
+   * Industry vertical identifier.
+   * Used to categorize kits in the gallery and prime AI domain knowledge.
+   * @example 'creative-experiences' | 'saas' | 'food-beverage' | 'professional-services'
+   */
+  industry: string;
+  /**
+   * Display category used for gallery filtering and discovery.
+   * Shown as a badge on kit cards and used for the category filter sidebar.
+   * @example 'creative' | 'business' | 'games' | 'knowledge' | 'dev'
+   */
+  category?: string;
+  /**
+   * Industry-specific term definitions injected into AI system prompts.
+   * Keys are terms; values are plain-English definitions the AI uses to answer questions.
+   * @example { "MRR": "Monthly Recurring Revenue — monthly subscription revenue excluding one-time charges" }
+   */
+  glossary?: Record<string, string>;
+  /**
+   * Areas of domain expertise the AI should embody across all products.
+   * Injected into Workshop's Briggy persona and Venue's chat context.
+   * @example ["SaaS metrics", "subscription economics", "user onboarding", "pricing strategy"]
+   */
+  aiExpertise?: string[];
+  /**
+   * Brainy entity type IDs that this kit uses heavily.
+   * Hints to the graph engine which entity types to optimize storage for,
+   * and tells Briggy which types to suggest when building the knowledge graph.
+   * @example ["subscription", "customer", "transaction", "usage_event"]
+   */
+  dataModelHints?: string[];
+  /**
+   * Cross-product suggestion chips for AI assistant interfaces.
+   *
+   * In Workshop: shown on the AI chat intro screen (replaces `WorkshopConfig.suggestions`).
+   * In Venue: shown as quick-action chips in the customer-facing chatbot widget.
+   *
+   * Order convention — first 1–2: create/add actions; middle 2–3: domain workflows;
+   * last 1–2: explore/visualize actions.
+   */
+  suggestions?: KitSuggestion[];
+  /**
+   * Unified domain model declaration.
+   *
+   * Single source of truth for all domain entities and relationships in this kit.
+   * Drives Workshop's graph guidance, Venue's entity labelling and station hints,
+   * and Academy's learning path scaffolding.
+   *
+   * Supersedes `dataModelHints` (kept for backward compat) and
+   * `workshop.graphGuidance.conceptCreation.typeMapping` (product-specific override
+   * still works for fine-tuning).
+   *
+   * @see {@link SharedDataModel}
+   */
+  dataModel?: SharedDataModel;
+}
+/**
+ * A complete unified Soulcraft kit manifest — the `kit.json` for a kit that
+ * spans multiple Soulcraft products via optional per-product config blocks.
+ *
+ * The `type: 'soulcraft'` discriminant marks a kit as product-agnostic at its
+ * core. Each product reads only its own section (`workshop`, `venue`, `academy`)
+ * and ignores the others. The `shared` block provides cross-product intelligence
+ * (glossary, AI expertise, industry identity) that enriches all products equally.
+ *
+ * This is the recommended type for new kits targeting more than one product.
+ * Existing `type: 'venue'`, `type: 'content'`, and `type: 'app'` kits continue
+ * to work without changes — the discriminated union is additive, not breaking.
+ *
+ * @example
+ * ```ts
+ * const kit: SoulcraftKitConfig = {
+ *   id: 'saas-app',
+ *   type: 'soulcraft',
+ *   name: 'SaaS Application',
+ *   description: 'Full-stack SaaS platform with subscriptions, CRM, and AI',
+ *   version: '1.0.0',
+ *   role: 'primary',
+ *   author: { name: 'Soulcraft Labs', email: 'kits@soulcraft.com' },
+ *   shared: {
+ *     industry: 'saas',
+ *     aiExpertise: ['SaaS metrics', 'subscription economics'],
+ *   },
+ *   venue: {
+ *     features: { subscriptions: true, customerAccounts: true, support: true },
+ *     theme: { primary: 'oklch(0.55 0.25 250)', bgBase: 'oklch(0.98 0.005 250)' },
+ *     experienceTypes: [],
+ *   },
+ *   workshop: {
+ *     workspaceConfig: { paradigm: 'developer', defaultTab: 'explore' },
+ *     aiPersona: { role: 'Senior SaaS architect', expertise: ['SaaS metrics'], tone: 'collaborator' },
+ *   },
+ * };
+ * ```
+ */
+export interface SoulcraftKitConfig extends BaseKitManifest {
+  /** Discriminant identifying this as a unified multi-product Soulcraft kit. */
+  type: 'soulcraft';
+  /** User-configurable variables substituted into template files at onboarding. */
+  variables?: KitVariable[];
+  /**
+   * Cross-product foundation — industry identity, glossary, and AI expertise.
+   * Consumed by Workshop (Briggy), Venue (UI labels, chat context), and Academy.
+   */
+  shared?: SharedKitFoundation;
+  /**
+   * Venue-specific configuration block.
+   * When present, this kit can be used to configure a Venue deployment.
+   * Absent for Workshop-only or Academy-only kits.
+   */
+  venue?: VenueConfig;
+  /**
+   * Workshop-specific configuration block.
+   * When present, this kit configures a Workshop workspace with the given persona,
+   * workflows, and AI expertise. Absent for Venue-only kits.
+   */
+  workshop?: WorkshopConfig;
+  /**
+   * Academy-specific configuration block.
+   * Reserved for future Academy product integration. Absent until Academy ships.
+   */
+  academy?: AcademyConfig;
+}
+// ──────────────────────────────────────────────
+// Discriminated union
+// ──────────────────────────────────────────────
+/**
+ * Discriminated union of all kit manifest types across the Soulcraft platform.
+ *
+ * Use the `type` field to narrow to the specific manifest variant:
+ *
+ * ```ts
+ * function loadKit(manifest: KitManifest) {
+ *   if (manifest.type === 'venue') {
+ *     // TypeScript narrows to VenueKitConfig
+ *     const { features } = manifest.venue;
+ *   } else if (manifest.type === 'content' || manifest.type === 'app') {
+ *     // TypeScript narrows to WorkshopKitConfig
+ *     const { workshop } = manifest;
+ *   } else if (manifest.type === 'academy') {
+ *     // TypeScript narrows to AcademyKitConfig
+ *   } else if (manifest.type === 'soulcraft') {
+ *     // TypeScript narrows to SoulcraftKitConfig
+ *     const { shared, venue, workshop, academy } = manifest;
+ *   }
+ * }
+ * ```
+ */
+export type KitManifest = VenueKitConfig | WorkshopKitConfig | AcademyKitConfig | SoulcraftKitConfig;