config

type AgePruneRule struct {
	OlderThan string `yaml:"older_than,omitempty"` // e.g. "72h"
}

type BadgeConfig struct {
	ID       string `yaml:"id"`                  // stable user-defined ID for narrator reference
	Text     string `yaml:"text"`                // left side label
	Value    string `yaml:"value"`               // right side value (templates: {env:*}, {sha}, {base}, etc.)
	Color    string `yaml:"color"`               // hex color or "auto"
	Output   string `yaml:"output"`              // SVG output path (required)
	Link     string `yaml:"link,omitempty"`      // clickable URL
	Font     string `yaml:"font,omitempty"`      // font name override
	FontSize int    `yaml:"font_size,omitempty"` // font size override
}

type BadgeSpec struct {
	Label    string  // left side text (badge name / alt text)
	Value    string  // right side text (supports templates)
	Color    string  // hex color or "auto"
	Output   string  // SVG file output path
	Font     string  // built-in font name override
	FontSize float64 // font size override
	FontFile string  // custom font file override
}

type BadgesConfig struct {
	Items []BadgeConfig `yaml:"items"`
}

type BreakingConfig struct {
	Aliases        []string `yaml:"aliases,omitempty"` // e.g., [b, break, bc]
	BangSuffix     bool     `yaml:"bang_suffix"`       // feat! syntax
	FooterKeys     []string `yaml:"footer_keys"`       // e.g., ["BREAKING CHANGE"]
	ForceHighlight bool     `yaml:"force_highlight"`
	PriorityBoost  int      `yaml:"priority_boost"`
}

type BuildCacheConfig struct {
	// Mode selects which cache planes are active.
	// "": inactive — no cache flags emitted, no cleanup runs.
	// off: explicitly disabled.
	// local: bounded local buildkit cache only.
	// shared: registry-backed external cache only.
	// hybrid: both local and external.
	Mode string `yaml:"mode,omitempty"`

	// Builder configures the buildx builder lifecycle.
	// The engine owns creation, bootstrap, and narration — skeleton is transport only.
	Builder BuilderConfig `yaml:"builder,omitempty"`

	// Local configures the bounded local buildkit cache.
	Local LocalCacheConfig `yaml:"local,omitempty"`

	// External configures registry-backed shared cache.
	External ExternalCacheConfig `yaml:"external,omitempty"`

	// Cleanup configures host hygiene — residue pruning, not cache.
	// Only executes when Mode is active (not empty, not off).
	Cleanup HostCleanupConfig `yaml:"cleanup,omitempty"`
}

type BuildCachePrunePolicy struct {
	OlderThan   string `yaml:"older_than,omitempty"`   // e.g. "72h"
	KeepStorage string `yaml:"keep_storage,omitempty"` // e.g. "20GB"
}

type BuildConfig struct {
	// ID is the unique identifier for this build, referenced by targets.
	ID string `yaml:"id"`

	// Kind is the build type. Determines which fields are valid.
	// Supported: "docker", "binary".
	Kind string `yaml:"kind"`

	// SelectTags enables CLI filtering via --select.
	SelectTags []string `yaml:"select_tags,omitempty"`

	// Required means build failure is a hard pipeline fail. Default: true.
	Required *bool `yaml:"required,omitempty"`

	// BuildMode controls the build execution strategy.
	// Supported: "" (standard), "crucible" (self-proving rebuild).
	BuildMode string `yaml:"build_mode,omitempty"`

	// DependsOn references another build ID that must complete before this one.
	// Enables build ordering: binary builds before docker builds that consume them.
	DependsOn string `yaml:"depends_on,omitempty"`

	// Dockerfile is the path to the Dockerfile. Default: auto-detect.
	Dockerfile string `yaml:"dockerfile,omitempty"`

	// Context is the Docker build context path. Default: "." (repo root).
	Context string `yaml:"context,omitempty"`

	// Target is the --target stage name for multi-stage builds.
	Target string `yaml:"target,omitempty"`

	// Platforms lists the target platforms. Default: [linux/{current_arch}].
	Platforms []string `yaml:"platforms,omitempty"`

	// BuildArgs are key-value pairs passed as --build-arg. Supports templates.
	BuildArgs map[string]string `yaml:"build_args,omitempty"`

	// Cache holds build cache settings.
	Cache CacheConfig `yaml:"cache,omitempty"`

	// Builder is the toolchain that interprets the build.
	// Supported: "go". Future: "rust", "zig", "cargo".
	Builder string `yaml:"builder,omitempty"`

	// Command is the builder subcommand. e.g., "build" for "go build".
	// Default: "build".
	Command string `yaml:"command,omitempty"`

	// From is the source/input root or entry point.
	// e.g., "./src/cli" (Go package), "./src/main.rs" (Rust).
	From string `yaml:"from,omitempty"`

	// Output is the artifact name. Windows platforms auto-append ".exe".
	// Default: basename of From.
	Output string `yaml:"output,omitempty"`

	// Args are ordered raw arguments passed directly to the selected builder.
	// For Go: raw args to "go build". For Rust: raw args to "cargo build".
	// Supports template variables: {version}, {sha}, {sha:N}, {date}.
	Args []string `yaml:"args,omitempty"`

	// Env are build environment variables. e.g., {"CGO_ENABLED": "0"}
	Env map[string]string `yaml:"env,omitempty"`

	// Compress enables UPX compression on the output binary. Default: false.
	Compress bool `yaml:"compress,omitempty"`

	// Crucible holds crucible-specific configuration for binary builds.
	Crucible *CrucibleConfig `yaml:"crucible,omitempty"`
}

