models

type AlertReceiverSpec struct {
	Name string `yaml:"name" json:"name"`
	Type string `yaml:"type" json:"type"` // "email", "slack", "discord", "telegram", "webhook"
}

type AlertingSpec struct {
	// Enabled activates alerting.
	Enabled bool `yaml:"enabled,omitempty" json:"enabled,omitempty"`
	// Receivers lists alert destinations.
	Receivers []AlertReceiverSpec `yaml:"receivers,omitempty" json:"receivers,omitempty"`
}

type AppHealthSpec struct {
	Path string `yaml:"path,omitempty" json:"path,omitempty"`
}

type AppRouteSpec struct {
	Host string `yaml:"host,omitempty" json:"host,omitempty"`
	Auth string `yaml:"auth,omitempty" json:"auth,omitempty"` // login-gateway (default) or public
}

type AppSetupSpec struct {
	Policy string          `yaml:"policy,omitempty" json:"policy,omitempty"`
	Drops  []SetupDropSpec `yaml:"drops,omitempty" json:"drops,omitempty"`
}

type AppSpec struct {
	Kind    string            `yaml:"kind,omitempty" json:"kind,omitempty"`
	Image   string            `yaml:"image,omitempty" json:"image,omitempty"`
	Port    int               `yaml:"port,omitempty" json:"port,omitempty"`
	Route   AppRouteSpec      `yaml:"route,omitempty" json:"route,omitempty"`
	Health  AppHealthSpec     `yaml:"health,omitempty" json:"health,omitempty"`
	Setup   AppSetupSpec      `yaml:"setup,omitempty" json:"setup,omitempty"`
	Env     map[string]string `yaml:"env,omitempty" json:"env,omitempty"`
	Secrets map[string]string `yaml:"secrets,omitempty" json:"secrets,omitempty"`
}

type ApplicationConnectorDef struct {
	Kind          string   `yaml:"kind,omitempty" json:"kind,omitempty"`
	Name          string   `yaml:"name,omitempty" json:"name,omitempty"`
	Owner         string   `yaml:"owner,omitempty" json:"owner,omitempty"`
	Endpoint      string   `yaml:"endpoint,omitempty" json:"endpoint,omitempty"`
	Transport     string   `yaml:"transport,omitempty" json:"transport,omitempty"`
	Auth          string   `yaml:"auth,omitempty" json:"auth,omitempty"`
	NativeProduct bool     `yaml:"nativeProduct,omitempty" json:"nativeProduct,omitempty"`
	Capabilities  []string `yaml:"capabilities,omitempty" json:"capabilities,omitempty"`
}

type ApplicationDef struct {
	Role                  ToolRole                                `yaml:"role" json:"role"`
	DefaultTool           string                                  `yaml:"defaultTool,omitempty" json:"defaultTool,omitempty"`
	Alternatives          []string                                `yaml:"alternatives,omitempty" json:"alternatives,omitempty"`
	Description           string                                  `yaml:"description,omitempty" json:"description,omitempty"`
	Package               string                                  `yaml:"package,omitempty" json:"package,omitempty"`
	DefaultRuntimeProfile string                                  `yaml:"defaultRuntimeProfile,omitempty" json:"defaultRuntimeProfile,omitempty"`
	RuntimeProfiles       map[string]ApplicationRuntimeProfileDef `yaml:"runtimeProfiles,omitempty" json:"runtimeProfiles,omitempty"`
	Connectors            map[string]ApplicationConnectorDef      `yaml:"connectors,omitempty" json:"connectors,omitempty"`
	ProductAPIs           map[string]ApplicationProductAPIDef     `yaml:"productApis,omitempty" json:"productApis,omitempty"`
	RIL                   *ApplicationRILDef                      `yaml:"ril,omitempty" json:"ril,omitempty"`
}

type ApplicationProductAPIDef struct {
	Protocol string `yaml:"protocol,omitempty" json:"protocol,omitempty"`
	BasePath string `yaml:"basePath,omitempty" json:"basePath,omitempty"`
	Auth     string `yaml:"auth,omitempty" json:"auth,omitempty"`
	Purpose  string `yaml:"purpose,omitempty" json:"purpose,omitempty"`
}

type ApplicationRILCapabilityDef struct {
	Mode             string `yaml:"mode,omitempty" json:"mode,omitempty"`
	Authority        string `yaml:"authority,omitempty" json:"authority,omitempty"`
	Source           string `yaml:"source,omitempty" json:"source,omitempty"`
	RequiresApproval bool   `yaml:"requiresApproval,omitempty" json:"requiresApproval,omitempty"`
	Evidence         string `yaml:"evidence,omitempty" json:"evidence,omitempty"`
}

type ApplicationRILDef struct {
	Capabilities map[string]ApplicationRILCapabilityDef `yaml:"capabilities,omitempty" json:"capabilities,omitempty"`
}

type ApplicationRuntimeProfileDef struct {
	DisplayName               string   `yaml:"displayName,omitempty" json:"displayName,omitempty"`
	Description               string   `yaml:"description,omitempty" json:"description,omitempty"`
	Realization               string   `yaml:"realization,omitempty" json:"realization,omitempty"` // oss, control-plane, hybrid, external
	PlacementModes            []string `yaml:"placementModes,omitempty" json:"placementModes,omitempty"`
	Contexts                  []string `yaml:"contexts,omitempty" json:"contexts,omitempty"`
	ManagedServerlessEligible bool     `yaml:"managedServerlessEligible,omitempty" json:"managedServerlessEligible,omitempty"`
	RequiresControlPlane      bool     `yaml:"requiresControlPlane,omitempty" json:"requiresControlPlane,omitempty"`
	RequiresLocalBridge       bool     `yaml:"requiresLocalBridge,omitempty" json:"requiresLocalBridge,omitempty"`
	Notes                     []string `yaml:"notes,omitempty" json:"notes,omitempty"`
}

type BackupDestinationSpec struct {
	Name string `yaml:"name" json:"name"`
	Type string `yaml:"type" json:"type"` // "local", "s3", "b2", "sftp"
	Path string `yaml:"path,omitempty" json:"path,omitempty"`
	// S3-specific fields.
	S3Bucket   string `yaml:"s3Bucket,omitempty" json:"s3Bucket,omitempty"`
	S3Endpoint string `yaml:"s3Endpoint,omitempty" json:"s3Endpoint,omitempty"`
	S3Region   string `yaml:"s3Region,omitempty" json:"s3Region,omitempty"`
	// SFTP-specific fields.
	SFTPHost string `yaml:"sftpHost,omitempty" json:"sftpHost,omitempty"`
	SFTPUser string `yaml:"sftpUser,omitempty" json:"sftpUser,omitempty"`
	SFTPPath string `yaml:"sftpPath,omitempty" json:"sftpPath,omitempty"`
}

