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 {
	Preset string        `yaml:"preset,omitempty"`
	Items  []BadgeConfig `yaml:"items"`
}

type BranchBuildConfig struct {
	// ID is the unique identifier. "default" is the catch-all entry and must
	// appear last in the BranchBuilds slice.
	ID string `yaml:"id"`

	// Match references a declared branch matcher name. Required for named
	// branch_builds entries. The "default" entry rejects Match — it catches
	// any branch that did not match a named entry.
	Match string `yaml:"match,omitempty"`

	// BaseFrom is the ordered fallback chain of tag_sources ids. The runtime
	// walks this list in order; for each source id, it scans tags for a match
	// and returns the first hit. Fallback advances only when a source yields
	// zero matches.
	//
	// Reads as "look in prerelease first; if nothing, look in stable":
	//   base_from: [prerelease, stable]
	//
	// It does NOT mean "prerelease beats stable by priority" — ordering is a
	// declared search path, not a ranking.
	BaseFrom []string `yaml:"base_from"`

	// Format is the version template for non-release commits.
	// Supported placeholders: {base}, {sha}, {branch}
	// e.g., "{base}-dev+{sha}"
	Format string `yaml:"format"`
}

type BranchesConfig struct {
	// Default is the default branch name (e.g., "main"). Required for primary.
	Default string `yaml:"default,omitempty"`
}

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 {
	Preset string `yaml:"preset,omitempty"`

	// 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 CIConfig struct {
	// Image is the container image for all pipeline jobs.
	// Required — render refuses to emit without it.
	Image string `yaml:"image"`

	// Routing declares per-phase runner placement requirements.
	// The renderer lowers labels to forge-native primitives
	// (GitLab: tags, GitHub/Gitea/Forgejo: runs-on).
	Routing RoutingConfig `yaml:"routing,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 {
	Preset       string       `yaml:"preset,omitempty"`
	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"`

	// Forges declares git hosts. Each entry is a host identity (provider, URL, credentials).
	Forges []ForgeConfig `yaml:"forges,omitempty"`

	// Repos declares projects on forges. References forges by id. Has role (primary/mirror).
	Repos []RepoConfig `yaml:"repos,omitempty"`

	// Registries declares OCI registry hosts. Referenced by targets.
	Registries []RegistryConfig `yaml:"registries,omitempty"`

	// Versioning controls how version identity is derived from git state.
	Versioning VersioningConfig `yaml:"versioning"`

	// Matchers defines reusable named patterns for branches (and future
	// dimensions). Pattern definitions only — no behavior. Referenced by
	// branch_builds[].match and target.when.branches.
	Matchers MatchersConfig `yaml:"matchers"`

	// 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 URL derived from publish-origin repo role.
	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"`

	// CI holds all pipeline-related configuration consumed by ci render.
	CI CIConfig `yaml:"ci"`

	// 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"`

	// Toolchains defines operator control over external tool resolution.
	// Version pins, future retention policy, future trust settings.
	Toolchains ToolchainConfig `yaml:"toolchains,omitempty"`
}

type ConfigReport struct {
	SourceFile   string         `json:"source_file"`
	Presets      []string       `json:"presets,omitempty"`
	Overrides    int            `json:"overrides,omitempty"`
	Sections     []SectionState `json:"sections,omitempty"`
	VarsApplied  int            `json:"vars_applied,omitempty"`
	Warnings     []string       `json:"warnings,omitempty"`
	Status       string         `json:"status"`       // "ok" | "partial" | "error"
	Completeness string         `json:"completeness"` // "complete" | "partial"
	Error        string         `json:"error,omitempty"`
}

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"`
	RunFrom   RunFromConfig             `yaml:"run_from,omitempty"` // gate mutation to declared origin
}

type DependencyCommitPromotion string