type BuilderConfig struct {
	// Backend pins the build backend. Default: "" (auto-detect).
	// "buildkitd" → prefer persistent buildkitd, fail if unavailable.
	// "dind" → use DinD only, ignore buildkitd even if available.
	// "" → auto-detect: prefer buildkitd if available, fall back to DinD.
	Backend string `yaml:"backend,omitempty"`

	// Name is the buildx builder name. Default: "sf-builder".
	Name string `yaml:"name,omitempty"`

	// Driver is the buildx driver. Default: "docker-container".
	Driver string `yaml:"driver,omitempty"`

	// Context is the Docker context name for the builder endpoint. Default: "sf-context".
	Context string `yaml:"context,omitempty"`
}

type CacheConfig struct {
	Watch      []WatchRule `yaml:"watch"`
	AutoDetect *bool       `yaml:"auto_detect"`
}

type ClusterConfig struct {
	Name     string        `yaml:"name"`
	Server   string        `yaml:"server"`
	Exposure ExposureRules `yaml:"exposure"`
}

type CommitConfig struct {
	DefaultType  string       `yaml:"default_type,omitempty"`
	DefaultScope string       `yaml:"default_scope,omitempty"`
	SkipCI       bool         `yaml:"skip_ci,omitempty"`
	Push         bool         `yaml:"push,omitempty"`
	Conventional bool         `yaml:"conventional"`
	Backend      string       `yaml:"backend,omitempty"`
	Types        []CommitType `yaml:"types,omitempty"`
}

type CommitPresentation struct {
	PreserveRawSubject  bool `yaml:"preserve_raw_subject"`
	EnforceConventional bool `yaml:"enforce_conventional"`
}

type CommitType struct {
	Key       string `yaml:"key"`
	Label     string `yaml:"label"`
	AliasFor  string `yaml:"alias_for,omitempty"`
	ForceBang bool   `yaml:"force_bang,omitempty"`
}

type CompiledPatterns struct {
	Include []*regexp.Regexp
	Exclude []*regexp.Regexp
}

type Condition struct {
	// Tag is a pattern matched against the git tag (CI_COMMIT_TAG).
	// Only evaluated when a tag is present. Prefix with ! to negate.
	Tag string `yaml:"tag,omitempty"`

	// Branch is a pattern matched against the git branch (CI_COMMIT_BRANCH).
	// Prefix with ! to negate.
	Branch string `yaml:"branch,omitempty"`
}

type Config struct {
	// Version must be 1. The pre-version config was an unversioned alpha
	// that never earned a schema number — this is the first stable schema.
	Version int `yaml:"version"`

	// Vars is a user-defined template variable dictionary.
	// Referenced as {var:name} anywhere templates are resolved.
	Vars map[string]string `yaml:"vars,omitempty"`

	// Defaults is inert YAML anchor storage. StageFreight ignores this
	// section entirely — it exists for users to define &anchors.
	Defaults yaml.Node `yaml:"defaults,omitempty"`

	// Sources defines build source configuration.
	Sources SourcesConfig `yaml:"sources"`

	// Policies defines named regex patterns for git tag and branch matching.
	Policies PoliciesConfig `yaml:"policies"`

	// Builds defines named build artifacts.
	Builds []BuildConfig `yaml:"builds"`

	// Targets defines distribution targets and side-effects.
	Targets []TargetConfig `yaml:"targets"`

	// Badges defines badge artifact generation (SVGs).
	// Badge system owns definitions; narrator references them via badge_ref.
	// Artifact serving location is declared at sources.publish_origin (cross-cutting).
	Badges BadgesConfig `yaml:"badges"`

	// Narrator defines content composition for file targets.
	Narrator []NarratorFile `yaml:"narrator"`

	// Lint holds lint-specific configuration (unchanged from v1).
	Lint LintConfig `yaml:"lint"`

	// Security holds security scanning configuration (unchanged from v1).
	Security SecurityConfig `yaml:"security"`

	// Commit holds configuration for the commit subsystem.
	Commit CommitConfig `yaml:"commit"`

	// Dependency holds configuration for the dependency update subsystem.
	Dependency DependencyConfig `yaml:"dependency"`

	// Docs holds configuration for the docs generation subsystem.
	Docs DocsConfig `yaml:"docs"`

	// Manifest holds configuration for the manifest subsystem.
	Manifest ManifestConfig `yaml:"manifest"`

	// Release holds configuration for the release subsystem.
	Release ReleaseConfig `yaml:"release"`

	// Lifecycle defines the repository lifecycle mode (image, gitops, governance).
	Lifecycle LifecycleConfig `yaml:"lifecycle"`

	// Governance defines configuration for the governance lifecycle mode.
	// Only valid in the control repo (lifecycle.mode: governance).
	Governance GovernanceConfig `yaml:"governance"`

	// GitOps defines configuration for the gitops lifecycle mode.
	GitOps GitOpsConfig `yaml:"gitops"`

	// Docker defines configuration for the docker lifecycle mode.
	Docker DockerLifecycleConfig `yaml:"docker"`

	// BuildCache defines the build cache subsystem (local, shared, hybrid).
	BuildCache BuildCacheConfig `yaml:"build_cache"`

	// Glossary defines the repo's shared change-language model.
	// Consumed by commit authoring, tag planning, and release rendering.
	Glossary GlossaryConfig `yaml:"glossary"`

	// Presentation defines surface-specific rendering policies.
	Presentation PresentationConfig `yaml:"presentation"`

	// Tag holds workflow defaults for the tag planner.
	Tag TagConfig `yaml:"tag"`
}