type BackupEmergencyExportSpec struct {
	Enabled        *bool                     `yaml:"enabled,omitempty" json:"enabled,omitempty"`
	Mode           string                    `yaml:"mode,omitempty" json:"mode,omitempty"`
	Format         string                    `yaml:"format,omitempty" json:"format,omitempty"`
	Schedule       string                    `yaml:"schedule,omitempty" json:"schedule,omitempty"`
	IncludeClasses []string                  `yaml:"includeClasses,omitempty" json:"includeClasses,omitempty"`
	LargeMediaMode string                    `yaml:"largeMediaMode,omitempty" json:"largeMediaMode,omitempty"`
	Target         *BackupDestinationSpec    `yaml:"target,omitempty" json:"target,omitempty"`
	Manifest       *BackupExportManifestSpec `yaml:"manifest,omitempty" json:"manifest,omitempty"`
}

type BackupExportManifestSpec struct {
	Enabled               *bool `yaml:"enabled,omitempty" json:"enabled,omitempty"`
	IncludeRestoreRunbook *bool `yaml:"includeRestoreRunbook,omitempty" json:"includeRestoreRunbook,omitempty"`
	IncludeChecksums      *bool `yaml:"includeChecksums,omitempty" json:"includeChecksums,omitempty"`
}

type BackupResilienceSpec struct {
	SingleServer      *SingleServerBackupSafetySpec  `yaml:"singleServer,omitempty" json:"singleServer,omitempty"`
	MultiServer       *MultiServerBackupSafetySpec   `yaml:"multiServer,omitempty" json:"multiServer,omitempty"`
	EmergencyExport   *BackupEmergencyExportSpec     `yaml:"emergencyExport,omitempty" json:"emergencyExport,omitempty"`
	ManagedServerless *ManagedServerlessRecoverySpec `yaml:"managedServerless,omitempty" json:"managedServerless,omitempty"`
}

type BackupRetentionSpec struct {
	Daily   int `yaml:"daily,omitempty" json:"daily,omitempty"`
	Weekly  int `yaml:"weekly,omitempty" json:"weekly,omitempty"`
	Monthly int `yaml:"monthly,omitempty" json:"monthly,omitempty"`
	Yearly  int `yaml:"yearly,omitempty" json:"yearly,omitempty"`
}

type BackupSpec struct {
	// Enabled activates backups (default true via CUE).
	Enabled *bool `yaml:"enabled,omitempty" json:"enabled,omitempty"`
	// Engine: "kopia" or transitional "restic-import".
	Engine string `yaml:"engine,omitempty" json:"engine,omitempty"`
	// Backend is a legacy alias for Engine. Only "kopia" and "restic-import"
	// are valid; Restic/Borg/Rclone are no longer active StackKits engines.
	Backend string `yaml:"backend,omitempty" json:"backend,omitempty"`
	// Schedule in cron format (default derived from compute tier).
	Schedule string `yaml:"schedule,omitempty" json:"schedule,omitempty"`
	// DataClasses lists state classes covered by the backup policy.
	DataClasses []string `yaml:"dataClasses,omitempty" json:"dataClasses,omitempty"`
	// Resilience defines recovery layers around the primary Kopia repository.
	Resilience *BackupResilienceSpec `yaml:"resilience,omitempty" json:"resilience,omitempty"`
	// Retention defines how many backups to keep.
	Retention *BackupRetentionSpec `yaml:"retention,omitempty" json:"retention,omitempty"`
	// Destinations lists backup targets.
	Destinations []BackupDestinationSpec `yaml:"destinations,omitempty" json:"destinations,omitempty"`
	// Paths to include in backups.
	Paths []string `yaml:"paths,omitempty" json:"paths,omitempty"`
	// Excludes lists patterns to exclude from backups.
	Excludes []string `yaml:"excludes,omitempty" json:"excludes,omitempty"`
}

type BlockDevice struct {
	Name       string  `json:"name"`
	Path       string  `json:"path"`
	SizeGB     float64 `json:"sizeGB"`
	Type       string  `json:"type"` // "disk", "part"
	Mountpoint string  `json:"mountpoint"`
	FSType     string  `json:"fstype"`
	Model      string  `json:"model"`
	Removable  bool    `json:"removable"`
}

type BootstrapSpec struct {
	Mode                     string `yaml:"mode,omitempty" json:"mode,omitempty"` // legacy/scenario selector: full_auto, guided, minimal, or an explicit install-mode alias
	PlatformPolicy           string `yaml:"platformPolicy,omitempty" json:"platformPolicy,omitempty"`
	ApplicationDefaultPolicy string `yaml:"applicationDefaultPolicy,omitempty" json:"applicationDefaultPolicy,omitempty"`
}

type BrandingSpec struct {
	// Color is the primary brand color (hex, e.g. "#4F46E5").
	Color string `yaml:"color,omitempty" json:"color,omitempty"`
	// DashboardTitle is the title shown on the dashboard.
	DashboardTitle string `yaml:"dashboardTitle,omitempty" json:"dashboardTitle,omitempty"`
}

type BreakGlassConfig struct {
	Enabled        *bool  `yaml:"enabled,omitempty" json:"enabled,omitempty"`
	Scope          string `yaml:"scope,omitempty" json:"scope,omitempty"`
	PocketIDAdmin  *bool  `yaml:"pocketidAdmin,omitempty" json:"pocketidAdmin,omitempty"`
	TinyAuthStatic *bool  `yaml:"tinyauthStatic,omitempty" json:"tinyauthStatic,omitempty"`
	ServerRecovery *bool  `yaml:"serverRecovery,omitempty" json:"serverRecovery,omitempty"`
}

type CloudflareTunnelConfig struct {
	// TunnelName is the Cloudflare tunnel name.
	TunnelName string `yaml:"tunnelName,omitempty" json:"tunnelName,omitempty"`
	// ZeroTrust enables Cloudflare Zero Trust access policies.
	ZeroTrust bool `yaml:"zeroTrust,omitempty" json:"zeroTrust,omitempty"`
}

type CompatibilityTier string

type ComputeSpec struct {
	Tier string `yaml:"tier" json:"tier"` // "low", "standard", "high"
}

type ContainerRuntimeSpec struct {
	// Engine: "docker" (default) or "podman".
	Engine string `yaml:"engine,omitempty" json:"engine,omitempty"`
	// Rootless enables rootless container mode.
	Rootless bool `yaml:"rootless,omitempty" json:"rootless,omitempty"`
	// StorageDriver: "overlay2", "btrfs", "zfs", "vfs".
	StorageDriver string `yaml:"storageDriver,omitempty" json:"storageDriver,omitempty"`
	// DataRoot directory for container data (default "/var/lib/docker").
	DataRoot string `yaml:"dataRoot,omitempty" json:"dataRoot,omitempty"`
	// RegistryMirrors lists Docker registry mirrors.
	RegistryMirrors []string `yaml:"registryMirrors,omitempty" json:"registryMirrors,omitempty"`
	// LogDriver default for containers: "json-file", "journald", etc.
	LogDriver string `yaml:"logDriver,omitempty" json:"logDriver,omitempty"`
}