type DependencyConfig struct {
	Preset  string                 `yaml:"preset,omitempty"`
	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 {
	Preset string `yaml:"preset,omitempty"`

	// 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"`
	RunFrom RunFromConfig `yaml:"run_from,omitempty"` // gate mutation to declared origin
}

type DocsConfig struct {
	Preset     string               `yaml:"preset,omitempty"`
	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 ForgeConfig struct {
	ID          string `yaml:"id"`                    // unique identifier (e.g., "prplanit-gitlab")
	Provider    string `yaml:"provider"`              // gitlab, github, gitea
	URL         string `yaml:"url"`                   // base URL (e.g., "https://gitlab.prplanit.com")
	Credentials string `yaml:"credentials,omitempty"` // env var prefix for token resolution
}

type GitOpsConfig struct {
	Preset string `yaml:"preset,omitempty"`

	// 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 {
	Preset   string                  `yaml:"preset,omitempty"`
	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"`
	Credentials string                   `yaml:"credentials,omitempty"` // env var prefix for forge auth
}

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 {
	Preset string `yaml:"preset,omitempty"`
	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 {
	Preset       string                  `yaml:"preset,omitempty"`
	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 {
	Preset string `yaml:"preset,omitempty"`

	// 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 MatchersConfig struct {
	Preset string `yaml:"preset,omitempty"`

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

type MergeEntry struct {
	Path         string // dot-path (e.g., "security.sbom")
	Source       string // "managed", "local", "preset:preset/security.yml"
	SourceRef    string // "PrPlanIT/MaintenancePolicy@v1.0.0" for presets
	Layer        int    // resolution depth (0=innermost preset, N=outermost, N+1=managed, N+2=local)
	Operation    string // "set", "override", "merge", "replace"
	Value        any
	Overridden   bool
	OverriddenBy string
}

type MergeTrace struct {
	Entries []MergeEntry
}

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"`

	// Build is the id of the build whose manifest this item renders
	// (kind: build-contents). Ownership is declared, never inferred from build
	// list position: when more than one build is configured this is required, so
	// reordering or adding builds can never silently change which build's
	// inventory a doc section renders. Optional only for single-build configs
	// (backward compatibility), where the sole build is unambiguous. Ignored when
	// Source is set (an explicit manifest path is even more specific).
	Build string `yaml:"build,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 NoLineageConfig struct {
	// Mode controls the response to missing lineage.
	//   "error" (default): fail fast with explanation and suggested fix
	//   "explicit": use the provided version template
	Mode string `yaml:"mode,omitempty"`

	// Version is the template used when mode is "explicit".
	// Must contain {sha} or {time} — hardcoded versions are rejected.
	// e.g., "0.1.0-bootstrap+{sha}"
	Version string `yaml:"version,omitempty"`
}

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

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

type PresentationConfig struct {
	Preset  string              `yaml:"preset,omitempty"`
	Commit  CommitPresentation  `yaml:"commit"`
	Tag     TagPresentation     `yaml:"tag"`
	Release ReleasePresentation `yaml:"release"`
}

type PresetLoader interface {
	Load(path string) ([]byte, error)
}

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 RegexRewrite struct {
	Pattern string `yaml:"pattern"`
	Replace string `yaml:"replace"`
}

type RegistryConfig struct {
	ID          string `yaml:"id"`                     // unique identifier (e.g., "dockerhub")
	Provider    string `yaml:"provider"`               // docker, harbor, ghcr, quay, gitea, generic
	URL         string `yaml:"url"`                    // registry URL (e.g., "docker.io")
	Credentials string `yaml:"credentials,omitempty"`  // env var prefix for token resolution
	DefaultPath string `yaml:"default_path,omitempty"` // default image path (e.g., "{var:org}/{var:repo}")
}

type ReleaseConfig struct {
	Preset          string        `yaml:"preset,omitempty"`
	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"`
	RunFrom         RunFromConfig `yaml:"run_from,omitempty"` // gate mutation to declared origin
}

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 RepoConfig struct {
	ID       string         `yaml:"id"`                 // unique identifier
	Forge    string         `yaml:"forge"`              // references forges[].id
	Project  string         `yaml:"project"`            // project path on the forge (e.g., "{var:gitlab_group}/{var:repo}")
	Roles    []string       `yaml:"roles,omitempty"`    // ["primary"] | ["mirror"] | ["mirror", "publish-origin"] | []
	Branches BranchesConfig `yaml:"branches,omitempty"` // branch identity (default, protected, etc.)
	Worktree string         `yaml:"worktree,omitempty"` // local working tree path (primary only)
	Ref      string         `yaml:"ref,omitempty"`      // pinned ref for non-primary repos (governance, presets)
	Sync     SyncConfig     `yaml:"sync,omitempty"`     // mirror sync domains
}

type ResolvedRegistry struct {
	ID          string
	Provider    string // from registry
	URL         string // from registry
	Path        string // from registry default_path or target override
	Credentials string // from registry
}

type ResolvedRepo struct {
	ID            string
	Provider      string   // from forge
	BaseURL       string   // from forge
	Project       string   // from repo
	Credentials   string   // from forge
	Roles         []string // from repo (primary, mirror, publish-origin)
	DefaultBranch string   // flattened from repo.Branches.Default
	Worktree      string
	Ref           string
	Sync          SyncConfig
}

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 RoutingConfig struct {
	Perform RoutingSpec `yaml:"perform,omitempty"`
}

type RoutingSpec struct {
	Labels []string `yaml:"labels,omitempty"`
}

type RunFromConfig struct {
	Allow    []string `yaml:"allow,omitempty"`    // permitted origins: "primary"
	Mismatch string   `yaml:"mismatch,omitempty"` // "read-only" (default), "exit", "ignore"
}

type RunFromResult struct {
	Matched bool   // true if current context matches an allowed origin
	Mode    string // "read-only", "exit", "ignore", or "" (no restriction)
	Reason  string // human-readable explanation (empty when matched or unconfigured)
}

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 SectionState struct {
	Name             string `json:"name"`
	Kind             string `json:"kind"` // "execution" | "capability" | "structural"
	Active           bool   `json:"active"`
	SourcePresent    bool   `json:"source_present"`
	Provenance       string `json:"provenance"`        // "manifest" | "preset" | "none"
	ResolutionStatus string `json:"resolution_status"` // "resolved" | "partial" | "none"
}

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

type SecurityConfig struct {
	Preset         string         `yaml:"preset,omitempty"`
	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 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 {
	Preset   string      `yaml:"preset,omitempty"`
	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 TagSourceConfig struct {
	// ID is the unique identifier (e.g. "stable", "prerelease").
	// Referenced by branch_builds[].base_from and target.when.git_tags.
	ID string `yaml:"id"`

	// Pattern is the regex that identifies tags belonging to this source.
	// e.g., "^v?\\d+\\.\\d+\\.\\d+$"
	Pattern string `yaml:"pattern"`
}

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"`

	// RunFrom gates mutation to declared execution origins.
	// e.g. ["primary"] — only mutate when running from sources.primary.
	// Empty = no restriction (backward compat).
	RunFrom RunFromConfig `yaml:"run_from,omitempty"`

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

	// Registry references a registries[].id for registry/docker-readme targets.
	// When set, URL/Provider/Path/Credentials are resolved from the registry entry.
	// Path can still be overridden on the target (overrides registry default_path).
	Registry string `yaml:"registry,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"`

	// Mirror references a sources.mirrors[].id for release sync.
	// Forge identity (provider, url, project_id, credentials) is resolved from the mirror.
	// Avoids restating forge connection details in the target.
	Mirror string `yaml:"mirror,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 ToolPinConfig struct {
	Version string `yaml:"version,omitempty"`
}

type ToolchainConfig struct {
	// Desired declares intended tool versions. Authoritative — not a hint.
	// If a desired version fails to resolve, the system fails. No fallback.
	Desired map[string]ToolPinConfig `yaml:"desired,omitempty"`
}

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

type VersioningConfig struct {
	Preset string `yaml:"preset,omitempty"`

	// TagSources defines named places where version bases can come from.
	// e.g., {id: "stable", pattern: "^v?\\d+\\.\\d+\\.\\d+$"}
	// Globally eligible, no inherent priority. Order is declaration-preserving
	// but semantically flat — priority lives on branch rules, not here.
	TagSources []TagSourceConfig `yaml:"tag_sources"`

	// BranchBuilds defines version format for non-tag commits per branch.
	// Evaluated in declaration order; first matching rule wins. An entry with
	// id: "default" is required and must be the last entry — it catches any
	// branch that did not match a named rule.
	BranchBuilds []BranchBuildConfig `yaml:"branch_builds,omitempty"`

	// NoLineage defines behavior when no tag lineage exists (no matching tags).
	NoLineage NoLineageConfig `yaml:"no_lineage,omitempty"`
}

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

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