type ContainerPrunePolicy struct {
	Exited AgePruneRule `yaml:"exited,omitempty"`
}

type CrucibleConfig struct {
	// ToolchainImage is the pinned container image for pass-2 verification.
	// e.g., "docker.io/library/golang:1.24-alpine"
	ToolchainImage string `yaml:"toolchain_image,omitempty"`
}

type DependencyCIConfig struct {
	Handoff DependencyHandoff `yaml:"handoff"` // default: continue
}

type DependencyCommitConfig struct {
	Enabled   bool                      `yaml:"enabled"`
	Type      string                    `yaml:"type"`
	Message   string                    `yaml:"message"`
	Push      bool                      `yaml:"push"`
	SkipCI    bool                      `yaml:"skip_ci"`
	Promotion DependencyCommitPromotion `yaml:"promotion"` // "direct" or "mr"
	MR        DependencyMRConfig        `yaml:"mr"`
}

type DependencyCommitPromotion string

type DependencyConfig struct {
	Enabled bool                   `yaml:"enabled"`
	Output  string                 `yaml:"output"`
	Scope   DependencyScopeConfig  `yaml:"scope"`
	Commit  DependencyCommitConfig `yaml:"commit"`
	CI      DependencyCIConfig     `yaml:"ci"`
}

type DependencyHandoff string

type DependencyMRConfig struct {
	BranchPrefix string `yaml:"branch_prefix"` // default: "stagefreight/deps"
	TargetBranch string `yaml:"target_branch"` // default: "" (CI default branch)
}

type DependencyScopeConfig struct {
	GoModules     bool `yaml:"go_modules"`
	DockerfileEnv bool `yaml:"dockerfile_env"` // umbrella for docker-image + github-release
}

type DetailRule struct {
	Condition `yaml:",inline"`

	// Detail is the detail level to use when this rule matches.
	// Values: "none", "counts", "detailed", "full".
	Detail string `yaml:"detail"`
}

type DockerDriftPolicy struct {
	Tier2Action               string `yaml:"tier2_action"`                // report | reconcile (default: report)
	OrphanAction              string `yaml:"orphan_action"`               // report | down | prune (default: report)
	OrphanThreshold           int    `yaml:"orphan_threshold"`            // block if more than N orphans (default: 5)
	PruneRequiresConfirmation bool   `yaml:"prune_requires_confirmation"` // require --force for prune (default: true)
}

type DockerIaCConfig struct {
	// Path is the IaC directory relative to repo root (default: "docker-compose").
	Path string `yaml:"path"`
}

type DockerLifecycleConfig struct {
	// Backend selects the Docker execution engine (e.g. "compose").
	Backend string `yaml:"backend"`

	// Targets defines how reconciliation targets are resolved.
	Targets DockerTargetsConfig `yaml:"targets"`

	// IaC defines the Infrastructure as Code directory layout.
	IaC DockerIaCConfig `yaml:"iac"`

	// Secrets defines the secrets decryption provider.
	Secrets DockerSecretsConfig `yaml:"secrets"`

	// Drift defines drift detection and reconciliation policy.
	Drift DockerDriftPolicy `yaml:"drift"`
}

type DockerSecretsConfig struct {
	// Provider selects the secrets backend (e.g. "sops", "vault", "infisical").
	Provider string `yaml:"provider"`
}

type DockerTargetSelector struct {
	Groups []string `yaml:"groups"`
}

type DockerTargetsConfig struct {
	// Source is the inventory adapter (e.g. "ansible").
	Source string `yaml:"source"`

	// Inventory is the path to the inventory file (relative to repo root).
	Inventory string `yaml:"inventory"`

	// Selector declares which hosts from inventory are eligible.
	Selector DockerTargetSelector `yaml:"selector"`
}

type DocsCommitConfig struct {
	Enabled bool     `yaml:"enabled"`
	Type    string   `yaml:"type"`
	Message string   `yaml:"message"`
	Add     []string `yaml:"add"`
	Push    bool     `yaml:"push"`
	SkipCI  bool     `yaml:"skip_ci"`
}

type DocsConfig struct {
	Enabled    bool                 `yaml:"enabled"`
	Generators DocsGeneratorsConfig `yaml:"generators"`
	Commit     DocsCommitConfig     `yaml:"commit"`
}