type DNSSpec struct {
	// Servers lists upstream DNS resolvers (default: ["1.1.1.1", "8.8.8.8"]).
	Servers []string `yaml:"servers,omitempty" json:"servers,omitempty"`
	// LocalResolver enables a local DNS resolver (AdGuard Home, Unbound).
	LocalResolver bool `yaml:"localResolver,omitempty" json:"localResolver,omitempty"`
	// LocalResolverTool selects the local resolver tool ("adguard-home", "unbound").
	LocalResolverTool string `yaml:"localResolverTool,omitempty" json:"localResolverTool,omitempty"`
	// DoH enables DNS-over-HTTPS.
	DoH bool `yaml:"doh,omitempty" json:"doh,omitempty"`
	// DoHUpstream is the DoH upstream URL.
	DoHUpstream string `yaml:"dohUpstream,omitempty" json:"dohUpstream,omitempty"`
}

type DemoDataSpec struct {
	Enabled *bool `yaml:"enabled,omitempty" json:"enabled,omitempty"`
}

type DeploymentState struct {
	StackKit           string             `yaml:"stackkit" json:"stackkit"`
	Mode               string             `yaml:"mode" json:"mode"`
	Status             DeploymentStatus   `yaml:"status" json:"status"`
	LastApplied        time.Time          `yaml:"lastApplied" json:"lastApplied"`
	TofuState          string             `yaml:"tofuState,omitempty" json:"tofuState,omitempty"`
	Services           []ServiceState     `yaml:"services" json:"services"`
	PlatformSystemApps []PlatformAppState `yaml:"platformSystemApps,omitempty" json:"platformSystemApps,omitempty"`
	PlatformApps       []PlatformAppState `yaml:"platformApps,omitempty" json:"platformApps,omitempty"`
	SetupRuns          []SetupRunState    `yaml:"setupRuns,omitempty" json:"setupRuns,omitempty"`

	// KitVersionID, KitSemver, KitChannel are populated by `stackkit apply`
	// and `stackkit kit upgrade` (kit-update-phase-1, ADR-0018). State files
	// written by older CLI versions leave these empty; the upgrade command
	// fails with a clear "re-apply to populate version metadata" message
	// rather than guessing.
	KitVersionID string `yaml:"kitVersionId,omitempty" json:"kitVersionId,omitempty"`
	KitSemver    string `yaml:"kitSemver,omitempty" json:"kitSemver,omitempty"`
	KitChannel   string `yaml:"kitChannel,omitempty" json:"kitChannel,omitempty"`

	// LastSnapshotDir points at .stackkit/snapshots/<ts>-<old-kit>/ — used
	// by `stackkit kit upgrade rollback` as the default --to-snapshot when
	// the operator does not pass one explicitly.
	LastSnapshotDir string `yaml:"lastSnapshotDir,omitempty" json:"lastSnapshotDir,omitempty"`
}

type DeploymentStatus string

type DockerCapabilities struct {
	BridgeNetworking bool   `json:"bridgeNetworking"`
	Iptables         bool   `json:"iptables"`
	StorageDriver    string `json:"storageDriver"`

	// Docker runtime functionality — false when the kernel blocks unshare/namespaces
	// (e.g. OpenVZ containers), making Docker unable to run any containers.
	DockerFunctional bool   `json:"dockerFunctional"`
	RuntimeError     string `json:"runtimeError,omitempty"`

	// VPS environment detection
	VirtualizationType string            `json:"virtualizationType,omitempty"` // "kvm", "openvz", "lxc", "none"
	CompatibilityTier  CompatibilityTier `json:"compatibilityTier,omitempty"`  // "full", "degraded", "incompatible"
	UnshareAvailable   bool              `json:"unshareAvailable"`
	CgroupVersion      string            `json:"cgroupVersion,omitempty"` // "v1", "v2"
	MemoryLimits       bool              `json:"memoryLimits"`            // false when nested Docker cannot apply cgroup memory limits

	// DNS and image pre-pull status (troubleshooting engine)
	DNSWorking      bool     `json:"dnsWorking"`
	DNSFix          string   `json:"dnsFix,omitempty"` // "none", "daemon-json", "host-prepull"
	PrePulledImages []string `json:"prePulledImages,omitempty"`
	PrePullFailed   []string `json:"prePullFailed,omitempty"`

	// Disk space (detected during prepare)
	DiskTotalGB float64 `json:"diskTotalGB,omitempty"`
	DiskAvailGB float64 `json:"diskAvailGB,omitempty"`
	DiskMount   string  `json:"diskMount,omitempty"`   // mount point checked (e.g. "/" or "/var/lib/docker")
	LVMDetected bool    `json:"lvmDetected,omitempty"` // root is on LVM
	LVMExtended bool    `json:"lvmExtended,omitempty"` // auto-extended during prepare

	// Hardware profile (detected during prepare)
	CPUCores int     `json:"cpuCores,omitempty"`
	MemoryGB float64 `json:"memoryGB,omitempty"`

	// Resolved NodeContext from legacy host observation (never native v2 authoring).
	ResolvedContext NodeContext `json:"resolvedContext,omitempty"` // "local", "cloud", "pi"

	// Network environment detection (lower-level detail feeding into context resolution)
	NetworkEnv         NetworkEnvironment `json:"networkEnv,omitempty"`         // "home", "vps", "cloud", "unknown"
	PublicIP           string             `json:"publicIP,omitempty"`           // External IP (empty if detection failed)
	PrivateIP          string             `json:"privateIP,omitempty"`          // LAN/internal IP
	IsNAT              bool               `json:"isNAT,omitempty"`              // true if behind NAT (private/local target)
	HasPublicInterface bool               `json:"hasPublicInterface,omitempty"` // true if a network interface has a public IP directly

	// Block devices and storage resolution
	BlockDevices      []BlockDevice      `json:"blockDevices,omitempty"`
	StorageResolution *StorageResolution `json:"storageResolution,omitempty"`
}

type DriftDetectionSpec struct {
	// Enabled activates drift detection.
	Enabled bool `yaml:"enabled,omitempty" json:"enabled,omitempty"`
	// Schedule in cron format (default "0 */6 * * *").
	Schedule string `yaml:"schedule,omitempty" json:"schedule,omitempty"`
}

type Features struct {
	MultiNode    bool `yaml:"multiNode,omitempty" json:"multiNode,omitempty"`
	VPNOverlay   bool `yaml:"vpnOverlay,omitempty" json:"vpnOverlay,omitempty"`
	PublicAccess bool `yaml:"publicAccess,omitempty" json:"publicAccess,omitempty"`
}

type FirewallRuleSpec struct {
	Port     int    `yaml:"port" json:"port"`
	Protocol string `yaml:"protocol,omitempty" json:"protocol,omitempty"` // "tcp", "udp", "both"
	Source   string `yaml:"source,omitempty" json:"source,omitempty"`     // IP/CIDR or "any"
	Action   string `yaml:"action,omitempty" json:"action,omitempty"`     // "allow", "deny"
	Comment  string `yaml:"comment,omitempty" json:"comment,omitempty"`
}

type FirewallSpec struct {
	// Enabled activates the firewall (default true).
	Enabled *bool `yaml:"enabled,omitempty" json:"enabled,omitempty"`
	// Backend: "ufw", "firewalld", "nftables".
	Backend string `yaml:"backend,omitempty" json:"backend,omitempty"`
	// DefaultInbound policy: "allow" or "deny" (default "deny").
	DefaultInbound string `yaml:"defaultInbound,omitempty" json:"defaultInbound,omitempty"`
	// Rules defines additional firewall rules.
	Rules []FirewallRuleSpec `yaml:"rules,omitempty" json:"rules,omitempty"`
	// RateLimit configures brute-force protection (fail2ban-style).
	RateLimit *RateLimitSpec `yaml:"rateLimit,omitempty" json:"rateLimit,omitempty"`
}

type HeadscaleConfig struct {
	ServerURL       string   `yaml:"serverUrl,omitempty" json:"serverUrl,omitempty"`
	Namespace       string   `yaml:"namespace,omitempty" json:"namespace,omitempty"`
	ExitNode        bool     `yaml:"exitNode,omitempty" json:"exitNode,omitempty"`
	AdvertiseRoutes []string `yaml:"advertiseRoutes,omitempty" json:"advertiseRoutes,omitempty"`
}

type HealthStatus string

type IdentitySpec struct {
	// AuthMode overrides the default TinyAuth auth mode (e.g. "passkeys_plus_legacy").
	AuthMode string `yaml:"authMode,omitempty" json:"authMode,omitempty"`
	// SecondUserEmail is an optional second admin user email.
	SecondUserEmail string `yaml:"secondUserEmail,omitempty" json:"secondUserEmail,omitempty"`
	// OIDCProvider selects the OIDC provider ("pocketid" default, or external).
	OIDCProvider string `yaml:"oidcProvider,omitempty" json:"oidcProvider,omitempty"`
	// LDAPEnabled enables LLDAP for directory services.
	LDAPEnabled *bool `yaml:"ldapEnabled,omitempty" json:"ldapEnabled,omitempty"`
	// LDAPOrganization sets the LDAP organization name.
	LDAPOrganization string `yaml:"ldapOrganization,omitempty" json:"ldapOrganization,omitempty"`
}

type InstanceRegistration struct {
	InstanceID  string        `json:"instance_id"`        // Unique instance identifier (device fingerprint + stackkit name)
	EndpointURL string        `json:"endpoint_url"`       // Public URL where stackkit-server is reachable (e.g. https://api.mylab.kombify.me)
	StackKit    string        `json:"stackkit"`           // StackKit name (e.g. "basement-kit")
	Version     string        `json:"version,omitempty"`  // StackKit version
	Services    []ServiceInfo `json:"services"`           // Running services
	Status      string        `json:"status"`             // "running", "degraded", "stopped"
	APIPort     int           `json:"api_port,omitempty"` // Port stackkit-server listens on
	LastSeen    time.Time     `json:"last_seen"`          // Last heartbeat timestamp
}

type KitMetadata struct {
	Name        string   `yaml:"name" json:"name"`
	Version     string   `yaml:"version" json:"version"`
	DisplayName string   `yaml:"displayName,omitempty" json:"displayName,omitempty"`
	Description string   `yaml:"description,omitempty" json:"description,omitempty"`
	Summary     string   `yaml:"summary,omitempty" json:"summary,omitempty"`
	Author      string   `yaml:"author,omitempty" json:"author,omitempty"`
	License     string   `yaml:"license,omitempty" json:"license,omitempty"`
	Homepage    string   `yaml:"homepage,omitempty" json:"homepage,omitempty"`
	Repository  string   `yaml:"repository,omitempty" json:"repository,omitempty"`
	Maturity    string   `yaml:"maturity,omitempty" json:"maturity,omitempty"`
	Status      string   `yaml:"status,omitempty" json:"status,omitempty"`
	Tags        []string `yaml:"tags,omitempty" json:"tags,omitempty"`
}

type LoggingSpec struct {
	// Driver: "json-file", "journald", "loki", "none".
	Driver string `yaml:"driver,omitempty" json:"driver,omitempty"`
	// Level: "debug", "info", "warn", "error".
	Level string `yaml:"level,omitempty" json:"level,omitempty"`
	// MaxSize per log file (e.g. "50m").
	MaxSize string `yaml:"maxSize,omitempty" json:"maxSize,omitempty"`
	// MaxFile count of rotated log files.
	MaxFile int `yaml:"maxFile,omitempty" json:"maxFile,omitempty"`
}

type ManagedServerlessRecoverySpec struct {
	Enabled                    *bool    `yaml:"enabled,omitempty" json:"enabled,omitempty"`
	NoServerDependency         *bool    `yaml:"noServerDependency,omitempty" json:"noServerDependency,omitempty"`
	Authority                  string   `yaml:"authority,omitempty" json:"authority,omitempty"`
	ProtectedClasses           []string `yaml:"protectedClasses,omitempty" json:"protectedClasses,omitempty"`
	ControlPlaneSnapshot       *bool    `yaml:"controlPlaneSnapshot,omitempty" json:"controlPlaneSnapshot,omitempty"`
	ProviderNativeBackups      *bool    `yaml:"providerNativeBackups,omitempty" json:"providerNativeBackups,omitempty"`
	RequireProviderDataHandles *bool    `yaml:"requireProviderDataHandles,omitempty" json:"requireProviderDataHandles,omitempty"`
	RequireRebuildIntent       *bool    `yaml:"requireRebuildIntent,omitempty" json:"requireRebuildIntent,omitempty"`
	PortableManifest           *bool    `yaml:"portableManifest,omitempty" json:"portableManifest,omitempty"`
	PreChangeSnapshot          *bool    `yaml:"preChangeSnapshot,omitempty" json:"preChangeSnapshot,omitempty"`
	Schedule                   string   `yaml:"schedule,omitempty" json:"schedule,omitempty"`
}

type MetricsSpec struct {
	// Enabled activates metrics collection.
	Enabled *bool `yaml:"enabled,omitempty" json:"enabled,omitempty"`
	// Backend: "prometheus", "victoriametrics", "none".
	Backend string `yaml:"backend,omitempty" json:"backend,omitempty"`
	// ScrapeInterval (e.g. "15s").
	ScrapeInterval string `yaml:"scrapeInterval,omitempty" json:"scrapeInterval,omitempty"`
	// Retention period (e.g. "15d", "30d").
	Retention string `yaml:"retention,omitempty" json:"retention,omitempty"`
}

type ModeSpec struct {
	Name        string `yaml:"name" json:"name"`
	Description string `yaml:"description" json:"description"`
	Engine      string `yaml:"engine" json:"engine"` // "opentofu" or "terramate"
	Default     bool   `yaml:"default,omitempty" json:"default,omitempty"`
}

type Modes struct {
	Bare         ModeSpec `yaml:"bare,omitempty" json:"bare,omitempty"`
	Bootstrapped ModeSpec `yaml:"bootstrapped,omitempty" json:"bootstrapped,omitempty"`
	Simple       ModeSpec `yaml:"simple,omitempty" json:"simple,omitempty"`
	Advanced     ModeSpec `yaml:"advanced,omitempty" json:"advanced,omitempty"`
}