type DocsGeneratorsConfig struct {
	Badges        bool `yaml:"badges"`
	ReferenceDocs bool `yaml:"reference_docs"`
	Narrator      bool `yaml:"narrator"`
	DockerReadme  bool `yaml:"docker_readme"`
}

type ExposureRule struct {
	Level        string   `yaml:"level"`     // internet | intranet | cluster
	Endpoints    []string `yaml:"endpoints"` // ip:port (highest precedence)
	Gateways     []string `yaml:"gateways"`
	CIDRs        []string `yaml:"cidrs"`
	Ports        []int    `yaml:"ports"`         // AND with CIDRs (empty = any port)
	ServiceTypes []string `yaml:"service_types"` // ClusterIP | NodePort | LoadBalancer
}

type ExposureRules struct {
	Rules []ExposureRule `yaml:"rules"`
}

type ExternalCacheConfig struct {
	// Target references a targets[].id with kind: registry.
	Target string `yaml:"target,omitempty"`

	// Path is appended to the target URL: <target-url>/<path>/<repo>/<branch>.
	Path string `yaml:"path,omitempty"`

	// Fallback is the read-only fallback branch ref (e.g. "default", "main").
	// Never written to unless current ref equals fallback.
	Fallback string `yaml:"fallback,omitempty"`

	// Mode is the BuildKit cache mode (e.g. "max", "min"). Default: "max".
	Mode string `yaml:"mode,omitempty"`

	// Retention defines when stale external cache refs are pruned.
	Retention ExternalRetention `yaml:"retention,omitempty"`
}

type ExternalRetention struct {
	MaxRefs  int    `yaml:"max_refs,omitempty"`  // max branch cache refs per repo
	StaleAge string `yaml:"stale_age,omitempty"` // prune refs for dead/merged branches
}

type FilterConfig struct {
	Summary             SummaryFilter `yaml:"summary"`
	Trailers            TrailerFilter `yaml:"trailers"`
	NormalizeWhitespace bool          `yaml:"normalize_whitespace"`
}

type GitOpsConfig struct {
	// Backend selects the GitOps reconciliation backend (e.g. "flux", "argo").
	Backend string `yaml:"backend"`

	// Cluster defines the target Kubernetes cluster.
	Cluster ClusterConfig `yaml:"cluster"`

	// OIDC defines authentication configuration for the cluster.
	OIDC OIDCConfig `yaml:"oidc"`
}

type GlossaryConfig struct {
	Types    map[string]GlossaryType `yaml:"types"`
	Breaking BreakingConfig          `yaml:"breaking"`
	Filters  FilterConfig            `yaml:"filters"`
	Rewrites RewriteConfig           `yaml:"rewrites"`
	Render   RenderConfig            `yaml:"render"`
}

type GlossaryType struct {
	Aliases        []string `yaml:"aliases,omitempty"`
	CanonicalAs    string   `yaml:"canonical_as,omitempty"` // normalize to this type (e.g., deps → chore)
	Priority       int      `yaml:"priority"`
	ReleaseVisible bool     `yaml:"release_visible"`
}

type GovernanceCluster struct {
	ID           string                   `yaml:"id"`
	Targets      GovernanceClusterTargets `yaml:"targets"`
	StageFreight map[string]any           `yaml:"stagefreight"`
}

type GovernanceClusterGroup struct {
	ID    string   `yaml:"id,omitempty"`
	Repos []string `yaml:"repos"`
}

type GovernanceClusterTargets struct {
	Repos  []string                 `yaml:"repos,omitempty"`
	Groups []GovernanceClusterGroup `yaml:"groups,omitempty"`
}

type GovernanceConfig struct {
	Clusters []GovernanceCluster `yaml:"clusters"`
}

type HostCleanupConfig struct {
	// Enabled controls whether cleanup runs. Independent of cache mode.
	Enabled bool `yaml:"enabled,omitempty"`

	// Enforcement controls what happens when cleanup cannot execute.
	// best_effort: continue + structured warning.
	// required: fail build immediately.
	Enforcement string `yaml:"enforcement,omitempty"`

	// Protect defines what is never pruned.
	Protect ProtectionPolicy `yaml:"protect,omitempty"`

	// Prune defines what is eligible for removal.
	Prune PrunePolicy `yaml:"prune,omitempty"`
}

type ImageProtection struct {
	Refs []string `yaml:"refs,omitempty"` // glob patterns
}

type ImagePrunePolicy struct {
	Dangling     AgePruneRule `yaml:"dangling,omitempty"`
	Unreferenced AgePruneRule `yaml:"unreferenced,omitempty"`
}

type Level string

type LifecycleConfig struct {
	Mode string `yaml:"mode"` // image | gitops | governance
}

type LintCacheConfig struct {
	MaxAge  string `yaml:"max_age,omitempty"`  // evict entries not hit in this duration (e.g. "7d")
	MaxSize string `yaml:"max_size,omitempty"` // evict oldest entries when cache exceeds this (e.g. "100MB")
}