type MultiServerBackupMediaSpec struct {
	DocumentsMode           string `yaml:"documentsMode,omitempty" json:"documentsMode,omitempty"`
	PhotosMode              string `yaml:"photosMode,omitempty" json:"photosMode,omitempty"`
	LargeMediaMode          string `yaml:"largeMediaMode,omitempty" json:"largeMediaMode,omitempty"`
	ExcludeGeneratedCaches  *bool  `yaml:"excludeGeneratedCaches,omitempty" json:"excludeGeneratedCaches,omitempty"`
	RequireExternalMediaMap *bool  `yaml:"requireExternalMediaMap,omitempty" json:"requireExternalMediaMap,omitempty"`
}

type MultiServerBackupPerformanceSpec struct {
	Profile                    string `yaml:"profile,omitempty" json:"profile,omitempty"`
	AvoidPrimaryOnlySnapshots  *bool  `yaml:"avoidPrimaryOnlySnapshots,omitempty" json:"avoidPrimaryOnlySnapshots,omitempty"`
	StaggerNodeSnapshots       *bool  `yaml:"staggerNodeSnapshots,omitempty" json:"staggerNodeSnapshots,omitempty"`
	MaxConcurrentNodeSnapshots int    `yaml:"maxConcurrentNodeSnapshots,omitempty" json:"maxConcurrentNodeSnapshots,omitempty"`
	PreferRepoServerFanIn      *bool  `yaml:"preferRepoServerFanIn,omitempty" json:"preferRepoServerFanIn,omitempty"`
}

type MultiServerBackupSafetySpec struct {
	Enabled                      *bool                             `yaml:"enabled,omitempty" json:"enabled,omitempty"`
	Topology                     string                            `yaml:"topology,omitempty" json:"topology,omitempty"`
	MinServers                   int                               `yaml:"minServers,omitempty" json:"minServers,omitempty"`
	MinManagers                  int                               `yaml:"minManagers,omitempty" json:"minManagers,omitempty"`
	QuorumSize                   int                               `yaml:"quorumSize,omitempty" json:"quorumSize,omitempty"`
	ToleratedManagerFailures     int                               `yaml:"toleratedManagerFailures,omitempty" json:"toleratedManagerFailures,omitempty"`
	CapacityHeadroomNodes        int                               `yaml:"capacityHeadroomNodes,omitempty" json:"capacityHeadroomNodes,omitempty"`
	ReleaseReadyHA               *bool                             `yaml:"releaseReadyHA,omitempty" json:"releaseReadyHA,omitempty"`
	CoordinationMode             string                            `yaml:"coordinationMode,omitempty" json:"coordinationMode,omitempty"`
	RequireOffsiteRepo           *bool                             `yaml:"requireOffsiteRepo,omitempty" json:"requireOffsiteRepo,omitempty"`
	RequireEmergencyExport       *bool                             `yaml:"requireEmergencyExport,omitempty" json:"requireEmergencyExport,omitempty"`
	RequireRestoreDrill          *bool                             `yaml:"requireRestoreDrill,omitempty" json:"requireRestoreDrill,omitempty"`
	RequireSharedVolumeInventory *bool                             `yaml:"requireSharedVolumeInventory,omitempty" json:"requireSharedVolumeInventory,omitempty"`
	RequirePlacementSpread       *bool                             `yaml:"requirePlacementSpread,omitempty" json:"requirePlacementSpread,omitempty"`
	RequireManagedServerlessPlan *bool                             `yaml:"requireManagedServerlessPlan,omitempty" json:"requireManagedServerlessPlan,omitempty"`
	Media                        *MultiServerBackupMediaSpec       `yaml:"media,omitempty" json:"media,omitempty"`
	Performance                  *MultiServerBackupPerformanceSpec `yaml:"performance,omitempty" json:"performance,omitempty"`
}

type NetworkEnvironment string

type NetworkSpec struct {
	Mode    string `yaml:"mode" json:"mode"` // "local", "public", "hybrid"
	Subnet  string `yaml:"subnet,omitempty" json:"subnet,omitempty"`
	Gateway string `yaml:"gateway,omitempty" json:"gateway,omitempty"`
	// MTU for the Docker network (default 1500).
	MTU int `yaml:"mtu,omitempty" json:"mtu,omitempty"`
	// IPv6 enables IPv6 on the Docker network.
	IPv6 bool `yaml:"ipv6,omitempty" json:"ipv6,omitempty"`
}

type NodeContext string

type NodeOSSpec struct {
	// Family: "debian" or "rhel".
	Family string `yaml:"family,omitempty" json:"family,omitempty"`
	// Distro: "ubuntu", "debian", "rocky", "alma".
	Distro string `yaml:"distro,omitempty" json:"distro,omitempty"`
	// Version of the distro (e.g. "24.04").
	Version string `yaml:"version,omitempty" json:"version,omitempty"`
}

type NodeSpec struct {
	Name     string   `yaml:"name" json:"name"`
	Role     string   `yaml:"role" json:"role"` // "main", "worker", "storage"; aliases: "control-plane", "standalone"
	IP       string   `yaml:"ip" json:"ip"`
	Host     string   `yaml:"host,omitempty" json:"host,omitempty"` // hostname or FQDN
	Services []string `yaml:"services,omitempty" json:"services,omitempty"`
	// Per-node compute resources (from CUE #ComputeResources).
	CPUCores  int `yaml:"cpuCores,omitempty" json:"cpuCores,omitempty"`
	RAMGB     int `yaml:"ramGB,omitempty" json:"ramGB,omitempty"`
	StorageGB int `yaml:"storageGB,omitempty" json:"storageGB,omitempty"`
	// OS configuration for the node.
	OS *NodeOSSpec `yaml:"os,omitempty" json:"os,omitempty"`
}

type ObservabilitySpec struct {
	// Logging configuration.
	Logging *LoggingSpec `yaml:"logging,omitempty" json:"logging,omitempty"`
	// Metrics configuration.
	Metrics *MetricsSpec `yaml:"metrics,omitempty" json:"metrics,omitempty"`
	// Alerting configuration.
	Alerting *AlertingSpec `yaml:"alerting,omitempty" json:"alerting,omitempty"`
}

type OwnerAdminBootstrapEnvelope struct {
	Owner                   OwnerConfig      `yaml:"owner,omitempty" json:"owner,omitempty"`
	AdminEmail              string           `yaml:"adminEmail,omitempty" json:"adminEmail,omitempty"`
	AdminUsername           string           `yaml:"adminUsername,omitempty" json:"adminUsername,omitempty"`
	AdminCredentialRef      string           `yaml:"adminCredentialRef,omitempty" json:"adminCredentialRef,omitempty"`
	RecoveryMaterialRef     string           `yaml:"recoveryMaterialRef,omitempty" json:"recoveryMaterialRef,omitempty"`
	RecoveryPassphraseHash  string           `yaml:"recoveryPassphraseHash,omitempty" json:"recoveryPassphraseHash,omitempty"`
	RecoveryPassphrasePlain string           `yaml:"-" json:"recoveryPassphrasePlain,omitempty"`
	BreakGlass              BreakGlassConfig `yaml:"breakGlass,omitempty" json:"breakGlass,omitempty"`
}

type OwnerConfig struct {
	// BootstrapMode selects how owner identity is prepared: "auto", "custom",
	// or "none". Empty preserves legacy specs; a non-empty Source with no
	// BootstrapMode resolves to custom(local) or auto(cloud).
	BootstrapMode string `yaml:"bootstrapMode,omitempty" json:"bootstrapMode,omitempty"`

	// Source selects the provisioning path: "local" for custom self-hosted
	// bootstrap or "cloud" for orchestrator-managed auto bootstrap.
	Source string `yaml:"source,omitempty" json:"source,omitempty"`

	// Email is the owner's address. Required only for custom bootstrap.
	Email string `yaml:"email,omitempty" json:"email,omitempty"`

	// Username is the PocketID login handle. Required only for custom bootstrap.
	Username string `yaml:"username,omitempty" json:"username,omitempty"`

	// DisplayName is rendered in PocketID's UI; defaults to Username when empty.
	DisplayName string `yaml:"displayName,omitempty" json:"displayName,omitempty"`

	// RecoveryPassphraseHash is the argon2id-PHC hash of the recovery
	// passphrase used to encrypt the break-glass bundle. Required when Source
	// is non-empty; the plaintext is re-prompted at apply-time.
	RecoveryPassphraseHash string `yaml:"recoveryPassphraseHash,omitempty" json:"recoveryPassphraseHash,omitempty"`

	// RecoveryMaterialRef points at orchestrator-owned recovery material. It is
	// a reference only; plaintext recovery passphrases do not belong in specs.
	RecoveryMaterialRef string `yaml:"recoveryMaterialRef,omitempty" json:"recoveryMaterialRef,omitempty"`

	// CloudOIDCIssuer is the URL of the external OIDC issuer for auto/cloud
	// owner bootstrap.
	CloudOIDCIssuer string `yaml:"cloudOidcIssuer,omitempty" json:"cloudOidcIssuer,omitempty"`

	// CloudOIDCClientID is the registered client ID at the cloud OIDC issuer.
	CloudOIDCClientID string `yaml:"cloudOidcClientId,omitempty" json:"cloudOidcClientId,omitempty"`

	// CloudOIDCClientSecretRef is a secret-store reference (e.g. doppler:// or
	// secret://) pointing at the OIDC client secret. The literal secret is
	// never persisted in the spec.
	CloudOIDCClientSecretRef string `yaml:"cloudOidcClientSecretRef,omitempty" json:"cloudOidcClientSecretRef,omitempty"`

	// CloudOIDCForeignSubject is the cloud user's stable subject ID at the
	// external IdP. PocketID uses it to federate the local owner record.
	CloudOIDCForeignSubject string `yaml:"cloudOidcForeignSubject,omitempty" json:"cloudOidcForeignSubject,omitempty"`
}

type PangolinTunnelConfig struct {
	// ServerDomain is the Pangolin server domain.
	ServerDomain string `yaml:"serverDomain,omitempty" json:"serverDomain,omitempty"`
}

type PlacementSpec struct {
	Mode     string `yaml:"mode,omitempty" json:"mode,omitempty"`
	Exposure string `yaml:"exposure,omitempty" json:"exposure,omitempty"`
	Coupling string `yaml:"coupling,omitempty" json:"coupling,omitempty"`
}

type PlatformAppState struct {
	Name           string          `yaml:"name" json:"name"`
	Role           string          `yaml:"role,omitempty" json:"role,omitempty"`
	Platform       string          `yaml:"platform" json:"platform"`
	Management     string          `yaml:"management,omitempty" json:"management,omitempty"`
	ExternalID     string          `yaml:"externalId" json:"externalId"`
	DeploymentID   string          `yaml:"deploymentId,omitempty" json:"deploymentId,omitempty"`
	ObservedStatus string          `yaml:"observedStatus,omitempty" json:"observedStatus,omitempty"`
	ObservedAt     time.Time       `yaml:"observedAt,omitempty" json:"observedAt,omitempty"`
	ComposePath    string          `yaml:"composePath,omitempty" json:"composePath,omitempty"`
	SetupPolicy    string          `yaml:"setupPolicy,omitempty" json:"setupPolicy,omitempty"`
	SetupDrops     []SetupDropSpec `yaml:"setupDrops,omitempty" json:"setupDrops,omitempty"`
	LastDeployed   time.Time       `yaml:"lastDeployed,omitempty" json:"lastDeployed,omitempty"`
	FailureStage   string          `yaml:"failureStage,omitempty" json:"failureStage,omitempty"`
	FailureMessage string          `yaml:"failureMessage,omitempty" json:"failureMessage,omitempty"`
	Retryable      bool            `yaml:"retryable,omitempty" json:"retryable,omitempty"`
}

type PlatformDef struct {
	Role         ToolRole `yaml:"role" json:"role"`
	DefaultTool  string   `yaml:"defaultTool,omitempty" json:"defaultTool,omitempty"`
	Alternatives []string `yaml:"alternatives,omitempty" json:"alternatives,omitempty"`
}

type PlatformFallbackSpec struct {
	Enabled bool   `yaml:"enabled,omitempty" json:"enabled,omitempty"`
	Mode    string `yaml:"mode,omitempty" json:"mode,omitempty"` // disabled or standalone-compose
}

type RateLimitSpec struct {
	Enabled    bool `yaml:"enabled,omitempty" json:"enabled,omitempty"`
	MaxRetries int  `yaml:"maxRetries,omitempty" json:"maxRetries,omitempty"`
	FindTime   int  `yaml:"findTime,omitempty" json:"findTime,omitempty"` // seconds
	BanTime    int  `yaml:"banTime,omitempty" json:"banTime,omitempty"`   // seconds
}

type Requirements struct {
	Minimum     ResourceSpec `yaml:"minimum" json:"minimum"`
	Recommended ResourceSpec `yaml:"recommended" json:"recommended"`
}

type ResourceSpec struct {
	CPU  int `yaml:"cpu" json:"cpu"`
	RAM  int `yaml:"memory" json:"ram"` // in GB (yaml: "memory" to match stackkit.yaml)
	Disk int `yaml:"disk" json:"disk"`  // in GB
}

type SSHSpec struct {
	KeyPath string `yaml:"keyPath,omitempty" json:"keyPath,omitempty"`
	User    string `yaml:"user,omitempty" json:"user,omitempty"`
	Port    int    `yaml:"port,omitempty" json:"port,omitempty"`
	// PermitRootLogin controls sshd PermitRootLogin ("no", "prohibit-password", etc.).
	PermitRootLogin string `yaml:"permitRootLogin,omitempty" json:"permitRootLogin,omitempty"`
	// PasswordAuth enables/disables password authentication in sshd.
	PasswordAuth *bool `yaml:"passwordAuth,omitempty" json:"passwordAuth,omitempty"`
	// MaxAuthTries limits authentication attempts per connection.
	MaxAuthTries int `yaml:"maxAuthTries,omitempty" json:"maxAuthTries,omitempty"`
}

type ServiceInfo struct {
	Name   string `json:"name"`
	URL    string `json:"url,omitempty"`
	Status string `json:"status"` // "running", "stopped", "error"
}