type LintConfig struct {
	Level        Level                   `yaml:"level"`
	CacheDir     string                  `yaml:"cache_dir"`
	TargetBranch string                  `yaml:"target_branch"`
	Exclude      []string                `yaml:"exclude"`
	Modules      map[string]ModuleConfig `yaml:"modules"`
	Cache        LintCacheConfig         `yaml:"cache,omitempty"`
}

type LocalCacheConfig struct {
	Path      string         `yaml:"path,omitempty"` // override local cache root (default: /stagefreight/cache/buildkit)
	Retention LocalRetention `yaml:"retention,omitempty"`
}

type LocalRetention struct {
	MaxAge  string `yaml:"max_age,omitempty"`  // e.g. "7d"
	MaxSize string `yaml:"max_size,omitempty"` // e.g. "15GB"
}

type ManifestConfig struct {
	// Enabled controls whether manifest generation is active (default: false).
	Enabled bool `yaml:"enabled"`

	// Mode controls where the manifest is stored.
	// ephemeral: temp location, use during run, discard after.
	// workspace: generate to .stagefreight/manifests/, don't auto-commit.
	// commit: generate and include in docs commit.
	// publish: generate and export as release asset / CI artifact.
	Mode string `yaml:"mode,omitempty"`

	// OutputDir is the output directory for manifest files.
	// Default: .stagefreight/manifests
	OutputDir string `yaml:"output_dir,omitempty"`
}

type MirrorConfig struct {
	ID          string     `yaml:"id"`          // unique identifier (e.g., "github")
	Provider    string     `yaml:"provider"`    // forge provider: github, gitlab, gitea
	URL         string     `yaml:"url"`         // forge base URL (e.g., "https://github.com")
	ProjectID   string     `yaml:"project_id"`  // owner/repo or numeric ID on the mirror forge
	Credentials string     `yaml:"credentials"` // env var prefix for token resolution
	Sync        SyncConfig `yaml:"sync"`        // which domains to synchronize
}

type ModuleConfig struct {
	Enabled *bool          `yaml:"enabled,omitempty"`
	Exclude []string       `yaml:"exclude,omitempty"`
	Options map[string]any `yaml:"options,omitempty"`
}

type NarratorFile struct {
	// File is the path to the target file (required).
	File string `yaml:"file"`

	// LinkBase is the base URL for relative link rewriting.
	LinkBase string `yaml:"link_base,omitempty"`

	// Items are the composable content items for this file.
	Items []NarratorItem `yaml:"items"`
}

type NarratorItem struct {
	// ID is the item identifier (unique within file).
	ID string `yaml:"id"`

	// Kind is the item type: badge, shield, text, component, break, include.
	Kind string `yaml:"kind"`

	// Placement declares where this item goes in the target file.
	Placement NarratorPlacement `yaml:"placement"`

	// Text is the badge label (left side text).
	Text string `yaml:"text,omitempty"`

	// Value is the badge value (right side text, supports templates).
	Value string `yaml:"value,omitempty"`

	// Color is the badge color (hex or "auto").
	Color string `yaml:"color,omitempty"`

	// Font is the badge font name override.
	Font string `yaml:"font,omitempty"`

	// FontSize is the badge font size override.
	FontSize int `yaml:"font_size,omitempty"`

	// Output is the SVG output path for badge generation.
	Output string `yaml:"output,omitempty"`

	// Link is the clickable URL (kind: badge, shield).
	Link string `yaml:"link,omitempty"`

	// Shield is the shields.io path (kind: shield).
	Shield string `yaml:"shield,omitempty"`

	// Content is raw text/markdown content (kind: text).
	Content string `yaml:"content,omitempty"`

	// Spec is the component spec file path (kind: component).
	Spec string `yaml:"spec,omitempty"`

	// Path is the file path to include verbatim (kind: include).
	Path string `yaml:"path,omitempty"`

	// Source is an optional path to a manifest JSON file (kind: build-contents).
	// If omitted, uses the current scope manifest.
	Source string `yaml:"source,omitempty"`

	// Section is the dot-path into the manifest (kind: build-contents).
	// e.g., "inventories.pip", "build.args", "security.sbom"
	Section string `yaml:"section,omitempty"`

	// Renderer is the rendering format (kind: build-contents).
	// Supported: "table", "list", "kv".
	Renderer string `yaml:"renderer,omitempty"`

	// Columns selects which columns to render (kind: build-contents, renderer: table).
	Columns []string `yaml:"columns,omitempty"`

	// OutputFile is an optional standalone file output path (kind: build-contents).
	// When set, the rendered content is written as a standalone file.
	// Can be used alongside placement (section embedding) or alone.
	OutputFile string `yaml:"output_file,omitempty"`

	// Wrap wraps the rendered output in a container element (kind: build-contents).
	// Supported: "details" (wraps in <details>/<summary>).
	Wrap string `yaml:"wrap,omitempty"`

	// Summary is the summary text when wrap=details (required when wrap is set).
	Summary string `yaml:"summary,omitempty"`

	// Type is the props resolver type ID (kind: props).
	Type string `yaml:"type,omitempty"`

	// Params are provider-semantic inputs for the props resolver.
	Params map[string]string `yaml:"params,omitempty"`

	// Label overrides the auto-derived alt text for props.
	Label string `yaml:"label,omitempty"`

	// Style is a presentation override for shields.io badge style.
	Style string `yaml:"style,omitempty"`

	// Logo is a presentation override for shields.io logo name.
	Logo string `yaml:"logo,omitempty"`

	// CatalogPath is the path to a catalog metadata file (kind: k8s-inventory).
	// Optional — provides descriptions, friendly names, graveyard, tier overrides.
	CatalogPath string `yaml:"catalog,omitempty"`

	// Ref is the badge ID to reference (kind: badge_ref).
	// Must match an ID defined in the top-level badges: config.
	// Narrator does NOT own badge generation — only composition.
	Ref string `yaml:"ref,omitempty"`
}