type ServiceState struct {
	Name      string        `yaml:"name" json:"name"`
	Status    ServiceStatus `yaml:"status" json:"status"`
	Container string        `yaml:"container,omitempty" json:"container,omitempty"`
	URL       string        `yaml:"url,omitempty" json:"url,omitempty"`
	Health    HealthStatus  `yaml:"health" json:"health"`
}

type ServiceStatus string

type SetupDropSpec struct {
	Name          string            `yaml:"name" json:"name"`
	Version       string            `yaml:"version,omitempty" json:"version,omitempty"`
	Runner        string            `yaml:"runner,omitempty" json:"runner,omitempty"`
	Description   string            `yaml:"description,omitempty" json:"description,omitempty"`
	RollbackNotes []string          `yaml:"rollbackNotes,omitempty" json:"rollbackNotes,omitempty"`
	Command       []string          `yaml:"command,omitempty" json:"command,omitempty"`
	Env           map[string]string `yaml:"env,omitempty" json:"env,omitempty"`
	Secrets       map[string]string `yaml:"secrets,omitempty" json:"secrets,omitempty"`
}

type SetupPolicyResolver struct {
	// contains filtered or unexported fields
}

type SetupRunLogEntry struct {
	Timestamp time.Time `yaml:"timestamp,omitempty" json:"timestamp,omitempty"`
	Phase     string    `yaml:"phase,omitempty" json:"phase,omitempty"`
	Level     string    `yaml:"level,omitempty" json:"level,omitempty"`
	Message   string    `yaml:"message,omitempty" json:"message,omitempty"`
}

type SetupRunState struct {
	RunID         string             `yaml:"runId,omitempty" json:"runId,omitempty"`
	ServiceKey    string             `yaml:"serviceKey,omitempty" json:"serviceKey,omitempty"`
	AppName       string             `yaml:"appName" json:"appName"`
	DropName      string             `yaml:"dropName" json:"dropName"`
	Policy        string             `yaml:"policy,omitempty" json:"policy,omitempty"`
	Status        string             `yaml:"status" json:"status"`
	Phase         string             `yaml:"phase,omitempty" json:"phase,omitempty"`
	Attempts      int                `yaml:"attempts,omitempty" json:"attempts,omitempty"`
	Message       string             `yaml:"message,omitempty" json:"message,omitempty"`
	Error         string             `yaml:"error,omitempty" json:"error,omitempty"`
	FailureClass  string             `yaml:"failureClass,omitempty" json:"failureClass,omitempty"`
	Evidence      map[string]string  `yaml:"evidence,omitempty" json:"evidence,omitempty"`
	Logs          []SetupRunLogEntry `yaml:"logs,omitempty" json:"logs,omitempty"`
	RollbackNotes []string           `yaml:"rollbackNotes,omitempty" json:"rollbackNotes,omitempty"`
	LastRequested time.Time          `yaml:"lastRequested,omitempty" json:"lastRequested,omitempty"`
	LastStarted   time.Time          `yaml:"lastStarted,omitempty" json:"lastStarted,omitempty"`
	LastFinished  time.Time          `yaml:"lastFinished,omitempty" json:"lastFinished,omitempty"`
}

type SingleServerBackupSafetySpec struct {
	Enabled                  *bool  `yaml:"enabled,omitempty" json:"enabled,omitempty"`
	MinimumRecoveryCopies    int    `yaml:"minimumRecoveryCopies,omitempty" json:"minimumRecoveryCopies,omitempty"`
	RequireLocalRepo         *bool  `yaml:"requireLocalRepo,omitempty" json:"requireLocalRepo,omitempty"`
	RequireEmergencyExport   *bool  `yaml:"requireEmergencyExport,omitempty" json:"requireEmergencyExport,omitempty"`
	RequireRestoreDrill      *bool  `yaml:"requireRestoreDrill,omitempty" json:"requireRestoreDrill,omitempty"`
	RequireOffHostCopy       *bool  `yaml:"requireOffHostCopy,omitempty" json:"requireOffHostCopy,omitempty"`
	RecommendOffsite         *bool  `yaml:"recommendOffsite,omitempty" json:"recommendOffsite,omitempty"`
	RecommendImmutableCopy   *bool  `yaml:"recommendImmutableCopy,omitempty" json:"recommendImmutableCopy,omitempty"`
	KopiaIndependentFallback string `yaml:"kopiaIndependentFallback,omitempty" json:"kopiaIndependentFallback,omitempty"`
}

type StackKit struct {
	APIVersion   string                    `yaml:"apiVersion,omitempty" json:"apiVersion,omitempty"`
	Kind         string                    `yaml:"kind,omitempty" json:"kind,omitempty"`
	Metadata     StackKitMetadata          `yaml:"metadata" json:"metadata"`
	SupportedOS  []string                  `yaml:"supportedOS" json:"supportedOS"`
	Requirements Requirements              `yaml:"requirements" json:"requirements"`
	Modes        Modes                     `yaml:"modes" json:"modes"`
	Application  map[string]ApplicationDef `yaml:"application,omitempty" json:"application,omitempty"`
	Platform     map[string]PlatformDef    `yaml:"platform,omitempty" json:"platform,omitempty"`
	Features     Features                  `yaml:"features,omitempty" json:"features,omitempty"`
}

type StackKitMetadata = KitMetadata