type NarratorPlacement struct {
	// Between is a two-element array: [start_marker, end_marker].
	// Content is placed relative to these markers.
	Between [2]string `yaml:"between,omitempty"`

	// After is a regex/literal line match (reserved for future use).
	After string `yaml:"after,omitempty"`

	// Before is a regex/literal line match (reserved for future use).
	Before string `yaml:"before,omitempty"`

	// Heading is a markdown heading match (reserved for future use).
	Heading string `yaml:"heading,omitempty"`

	// Mode controls how content is placed:
	// replace (default), append, prepend, above, below.
	Mode string `yaml:"mode,omitempty"`

	// Inline renders items side-by-side when true (default: false).
	Inline bool `yaml:"inline,omitempty"`
}

type NetworkPrunePolicy struct {
	Unused bool `yaml:"unused,omitempty"`
}

type OIDCConfig struct {
	Audience string `yaml:"audience"`
}

type PhraseRewrite struct {
	From string `yaml:"from"`
	To   string `yaml:"to"`
}

type PoliciesConfig struct {
	// GitTags maps policy names to regex patterns for git tag matching.
	// e.g., "stable": "^\\d+\\.\\d+\\.\\d+$"
	// Named "git_tags" (not "tags") to avoid collision with Docker image tags.
	GitTags map[string]string `yaml:"git_tags"`

	// Branches maps policy names to regex patterns for branch matching.
	// e.g., "main": "^main$"
	Branches map[string]string `yaml:"branches"`
}

type PresentationConfig struct {
	Commit  CommitPresentation  `yaml:"commit"`
	Tag     TagPresentation     `yaml:"tag"`
	Release ReleasePresentation `yaml:"release"`
}

type ProtectionPolicy struct {
	Images  ImageProtection  `yaml:"images,omitempty"`
	Volumes VolumeProtection `yaml:"volumes,omitempty"`
}

type PrunePolicy struct {
	Images     ImagePrunePolicy      `yaml:"images,omitempty"`
	BuildCache BuildCachePrunePolicy `yaml:"build_cache,omitempty"`
	Containers ContainerPrunePolicy  `yaml:"containers,omitempty"`
	Networks   NetworkPrunePolicy    `yaml:"networks,omitempty"`
}

type PublishOrigin struct {
	Kind string `yaml:"kind"`           // "primary", "mirror", or "url"
	Ref  string `yaml:"ref,omitempty"`  // mirror ID (kind: mirror only)
	Base string `yaml:"base,omitempty"` // explicit URL (kind: url only)
}

type RegexRewrite struct {
	Pattern string `yaml:"pattern"`
	Replace string `yaml:"replace"`
}

type ReleaseConfig struct {
	Enabled         bool   `yaml:"enabled"`
	Required        *bool  `yaml:"required,omitempty"` // failure is hard pipeline fail (default: false)
	SecuritySummary string `yaml:"security_summary"`
	RegistryLinks   bool   `yaml:"registry_links"`
	CatalogLinks    bool   `yaml:"catalog_links"`
}

type ReleasePresentation struct {
	MaxEntries                int    `yaml:"max_entries"`
	GroupByType               bool   `yaml:"group_by_type"`
	Style                     string `yaml:"style"` // concise | explanatory | technical
	IncludeReleaseVisibleOnly bool   `yaml:"include_release_visible_only"`
}

type RenderConfig struct {
	EmptyStrategy string `yaml:"empty_strategy"` // prompt | fail | allow_empty
}

type RetentionPolicy struct {
	KeepLast    int      `yaml:"keep_last"`    // keep the N most recent tags
	KeepDaily   int      `yaml:"keep_daily"`   // keep one per day for the last N days
	KeepWeekly  int      `yaml:"keep_weekly"`  // keep one per week for the last N weeks
	KeepMonthly int      `yaml:"keep_monthly"` // keep one per month for the last N months
	KeepYearly  int      `yaml:"keep_yearly"`  // keep one per year for the last N years
	Protect     []string `yaml:"protect"`      // tag patterns that are never deleted (v2)
}

type RewriteConfig struct {
	Phrases []PhraseRewrite `yaml:"phrases,omitempty"`
	Regex   []RegexRewrite  `yaml:"regex,omitempty"`
}

type ScannerCacheConfig struct {
	MaxSize string `yaml:"max_size,omitempty"` // e.g. "500MB" — full-clear when exceeded
	MaxAge  string `yaml:"max_age,omitempty"`  // e.g. "7d" — full-clear when oldest file exceeds age
}