type StackSpec struct {
	Name             string               `yaml:"name" json:"name"`
	StackKit         string               `yaml:"stackkit" json:"stackkit"`
	Mode             string               `yaml:"mode,omitempty" json:"mode,omitempty"`
	Runtime          string               `yaml:"runtime,omitempty" json:"runtime,omitempty"` // "docker" or "native"
	Context          string               `yaml:"context,omitempty" json:"context,omitempty"`
	Placement        PlacementSpec        `yaml:"placementMode,omitempty" json:"placementMode,omitempty"`
	Domain           string               `yaml:"domain,omitempty" json:"domain,omitempty"`
	SubdomainPrefix  string               `yaml:"subdomainPrefix,omitempty" json:"subdomainPrefix,omitempty"`
	Email            string               `yaml:"email,omitempty" json:"email,omitempty"`
	AdminEmail       string               `yaml:"adminEmail,omitempty" json:"adminEmail,omitempty"`
	Network          NetworkSpec          `yaml:"network,omitempty" json:"network,omitempty"`
	Compute          ComputeSpec          `yaml:"compute,omitempty" json:"compute,omitempty"`
	Storage          StorageSpec          `yaml:"storage,omitempty" json:"storage,omitempty"`
	SSH              SSHSpec              `yaml:"ssh,omitempty" json:"ssh,omitempty"`
	Nodes            []NodeSpec           `yaml:"nodes,omitempty" json:"nodes,omitempty"`
	TLS              TLSSpec              `yaml:"tls,omitempty" json:"tls,omitempty"`
	PAAS             string               `yaml:"paas,omitempty" json:"paas,omitempty"` // explicit platform adapter override; omitted resolves to Coolify
	Addons           []string             `yaml:"addons,omitempty" json:"addons,omitempty"`
	Application      map[string]any       `yaml:"application,omitempty" json:"application,omitempty"`
	Services         map[string]any       `yaml:"services,omitempty" json:"services,omitempty"`
	Apps             map[string]AppSpec   `yaml:"apps,omitempty" json:"apps,omitempty"`
	PlatformFallback PlatformFallbackSpec `yaml:"platformFallback,omitempty" json:"platformFallback,omitempty"`
	Environment      map[string]string    `yaml:"environment,omitempty" json:"environment,omitempty"`
	Metadata         map[string]string    `yaml:"metadata,omitempty" json:"metadata,omitempty"`
	Identity         *IdentitySpec        `yaml:"identity,omitempty" json:"identity,omitempty"`

	// Owner is set by `stackkit init` or orchestration handoff when owner
	// bootstrap is requested. Empty means owner provisioning is disabled. The
	// explicit bootstrapMode separates SaaS auto-owner, self-hosted custom
	// owner, and OSS/BYOS no-owner specs without inventing a fake human owner.
	Owner OwnerConfig `yaml:"owner,omitempty" json:"owner,omitempty"`

	// BreakGlass declares the emergency-admin contract. It is enabled by
	// default even when omitted; the explicit block exists so Admin/private
	// specs can prove that break-glass is a separate full-emergency path rather
	// than a second daily admin account.
	BreakGlass BreakGlassConfig `yaml:"breakGlass,omitempty" json:"breakGlass,omitempty"`

	// Bootstrap configures setup policy defaults. Install mode selects the
	// automation surface; bootstrapped defaults to automatic platform setup and
	// on-demand application setup.
	Bootstrap BootstrapSpec `yaml:"bootstrap,omitempty" json:"bootstrap,omitempty"`

	// DemoData controls optional seed content for app verification. It is off
	// by default so L3 applications are not preconfigured unless requested.
	DemoData DemoDataSpec `yaml:"demoData,omitempty" json:"demoData,omitempty"`

	// Extended spec sections — derived from basement-kit CUE schemas.
	// These capture the full Zielbild that StackKits need to generate configs.
	System          *SystemSpec           `yaml:"system,omitempty" json:"system,omitempty"`
	DNS             *DNSSpec              `yaml:"dns,omitempty" json:"dns,omitempty"`
	VPN             *VPNSpec              `yaml:"vpn,omitempty" json:"vpn,omitempty"`
	Firewall        *FirewallSpec         `yaml:"firewall,omitempty" json:"firewall,omitempty"`
	Backup          *BackupSpec           `yaml:"backup,omitempty" json:"backup,omitempty"`
	Observability   *ObservabilitySpec    `yaml:"observability,omitempty" json:"observability,omitempty"`
	ContainerConfig *ContainerRuntimeSpec `yaml:"container,omitempty" json:"container,omitempty"`
	Branding        *BrandingSpec         `yaml:"branding,omitempty" json:"branding,omitempty"`
	Tunnel          *TunnelSpec           `yaml:"tunnel,omitempty" json:"tunnel,omitempty"`
	DriftDetection  *DriftDetectionSpec   `yaml:"driftDetection,omitempty" json:"driftDetection,omitempty"`
}

type StorageResolution struct {
	Strategy string `json:"strategy"` // "none", "external-device", "tier-downgrade", "force"
	Device   string `json:"device,omitempty"`
	Mount    string `json:"mount,omitempty"`
}

type StorageSpec struct {
	ExternalDevice string `yaml:"externalDevice,omitempty" json:"externalDevice,omitempty"`
	MountPoint     string `yaml:"mountPoint,omitempty" json:"mountPoint,omitempty"`
	// DataDir is the root directory for service data (default "/opt/data").
	DataDir string `yaml:"dataDir,omitempty" json:"dataDir,omitempty"`
	// BackupDir is the directory for local backups (default "/opt/backups").
	BackupDir string `yaml:"backupDir,omitempty" json:"backupDir,omitempty"`
	// MediaPath is the path for media storage (Jellyfin, Immich, etc.).
	MediaPath string `yaml:"mediaPath,omitempty" json:"mediaPath,omitempty"`
}

type SystemInfo struct {
	Hostname      string `json:"hostname"`
	OS            string `json:"os"`
	OSVersion     string `json:"osVersion"`
	Arch          string `json:"arch"`
	CPUCores      int    `json:"cpuCores"`
	MemoryMB      int    `json:"memoryMB"`
	DiskGB        int    `json:"diskGB"`
	DockerVersion string `json:"dockerVersion,omitempty"`
	TofuVersion   string `json:"tofuVersion,omitempty"`
}

type SystemSpec struct {
	// Timezone in IANA format (e.g. "Europe/Berlin"). Default: "UTC".
	Timezone string `yaml:"timezone,omitempty" json:"timezone,omitempty"`
	// Locale for the system (e.g. "en_US.UTF-8").
	Locale string `yaml:"locale,omitempty" json:"locale,omitempty"`
	// Swap policy: "disabled", "auto", "manual".
	Swap string `yaml:"swap,omitempty" json:"swap,omitempty"`
	// SwapSizeMB when Swap is "manual".
	SwapSizeMB int `yaml:"swapSizeMB,omitempty" json:"swapSizeMB,omitempty"`
	// UnattendedUpgrades: "disabled", "security" (default), "all".
	UnattendedUpgrades string `yaml:"unattendedUpgrades,omitempty" json:"unattendedUpgrades,omitempty"`
}

type TLSSpec struct {
	Provider  string `yaml:"provider,omitempty" json:"provider,omitempty"`   // DNS provider for DNS-01 challenge (e.g. "cloudflare")
	Challenge string `yaml:"challenge,omitempty" json:"challenge,omitempty"` // "tls" (default) or "dns"
}

type ToolRole string

type TunnelSpec struct {
	// Enabled activates the tunnel.
	Enabled bool `yaml:"enabled,omitempty" json:"enabled,omitempty"`
	// Provider: "cloudflare" or "pangolin".
	Provider string `yaml:"provider,omitempty" json:"provider,omitempty"`
	// Cloudflare-specific configuration.
	Cloudflare *CloudflareTunnelConfig `yaml:"cloudflare,omitempty" json:"cloudflare,omitempty"`
	// Pangolin-specific configuration.
	Pangolin *PangolinTunnelConfig `yaml:"pangolin,omitempty" json:"pangolin,omitempty"`
}

type VPNSpec struct {
	// Enabled activates the VPN overlay.
	Enabled bool `yaml:"enabled,omitempty" json:"enabled,omitempty"`
	// Type selects the VPN provider: "headscale", "tailscale", "wireguard", "netbird", "none".
	Type string `yaml:"type,omitempty" json:"type,omitempty"`
	// Subnet for the VPN network.
	Subnet string `yaml:"subnet,omitempty" json:"subnet,omitempty"`
	// Port for the VPN service.
	Port int `yaml:"port,omitempty" json:"port,omitempty"`
	// Headscale-specific configuration.
	Headscale *HeadscaleConfig `yaml:"headscale,omitempty" json:"headscale,omitempty"`
}

type ValidationError struct {
	Path    string `json:"path"`
	Message string `json:"message"`
	Code    string `json:"code,omitempty"`
}

type ValidationResult struct {
	Valid    bool              `json:"valid"`
	Errors   []ValidationError `json:"errors,omitempty"`
	Warnings []ValidationError `json:"warnings,omitempty"`
}