type ScannersConfig struct {
	Trivy *bool `yaml:"trivy,omitempty"` // run Trivy image scan (default: true)
	Grype *bool `yaml:"grype,omitempty"` // run Grype image scan (default: true)
}

type SecurityCacheConfig struct {
	Trivy ScannerCacheConfig `yaml:"trivy,omitempty"`
	Grype ScannerCacheConfig `yaml:"grype,omitempty"`
}

type SecurityConfig struct {
	Enabled        bool           `yaml:"enabled"`            // run vulnerability scanning (default: true)
	Required       *bool          `yaml:"required,omitempty"` // failure is hard pipeline fail (default: false)
	Scanners       ScannersConfig `yaml:"scanners"`           // per-scanner toggles
	SBOMEnabled    bool           `yaml:"sbom"`               // generate SBOM artifacts (default: true)
	FailOnCritical bool           `yaml:"fail_on_critical"`   // fail the pipeline if critical vulns found
	OutputDir      string         `yaml:"output"`             // directory for scan artifacts (default: .stagefreight/security)

	// ReleaseDetail is the default detail level for security info in release notes.
	// Values: "none", "counts", "detailed", "full" (default: "counts").
	ReleaseDetail string `yaml:"release_detail"`

	// ReleaseDetailRules are conditional overrides evaluated top-down (first match wins).
	// Uses the standard Condition primitive for tag/branch matching with ! negation.
	ReleaseDetailRules []DetailRule `yaml:"release_detail_rules"`

	// Cache controls persistent vulnerability DB caching per scanner.
	// Each tool's max_size triggers full-clear when exceeded (opaque DBs, no granular eviction).
	// Empty/omitted per tool = no StageFreight-managed persistence for that tool.
	Cache SecurityCacheConfig `yaml:"cache,omitempty"`

	// OverwhelmMessage is the message lines shown when >1000 vulns are found.
	// Defaults to ["…maybe start here:"] with the OverwhelmLink below.
	OverwhelmMessage []string `yaml:"overwhelm_message"`

	// OverwhelmLink is an optional URL appended after OverwhelmMessage.
	// Defaults to a Psychology Today anxiety page. Empty string disables.
	OverwhelmLink string `yaml:"overwhelm_link"`
}

type SourceConfig struct {
	Kind          string `yaml:"kind"`           // source type (default: "git")
	Worktree      string `yaml:"worktree"`       // path to working tree (default: ".")
	URL           string `yaml:"url"`            // optional: enables deterministic link_base/raw_base derivation
	DefaultBranch string `yaml:"default_branch"` // optional: used with URL for raw_base derivation
}

type SourcesConfig struct {
	Primary       SourceConfig   `yaml:"primary"`
	Mirrors       []MirrorConfig `yaml:"mirrors,omitempty"`
	PublishOrigin *PublishOrigin `yaml:"publish_origin,omitempty"`
}

type SummaryFilter struct {
	StripPhrases []string `yaml:"strip_phrases,omitempty"`
	StripRegex   []string `yaml:"strip_regex,omitempty"`
}

type SyncConfig struct {
	// Git enables authoritative mirror replication via git push --mirror.
	// All refs, branches, tags, deletions, force updates. This is the
	// foundation — artifact sync runs only after mirror succeeds.
	Git bool `yaml:"git,omitempty"`

	// Releases enables forge-native release projection (notes, assets, links).
	// Runs after git mirror succeeds. Tag is the identity key.
	Releases bool `yaml:"releases,omitempty"`

	// Docs enables README/doc file projection via forge commit API.
	// Mutually exclusive with Git (docs arrive through git mirror).
	// Only valid when Git is false.
	Docs bool `yaml:"docs,omitempty"`
}

type TagConfig struct {
	Defaults TagDefaults `yaml:"defaults"`
	Message  TagMessage  `yaml:"message"`
}

type TagDefaults struct {
	Target          string `yaml:"target"`           // default ref to tag (default: HEAD)
	Preview         bool   `yaml:"preview"`          // show preview before creating
	RequireApproval bool   `yaml:"require_approval"` // require interactive approval
	Push            bool   `yaml:"push"`             // push after creation
}

type TagMessage struct {
	Mode          string `yaml:"mode"`           // auto | prompt_if_missing | require_manual
	EmptyStrategy string `yaml:"empty_strategy"` // prompt | fail | allow_empty
}

type TagPresentation struct {
	MaxEntries                int    `yaml:"max_entries"`
	GroupByType               bool   `yaml:"group_by_type"`
	Style                     string `yaml:"style"` // concise | explanatory | technical
	IncludeReleaseVisibleOnly bool   `yaml:"include_release_visible_only"`
	CollapseSimilar           bool   `yaml:"collapse_similar"`
}

type TargetCondition struct {
	// Branches lists branch filters. Each entry is a policy name or "re:<regex>".
	// Empty = no branch filtering.
	Branches []string `yaml:"branches,omitempty"`

	// GitTags lists git tag filters. Each entry is a policy name or "re:<regex>".
	// Empty = no tag filtering.
	GitTags []string `yaml:"git_tags,omitempty"`

	// Events lists CI event type filters.
	// Supported: push, tag, release, schedule, manual, pull_request, merge_request.
	// Empty = no event filtering.
	Events []string `yaml:"events,omitempty"`
}

type TargetConfig struct {
	// ID is the unique identifier for this target (logging, status, enable/disable).
	ID string `yaml:"id"`

	// Kind is the target type. Determines which fields are valid.
	Kind string `yaml:"kind"`

	// Build references a BuildConfig.ID. Required for kind: registry.
	Build string `yaml:"build,omitempty"`

	// When specifies routing conditions for this target.
	When TargetCondition `yaml:"when,omitempty"`

	// SelectTags enables CLI filtering via --select.
	SelectTags []string `yaml:"select_tags,omitempty"`

	// URL is the registry/forge hostname (kind: registry, docker-readme, release).
	URL string `yaml:"url,omitempty"`

	// Provider is the vendor type for auth and API behavior.
	// Registry: docker, ghcr, gitlab, jfrog, harbor, quay, gitea, generic.
	// Release: github, gitlab, gitea.
	// If omitted on registry/docker-readme, inferred from URL.
	Provider string `yaml:"provider,omitempty"`

	// Path is the image path within the registry (kind: registry, docker-readme).
	Path string `yaml:"path,omitempty"`

	// Credentials is the env var prefix for authentication.
	// Resolution: try {PREFIX}_TOKEN first, else {PREFIX}_USER + {PREFIX}_PASS.
	Credentials string `yaml:"credentials,omitempty"`

	// Description is a short description override (kind: registry, docker-readme).
	Description string `yaml:"description,omitempty"`

	// Retention controls cleanup of old tags/releases.
	// Structured only in v2 (no scalar shorthand).
	Retention *RetentionPolicy `yaml:"retention,omitempty"`

	// Tags are tag templates resolved against version info (kind: registry).
	// e.g., ["{version}", "{major}.{minor}", "latest"]
	Tags []string `yaml:"tags,omitempty"`

	// NativeScan enables post-push vulnerability scanning via the registry's own built-in scanner.
	// Distinct from StageFreight's own scan pipeline (Trivy/Grype run by StageFreight itself).
	// Currently supported: Harbor (triggers Harbor's built-in Trivy after each push).
	// No-op for Docker Hub, GHCR, Quay, JFrog, and other providers.
	// Best-effort — scan failures warn but do not fail the build.
	// Push success does not imply scan success; results appear in the registry UI only.
	NativeScan bool `yaml:"native_scan,omitempty"`

	// File is the path to the README file (kind: docker-readme).
	File string `yaml:"file,omitempty"`

	// LinkBase is the base URL for relative link rewriting (kind: docker-readme).
	LinkBase string `yaml:"link_base,omitempty"`

	// SpecFiles lists component spec file paths (kind: gitlab-component).
	SpecFiles []string `yaml:"spec_files,omitempty"`

	// Catalog enables GitLab Catalog registration (kind: gitlab-component).
	Catalog bool `yaml:"catalog,omitempty"`

	// Aliases are rolling git tag aliases (kind: release).
	// e.g., ["{version}", "{major}.{minor}", "latest"]
	// Named "aliases" to avoid collision with Tags (image tags) and git_tags (policy filters).
	Aliases []string `yaml:"aliases,omitempty"`

	// ProjectID is the "owner/repo" or numeric ID for remote forge targets (kind: release).
	ProjectID string `yaml:"project_id,omitempty"`

	// SyncRelease syncs release notes + tags to a remote forge (kind: release, remote only).
	SyncRelease bool `yaml:"sync_release,omitempty"`

	// SyncAssets syncs scan artifacts to a remote forge (kind: release, remote only).
	SyncAssets bool `yaml:"sync_assets,omitempty"`

	// Archives references a binary-archive target ID (kind: release only).
	Archives string `yaml:"archives,omitempty"`

	// BinaryName overrides the binary name inside the archive (kind: binary-archive).
	// Auto-detected from referenced build if omitted.
	BinaryName string `yaml:"binary_name,omitempty"`

	// Format is the archive format: "tar.gz", "zip", or "auto" (kind: binary-archive).
	// "auto" picks zip for windows, tar.gz for everything else. Default: "auto".
	Format string `yaml:"format,omitempty"`

	// Name is the archive filename template (kind: binary-archive).
	// Supports: {id}, {version}, {os}, {arch}. e.g., "{id}-{version}-{os}-{arch}".
	Name string `yaml:"name,omitempty"`

	// Include lists extra files to bundle into the archive (kind: binary-archive).
	// e.g., ["README.md", "LICENSE"]
	Include []string `yaml:"include,omitempty"`

	// Checksums generates a SHA256SUMS file alongside archives (kind: binary-archive).
	Checksums bool `yaml:"checksums,omitempty"`
}

type TrailerFilter struct {
	StripKeys []string `yaml:"strip_keys,omitempty"`
}

type VolumeProtection struct {
	Named *bool `yaml:"named,omitempty"` // protect all named volumes
}

type WatchRule struct {
	Paths       []string `yaml:"paths"`
	Invalidates []string `yaml:"invalidates"`
}