config

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

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

	// Backend selects the host-convergence backend. Default: "ansible".
	Backend string `yaml:"backend"`

	// Image is the execution image the playbooks (and ansible-lint) run in —
	// the ansible runtime, collections, and connection deps are the image's
	// contract. Fully qualified, version-pinned reference.
	// Default: docker.io/hlhd/ansible (the official StageFreight ansible image).
	Image string `yaml:"image"`

	// Inventory is the repo-relative ansible inventory file.
	Inventory string `yaml:"inventory"`

	// SSH is the shared connection identity used by every play.
	SSH AnsibleSSH `yaml:"ssh"`

	// Playbooks is the play library: an order-preserving id → entry map.
	// Entries with converge: true run every perform reconcile, in declared
	// order; entries with converge: false are runbooks — lintable and
	// plannable, but only ever executed by an explicit `ansible run <id>`.
	Playbooks OrderedAnsiblePlaybooks `yaml:"playbooks"`
}

type AnsiblePlaybook struct {
	ID string `yaml:"-"`

	// Path is the repo-relative playbook file.
	Path string `yaml:"path"`

	// Groups are the inventory groups this play targets (rendered as --limit).
	Groups []string `yaml:"groups"`

	// Converge marks the play as desired-state: it runs on every perform
	// reconcile. False declares a runbook — a named human operation that CI
	// can never trigger.
	Converge bool `yaml:"converge"`

	// Required: failure is hard pipeline fail (default: true — a converge
	// mutates hosts, so a partial apply must never pass silently). Set false
	// for advisory plays: a failure is recorded and narrated but the phase
	// still exits clean.
	Required *bool `yaml:"required,omitempty"`
}

type AnsibleSSH struct {
	// User is the remote login user on the managed hosts.
	User string `yaml:"user"`

	// Credentials is the env-prefix name the SSH key material is read from.
	Credentials string `yaml:"credentials"`

	// KnownHosts is the repo-relative known_hosts file holding the managed
	// hosts' public keys. Host-key verification is always strict; the file is
	// committed so host trust is auditable in git.
	KnownHosts string `yaml:"known_hosts"`
}

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 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 is governance-owned host-hygiene policy — see HostCleanupConfig.
	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", "command".
	//   - docker:  build an OCI image
	//   - binary:  build an executable via a language builder (opinionated inference)
	//   - command: run an arbitrary command in an image, capture typed outputs (the
	//              un-opinionated escape hatch; no inference). Prefer a `builder:` when
	//              one fits; reach for command only when none does.
	Kind string `yaml:"kind"`

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

	// Label is an optional human display name for this build's image in the release
	// notes / README "Image Availability" table group header (e.g. "Backend", "Login v2").
	// Purely presentational; when empty the group header falls back to the image name.
	// Generic — no per-app defaults.
	Label string `yaml:"label,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 lists the nodes that must complete before this build runs. Entries
	// are TYPED references: a bare id (or "build:<id>") is another BUILD; "scribe:<id>"
	// is a scribe content item that must be rendered first (a build baking scribe
	// output — e.g. a doc-site build consuming composed pages). Accepts a scalar or a
	// sequence; a bare id stays a build ref, so existing `depends_on: x` is unchanged.
	// Typed prefixes keep the build and scribe id spaces separate — no shared-uid rule.
	DependsOn StringOrList `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"`

	// Secrets are id → in-repo file path, passed as --secret id=<id>,src=<path>.
	// A build arg is baked into the image and readable from its history; a secret is
	// mounted for one RUN and leaves nothing behind. Use it for a credential, and for
	// an input a Dockerfile expects this way — upstream frappe_docker takes its app
	// list as a secret rather than a build arg, for instance.
	Secrets map[string]string `yaml:"secrets,omitempty"`

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

	// Stage recycles a binary build's output into this docker build's context before
	// buildx, so a copy-pre-built Dockerfile (COPY <name>) resolves — the compiled
	// binary is reused, not recompiled inside the image.
	Stage *StageConfig `yaml:"stage,omitempty"`

	// Builder is the toolchain that interprets the build.
	// Supported: "go", "rust", "node", "elixir", "dotnet", "c", "python", "jvm", "android"
	// (authoritative list: validBuilders in enums.go). Future: "zig". Empty defaults to "go".
	Builder string `yaml:"builder,omitempty"`

	// Command is the builder subcommand (binary: e.g. "build") or the full command
	// (kind: command). Accepts a scalar string or an argv sequence. Default: "build".
	Command CommandSpec `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"`

	// Image is the container image a containerized build (builder: node, elixir) runs
	// inside (with the repo mounted). Command runs in it; Output is the produced
	// artifact (file or directory tree). Defaults per builder; override for the odd
	// case (e.g. electronuserland/builder:wine, or an elixir+node image for Phoenix).
	Image string `yaml:"image,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"`

	// Outputs declares what the command produced and each output's artifact class.
	Outputs []OutputSpec `yaml:"outputs,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"`

	// Memory caps the builder container (e.g. "3g"), pinning memory-swap to the same
	// value so the builder cannot swap. Unset derives it from the runner: total RAM
	// minus a reserve that keeps the host alive — a build must never be able to
	// livelock its own machine. Only applies to a builder StageFreight creates
	// (docker-container driver); an external buildkitd owns its own limits.
	Memory string `yaml:"memory,omitempty"`
}

type CIConfig struct {
	// Image is the container image for all pipeline jobs.
	// Required — render refuses to emit without it.
	Image string `yaml:"image"`

	// Forge names the forge whose CI skeleton this repo runs on, and therefore which
	// pipeline file governance renders and distributes (gitlab → .gitlab-ci.yml,
	// github → .github/workflows/stagefreight.yml, …). More than one may be listed —
	// each writes its own file — for a repo genuinely wired to two CI systems.
	//
	// It is DECLARED, never inferred. The primary repo's forge is the obvious guess and
	// it is wrong often enough to matter: a repo can be authoritative on one forge and
	// run CI on another after replication — source on GitLab, Actions on the GitHub
	// mirror. Guessing there writes a skeleton for a forge that never runs it while the
	// one that does goes stale, surfacing as an unexplained "CI is stale" at audition.
	//
	// Empty means no CI file is rendered or distributed. That is deliberate: a repo that
	// has not said where its CI runs gets nothing, rather than something plausible.
	Forge []string `yaml:"forge,omitempty"`

	// 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
	Endpoint   string
	Exposure   ExposureRules
	Categories []InventoryCategory
	Groups     GroupSource
}

type CommandSpec string

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

	// Render controls commit rendering (default DefaultCommitPresentation; a
	// partial render: block overlays those defaults).
	Render  CommitPresentation `yaml:"render,omitempty"`
	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 as an id→forge map (provider, URL, credentials).
	Forges OrderedForges `yaml:"forges,omitempty"`

	// Repos declares projects as an id→repo map. References forges by id. Has role.
	Repos OrderedRepos `yaml:"repos,omitempty"`

	// Registries declares OCI registry hosts as an id→registry map.
	Registries OrderedRegistries `yaml:"registries,omitempty"`

	// Orgs declares organization/owner identities as an id→org map (maintainer +
	// aliases). Identity only — no forge, no credentials. Feeds {org.*} and, through
	// surface default_paths, {path.*}. See docs/design/identity-model.md.
	Orgs OrderedOrgs `yaml:"orgs,omitempty"`

	// Metadata is this repo's identity/branding — the one block every consumer reads
	// (org ref, title, names, scoped description/readme, topics, license, …). Feeds
	// {metadata.*}. See docs/design/identity-model.md.
	Metadata MetadataConfig `yaml:"metadata,omitempty"`

	// SigningSetup is the signing block. Its Profiles field holds the named trust
	// profiles (generic primitives), referenced per-target by signing_profile: <id>.
	// "Releases require hardware" is project policy (the target's selection), never
	// encoded in the framework.
	SigningSetup SigningConfig `yaml:"signing,omitempty"`

	// Git is the git: cluster and the single source for ref interpretation: named
	// branch patterns (git.branches), tag patterns (git.tags), and versioning rules
	// (git.versioning). Consumers read cfg.Git.Branches / cfg.Git.Tags /
	// cfg.Git.Versioning.{BranchBuilds,NoLineage} directly — no translation layer.
	Git GitConfig `yaml:"git,omitempty"`

	// Builds defines named build artifacts as an id→build map.
	Builds OrderedBuilds `yaml:"builds"`

	// Targets defines distribution targets and side-effects. Declared under the
	// publish: key as an id→target map (execution order preserved).
	Targets OrderedTargets `yaml:"publish,omitempty"`

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

	// LLMs is the model endpoint library (llms:): id → { provider, url, model,
	// credentials }, referenced by type: llm stencils via llm: <id>.
	LLMs OrderedLLMs `yaml:"llms,omitempty"`

	// Stencils is the shared audience-text library: id → reusable markdown element
	// with {…} variable fill, embeddable as {id} anywhere SF composes text (scribe
	// file regions, narrate, release bodies). Presence-neutral (a shared library, not
	// a phase). Consumers differ only by destination.
	Stencils OrderedStencils `yaml:"stencils,omitempty"`

	// Scribe places rendered stencils into repository files and commits them: files:
	// (placement regions whose bodies reference stencils by {id}) + commit:.
	// Presence-enabled (files/commit gate the stage).
	Scribe ScribeConfig `yaml:"scribe"`

	// Notifications sends a message when a run finishes: id → { provider, on, subject,
	// body, … }. Flat, one entry per notification. subject/body accept {…} embeds; an
	// omitted body defaults to the run's apex summary. Dispatched by the narrate phase.
	Notifications OrderedNotifications `yaml:"notifications,omitempty"`

	// Narrate is the stdout storytelling surface: announces: lists stencil ids rendered
	// as structured-output cards at the end of the run (default: the built-in summary).
	Narrate NarrateConfig `yaml:"narrate,omitempty"`

	Test TestConfig `yaml:"test"`

	// 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 declares the control repo's governance profiles. It is
	// PRESENCE-GATED, not mode-gated: the reconcile facet activates whenever
	// governance.profiles is non-empty (like the ansible/gitops subsystems), so a
	// control repo needs no lifecycle.mode: governance. A satellite instead carries
	// governance.source (a pointer at its policy repo).
	Governance GovernanceConfig `yaml:"governance"`

	// GitOps defines the gitops lifecycle target clusters, keyed by cluster name.
	GitOps OrderedClusters `yaml:"gitops,omitempty"`

	// Ansible defines the ansible host-convergence subsystem. Presence-gated
	// (any converge playbook activates it) and independent of lifecycle.mode.
	Ansible AnsibleConfig `yaml:"ansible"`

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

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

	// Toolchains defines operator control over external tool resolution.
	// Version pins, future retention policy, future trust settings.
	Toolchains ToolchainSection `yaml:"toolchains,omitempty"`
	// contains filtered or unexported fields
}

type ConfigReport struct {
	SourceFile   string         `json:"source_file"`
	Presets      []string       `json:"presets,omitempty"`
	Overrides    int            `json:"overrides,omitempty"`
	Sections     []SectionState `json:"sections,omitempty"`
	SyncTopology *SyncTopology  `json:"sync_topology,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"`
	Ignore  []DependencyIgnore     `yaml:"ignore,omitempty"`

	// Remediate controls whether the update pass PATCHES eligible dependencies
	// (true, default — fix-forward) or only evaluates them without changing
	// anything (false). It is the module's remediation stage, orthogonal to
	// fail_on (the policy stage).
	Remediate *bool `yaml:"remediate,omitempty"`

	// Outdated gates on how far a dependency has fallen behind — an update-MAGNITUDE
	// policy, not a severity one. Vulnerability severity has exactly one authority,
	// security.fail_on; duplicating that vocabulary here made two places disagree
	// about the same question.
	Outdated OutdatedGate `yaml:"outdated,omitempty"`

	// Policy is the freshness SCOPE — which non-vulnerable dependencies to pursue:
	// "all" (default — every dep to its latest eligible) or "security" (only
	// vulnerable deps; leave everything else where it is). A known vulnerability is
	// a floor, remediated under EVERY policy — Policy only governs freshness of
	// NON-vulnerable deps. Empty defaults to "all" (today's audition behavior).
	Policy string `yaml:"policy,omitempty"`

	// MaxUpdate is the update-type CEILING — how far a dependency may move:
	// "major" (allow the ecosystem's own maximum), "minor" (n.x.n — lock the major,
	// allow minor+patch), or "patch" (n.n.x — lock major and minor, allow patch
	// only). Empty defaults to "major" — a NO-OP that imposes no ceiling beyond each
	// ecosystem's native compatibility model (cargo/docker still hold out-of-range
	// majors via their `^`/tag-line semantics; gomod/github-release/toolchain retain
	// their prior auto-apply). Setting "minor"/"patch" is an explicit opt-in to hold
	// majors (and minors). A security fix is applied even if it exceeds the ceiling
	// (remediation floor).
	MaxUpdate string `yaml:"max_update,omitempty"`

	// MinReleaseAge is the supply-chain COOLDOWN: a release younger than this is
	// not recommended (freshness) nor applied (deps) — dodging the window in which
	// a compromised or yanked release is briefly live. Accepts durations like
	// "3d", "72h". Owned here as a supply-chain policy; the freshness lint module
	// reads the SAME value so its recommendations match what deps will apply.
	// Empty falls back to lint.modules.freshness.options.min_release_age (its
	// historical home) for back-compat, then to disabled.
	MinReleaseAge string `yaml:"min_release_age,omitempty"`
}

type DependencyHandoff string

type DependencyIgnore struct {
	ID     string `yaml:"id"`               // e.g. "GHSA-xxxx-yyyy-zzzz", "GO-2026-1234"
	Reason string `yaml:"reason,omitempty"` // why this risk is carried
	Until  string `yaml:"until,omitempty"`  // YYYY-MM-DD; past this date the ignore lapses
}

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 ExposureRule struct {
	Level          string   `yaml:"level"`     // internet | intranet | cluster
	Endpoints      []string `yaml:"endpoints"` // ip:port (highest precedence)
	Gateways       []string `yaml:"gateways"`
	IngressClasses []string `yaml:"ingress_classes"` // Ingress spec.ingressClassName
	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 {
	// Registry references a registries[].id. Its URL + default_path locate the cache.
	Registry string `yaml:"registry,omitempty"`

	// Path is appended to the registry URL: <registry-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 FacetSpec struct {
	Scope  string   `yaml:"scope,omitempty"`  // "current" | "all" (exact expands here)
	Prune  bool     `yaml:"prune,omitempty"`  // delete target refs/releases absent on source
	Force  bool     `yaml:"force,omitempty"`  // refs only: overwrite a DIVERGED mirror ref (default off = keep-divergent)
	Drafts bool     `yaml:"drafts,omitempty"` // releases only: carry unpublished drafts
	Only   []string `yaml:"only,omitempty"`   // releases only: restrict to these tag-sources
	Match  string   `yaml:"match,omitempty"`  // glob filter on ref/tag name
	Assets string   `yaml:"assets,omitempty"` // releases only: "" | "true" | "false" | "link"
}

type FileDef struct {
	ID       string    `yaml:"-"` // set from the files map key
	File     string    `yaml:"file"`
	LinkBase string    `yaml:"link_base,omitempty"`
	Between  [2]string `yaml:"between,omitempty"`
	Inline   bool      `yaml:"inline,omitempty"` // items sugar: render side-by-side
	Items    []string  `yaml:"items,omitempty"`  // stencil ids (+ "br"); sugar for a body
	Body     string    `yaml:"body,omitempty"`   // freeform markdown with {id} embeds
}

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
	DefaultPath string `yaml:"default_path,omitempty"` // default project path template (e.g. "{org}/{repo}"), for {path.<id>}
}

type Gate string

type GitConfig struct {
	// Branches maps a matcher name to a regex.
	Branches map[string]string `yaml:"branches,omitempty"`

	// Submodules requests that CI check out submodules. A pipeline that clones without
	// them leaves the submodule directory empty, and the build fails on a missing file
	// rather than on anything to do with the checkout — so this is declared, not guessed.
	Submodules bool `yaml:"submodules,omitempty"`
	// Tags maps a tag-source name to its pattern.
	Tags OrderedTagSources `yaml:"tags,omitempty"`
	// Versioning holds the derivation rules that consume the patterns above.
	Versioning GitVersioning `yaml:"versioning,omitempty"`
}

type GitOpsCluster struct {
	Name string `yaml:"-"` // from the map key

	Preset string `yaml:"preset,omitempty"`

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

	// Endpoint is the cluster API server URL (e.g. https://host:6443).
	Endpoint string `yaml:"endpoint"`

	// Exposure classifies endpoint reachability (rule-based).
	Exposure ExposureRules `yaml:"exposure"`

	// Categories groups the cluster's namespaces into app inventory sections.
	Categories []InventoryCategory `yaml:"categories,omitempty"`

	// Inventory configures how the app inventory reads the cluster.
	Inventory InventoryConfig `yaml:"inventory,omitempty"`

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

type GitVersioning struct {
	BranchBuilds OrderedBranchBuilds `yaml:"branch_builds,omitempty"`
	NoLineage    NoLineageConfig     `yaml:"no_lineage,omitempty"`
}

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 GovernanceConfig struct {
	Profiles OrderedGovProfiles `yaml:"profiles"`
}

type GovernanceProfile struct {
	ID          string         `yaml:"-"`                     // from the profiles: map key
	Repos       map[string]any `yaml:"repos,omitempty"`       // the location-anchored catalog (raw here)
	Config      map[string]any `yaml:"config,omitempty"`      // the profile's shared StageFreight config
	Credentials string         `yaml:"credentials,omitempty"` // env var prefix for the write token
}

type GroupSource struct {
	Annotation string `yaml:"annotation,omitempty"`
	Label      string `yaml:"label,omitempty"`
	Field      string `yaml:"field,omitempty"`
}

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 IDMap interface {
	// contains filtered or unexported methods
}

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

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

	// Refs is the operator's scoped ADOPTION list: third-party image streams
	// (matched by the shared retention-grammar template syntax) that the operator
	// explicitly grants a lifecycle — e.g. a CI base image pulled into the dind.
	// Each entry carries its own retention rules (keep_last / max_age / …), the same
	// RetentionRef grammar used everywhere retention appears. Nothing outside this
	// list (or SF's own provenance) is ever image-pruned; this is an authorization,
	// not a confidence judgment.
	Refs []RetentionRef `yaml:"refs,omitempty"`
}

type InventoryCategory struct {
	Name string `yaml:"name"`

	// Tier declares what the namespaces' workloads are: app, platform or hidden. Left
	// empty, discovery infers it per workload.
	Tier string `yaml:"tier,omitempty"`

	Namespaces []string `yaml:"namespaces"`
}

type InventoryConfig struct {
	Groups InventoryGroups `yaml:"groups,omitempty"`
}

type InventoryGroups struct {
	From GroupSource `yaml:"from,omitempty"`
}

type KMSTrust struct {
	Ref string `yaml:"ref"`
}

type KeyTrust struct {
	Ref string `yaml:"ref"`
}

type LLMConfig struct {
	ID          string `yaml:"-"`                     // the map key ({llm: <id>} reference target)
	Provider    string `yaml:"provider"`              // ollama (openai | anthropic | claude-agent reserved)
	URL         string `yaml:"url,omitempty"`         // ollama: server base URL
	Model       string `yaml:"model,omitempty"`       // model name/tag
	Credentials string `yaml:"credentials,omitempty"` // env prefix for hosted providers
}

type Level string

type LifecycleConfig struct {
	// Preset references an external lifecycle fragment to inherit (the generic
	// preset: fragment-include mechanism — resolved and deep-merged before parse).
	Preset string `yaml:"preset,omitempty"`
	// Mode selects the phase graph. Empty defaults to image.
	//   image      — build → review → publish image pipeline (the default)
	//   docker     — read-only Docker plan/reconcile (dry-run)
	//   gitops     — validate + reconcile Flux manifests
	//   governance — governance control-repo reconcile
	Mode string `yaml:"mode"`
}

type LifecycleMode struct {
	// Name is the canonical (lowercased) mode identifier.
	Name string

	// PhaseReconcile reports whether the perform/audition/review/publish phase
	// BODIES reconcile for this mode instead of build/review/publish. True for
	// gitops+governance. False for image (build) and docker — docker reconciles
	// via the `docker`/`reconcile` CLI (RunLifecycle), not the CI phase bodies.
	PhaseReconcile bool

	// Backend returns the RunLifecycle backend name for this mode, or nil when the
	// mode has no RunLifecycle backend: image (builds via the CI pipeline) and
	// governance (dispatched by its own subsystem, executeGovernanceReconcile —
	// it never reaches RunLifecycle).
	Backend func(*Config) string
}

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"`
	Provenance   ProvenanceConfig        `yaml:"provenance,omitempty"`
	Remediation  RemediationConfig       `yaml:"remediation,omitempty"`
	Cache        LintCacheConfig         `yaml:"cache,omitempty"`

	// FailOn is the DIAGNOSTIC-IMPORTANCE threshold at or above which a lint
	// finding blocks the build: "critical" | "warning" | "info" | "off". This is
	// lint's OWN ordered vocabulary (info < warning < critical) — deliberately NOT
	// the vulnerability severity scale; a lint warning and a CVSS High are
	// incomparable. Empty defaults to "critical" (today's behavior: only critical
	// findings block). Note this is a SECOND control axis on top of each module's
	// own severity: raising fail_on reclassifies lower-importance findings from
	// other lint modules as blocking too.
	FailOn string `yaml:"fail_on,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 MatchResult struct {
	Eligible bool
	Reason   string // why NOT eligible; empty when Eligible
}

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 MetadataConfig struct {
	// Org references an orgs: entry by id (the repo's owner). May be derived from the
	// primary repo location instead of declared.
	Org string `yaml:"org,omitempty"`

	// Title is the human display name (e.g. "ARK Server"); defaults to the slug.
	Title string `yaml:"title,omitempty"`

	// Names overrides the repo's PATH name per surface (default = slug), e.g.
	// { dockerhub: arkserver, github: SteamCMD }.
	Names map[string]string `yaml:"names,omitempty"`

	// Description is scoped: the default may be a tiered StringOrList (fit-picked across
	// un-named surfaces); a named surface takes a single string.
	Description Scoped[StringOrList] `yaml:"description,omitempty"`

	// Readme is the source doc pushed to registry overviews / forge About, scoped:
	// a default path or per-surface paths. Defaults to the auto-detected README.
	Readme Scoped[string] `yaml:"readme,omitempty"`

	Topics   []string `yaml:"topics,omitempty"`
	License  string   `yaml:"license,omitempty"`
	Category string   `yaml:"category,omitempty"`

	// Website / DocsURL are optional and only for a genuinely SEPARATE site (product
	// page / hosted docs) — never the repo URL, which is a coordinate ({path.<forge>}).
	Website string `yaml:"website,omitempty"`
	DocsURL string `yaml:"docs_url,omitempty"`
	Icon    string `yaml:"icon,omitempty"`

	// Labels is the open forward-compat escape hatch (OCI-annotation style) for
	// metadata the schema does not model — funding, support/changelog URLs, deprecation.
	// It is NEVER a back door for a typed field above.
	Labels map[string]string `yaml:"labels,omitempty"`
}

type MirrorSync struct {
	MirrorID string `json:"mirror_id"`
	Forge    string `json:"forge"`
	Legacy   bool   `json:"legacy,omitempty"`
	Branches string `json:"branches,omitempty"`
	Tags     string `json:"tags,omitempty"`
	Releases string `json:"releases,omitempty"`
}

type ModuleConfig struct {
	Enabled *bool
	Exclude []string
	Options map[string]any
}

type NarrateConfig struct {
	Announces []string `yaml:"announces,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 Notification struct {
	ID       string `yaml:"-"`        // the map key
	Provider string `yaml:"provider"` // ntfy | webhook

	// Transport. Credentials follows the shipped env-prefix convention
	// (credentials: NTFY → NTFY_TOKEN, sent as Authorization: Bearer).
	URL         string `yaml:"url,omitempty"`
	Credentials string `yaml:"credentials,omitempty"`

	// Message — freeform stencil bodies.
	Subject string `yaml:"subject,omitempty"`
	Body    string `yaml:"body,omitempty"`

	// When gates dispatch: outcomes: (success | failure | warning) composing with
	// branches:/events:/git_tags: ("failures, but only on main"). Omitted = always.
	When WhenConditions `yaml:"when,omitempty"`

	// MaxLength hard-caps the rendered body in bytes (ntfy's default server limit
	// is 4096). Trimming happens at a line boundary and always preserves the
	// pipeline-link line so tap-through survives. 0 = no cap.
	MaxLength int `yaml:"max_length,omitempty"`

	// ntfy knobs — the full header vocabulary.
	Priority string       `yaml:"priority,omitempty"` // min|low|default|high|max
	Tags     StringOrList `yaml:"tags,omitempty"`     // emoji tags (comma-joined into the Tags header)
	Click    string       `yaml:"click,omitempty"`    // tap-through URL (stencil body; default {pipeline_url})
	Attach   string       `yaml:"attach,omitempty"`   // attachment URL
	Actions  string       `yaml:"actions,omitempty"`  // ntfy actions spec string
	Markdown bool         `yaml:"markdown,omitempty"` // render body as markdown
	Email    string       `yaml:"email,omitempty"`    // forward to email address
}

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

type OIDCTrust struct {
	Issuer   string `yaml:"issuer,omitempty"`
	Identity string `yaml:"identity,omitempty"`
}

type OrderedAnsiblePlaybooks []AnsiblePlaybook

type OrderedBranchBuilds []BranchBuildConfig

type OrderedBuilds []BuildConfig

type OrderedClusters []GitOpsCluster

type OrderedFiles []FileDef

type OrderedForges []ForgeConfig

type OrderedGovProfiles []GovernanceProfile

type OrderedLLMs []LLMConfig

type OrderedNotifications []Notification

type OrderedOrgs []OrgConfig

type OrderedRegistries []RegistryConfig

type OrderedRepos []RepoConfig

type OrderedSigningProfiles []SigningProfile

type OrderedStencils []StencilDef

type OrderedTagSources []TagSourceConfig

type OrderedTargets []TargetConfig

type OrderedTestSuites []TestSuite

type OrgConfig struct {
	ID string `yaml:"-"` // from the map key

	// Maintainer is the "Name <email>" contact for this org's repos.
	Maintainer string `yaml:"maintainer,omitempty"`

	// Aliases is an OPEN map of name-forms used to build coordinates on different
	// surfaces — e.g. {handle: hlhd, lower: homelabhd, gitlab_group: "PrPlanIT/HomeLabHD"}.
	// A surface's default_path references one as {org.<alias>}. Common case is a single
	// entry; string→string only (a coordinate segment is always a scalar).
	Aliases map[string]string `yaml:"aliases,omitempty"`
}

type OutdatedGate struct {
	// At is the smallest magnitude that trips the gate: "major" | "minor" | "patch",
	// or "off". Empty defaults to "off" — no gate, so this is zero-change until a
	// project opts in.
	At string `yaml:"at,omitempty"`

	// Action is what a tripped gate does: "warn" (default) or "error". Warn is the
	// default deliberately: an available update is information, and a policy that
	// breaks a build the day upstream publishes is one operators disable entirely.
	Action string `yaml:"action,omitempty"`
}

type OutputSpec struct {
	Type     string        `yaml:"type"`
	Source   string        `yaml:"source"`
	Worktree *WorktreeSpec `yaml:"worktree,omitempty"`
}

type PKCS11Trust struct {
	Ref string `yaml:"ref"`
}

type PagesVersioning struct {
	// Mode: "replace" (each release overwrites; the only mode implemented in P1) or
	// "keep" (every released version stays browsable — reserved for phase 2, rejected
	// in P1 rather than silently ignored).
	Mode string `yaml:"mode,omitempty"`
}

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

type PolicyPresetLoader interface {
	LoadWithPolicy(path, onMismatch string) ([]byte, error)
}

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

type ProducerCoords struct {
	Provider string // github, gitlab, gitea, forgejo
	Host     string // github.com, gitlab.prplanit.com, ...
	Project  string // owner/name
	Module   string // host/owner/name (Go module path)
}

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

type ProvenanceConfig struct {
	Generated []string `yaml:"generated,omitempty"`
	Vendored  []string `yaml:"vendored,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)
	// Render controls release rendering (default DefaultReleasePresentation; a
	// partial render: block overlays those defaults).
	Render ReleasePresentation `yaml:"render,omitempty"`

	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 RemediationConfig struct {
	TrailingWhitespace *bool `yaml:"trailing_whitespace,omitempty"` // default ON under --fix-safe
	FinalNewline       *bool `yaml:"final_newline,omitempty"`       // default ON under --fix-safe
}

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 ResolvedSigningProfile struct {
	ID               string
	Class            string
	KeyRef           string
	KMSRef           string
	PKCS11Ref        string
	OIDCIssuer       string
	OIDCIdentity     string
	PhysicalPresence bool
	NonExportable    bool
	TransparencyLog  *bool // nil = use the class default
	Attestation      bool
	Enforce          bool // signing failure is fatal (orchestration policy, not trust)
	AllowFallback    bool // an unresolved explicit signer may fall back to Tier-0
}

type RetentionPolicy struct {
	KeepLast     int            `yaml:"keep_last"`     // keep the N most recent tags per series (0/-1/unset = ∞)
	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
	KeepBranches int            `yaml:"keep_branches"` // keep the N most-recent identity groups per template (bounds retired branches; 0/unset = ∞)
	MaxAge       string         `yaml:"max_age"`       // keep items newer than this ("14d", "72h"); additive like keep_* — alone it means "only the recent survive"
	Identity     []string       `yaml:"identity"`      // extra identity vars beyond the {branch}/{env} defaults — partition tags into independent series
	Protect      []string       `yaml:"protect"`       // tag patterns that are never deleted, an explicit override
	Refs         []RetentionRef `yaml:"refs"`          // scoped overrides: a different policy for items matching a pattern (first match wins; unset fields inherit this default)
}

type RetentionRef struct {
	Match       string `yaml:"match"` // pattern (same syntax as protect/templates)
	KeepLast    int    `yaml:"keep_last"`
	KeepDaily   int    `yaml:"keep_daily"`
	KeepWeekly  int    `yaml:"keep_weekly"`
	KeepMonthly int    `yaml:"keep_monthly"`
	KeepYearly  int    `yaml:"keep_yearly"`
	MaxAge      string `yaml:"max_age"`
}

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

type RoutingConfig struct {
	Default  RoutingSpec `yaml:"default,omitempty"`
	Audition RoutingSpec `yaml:"audition,omitempty"`
	Perform  RoutingSpec `yaml:"perform,omitempty"`
	Review   RoutingSpec `yaml:"review,omitempty"`
	Publish  RoutingSpec `yaml:"publish,omitempty"`
	Narrate  RoutingSpec `yaml:"narrate,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 Scoped[T any] struct {
	Default   T
	BySurface map[string]T
}

type ScribeCommit struct {
	Type    string        `yaml:"type,omitempty"`
	Message string        `yaml:"message,omitempty"`
	Add     []string      `yaml:"add,omitempty"`
	Push    bool          `yaml:"push,omitempty"`
	SkipCI  bool          `yaml:"skip_ci,omitempty"`
	RunFrom RunFromConfig `yaml:"run_from,omitempty"`
}

type ScribeConfig struct {
	Store  string       `yaml:"store,omitempty"`  // dir for rendered file assets (default .stagefreight/scribe); path = {store}/{id}.svg
	Files  OrderedFiles `yaml:"files,omitempty"`  // id → placement region referencing stencils
	Commit ScribeCommit `yaml:"commit,omitempty"` // scribe's own auto-commit action
}

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"`   // DEPRECATED: use fail_on. Alias — true → fail_on: critical.
	OutputDir      string         `yaml:"output"`             // directory for scan artifacts (default: .stagefreight/security)

	// FailOn is the severity threshold at or above which the scan fails the build:
	// "critical" | "high" | "medium" | "low" | "off". Empty falls back to the
	// deprecated fail_on_critical (true → "critical"), then to "off" — so the
	// default stays informational (no gate), exactly as today.
	FailOn string `yaml:"fail_on,omitempty"`

	// UnreachableVulns is the policy for vulnerabilities a reachability analyzer
	// proved are never called: "pass" (default — excused from the gate) or "fail"
	// (gated on severity regardless of reachability). Only vulns with a
	// proven-unreachable verdict are affected; everything else is "unknown" and
	// gates normally.
	UnreachableVulns string `yaml:"unreachable_vulns,omitempty"`

	// Exceptions are reviewed, on-record decisions to excuse specific advisories from the
	// fail_on gate — the human counterpart to the reachability excusal above. An excepted
	// finding STILL appears in the scan report (it is not hidden); the exception only stops
	// it from FAILING the build. Each carries a mandatory reason and an optional expiry: an
	// expired exception lapses (the advisory gates again and the lapse is surfaced), and one
	// with no expiry is a standing decision (reported as such). This does nothing unless
	// fail_on is set — with the gate off, everything is already informational.
	Exceptions []SecurityException `yaml:"exceptions,omitempty"`

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

	// ReleaseDetailMaxRows bounds how many vulnerability rows the "full" detail level
	// writes into release notes; the rest are reported as a count. Unset = 100.
	//
	// "full" means complete within reason, not unbounded: a large image can carry
	// thousands of advisories, and every forge caps a release body — GitHub at 125k
	// characters, and it rejects an over-long body outright rather than trimming it. The
	// rows are written worst-first, so a bound keeps what a reader acts on and drops the
	// tail they scroll past. 0 disables the bound and restores the old behaviour.
	ReleaseDetailMaxRows *int `yaml:"release_detail_max_rows,omitempty"`

	// 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 SecurityException struct {
	// ID is the advisory this excepts (CVE / GHSA), matched case-insensitively. Required.
	ID string `yaml:"id"`
	// Reason is why the advisory is accepted or not applicable. Required — there is no
	// anonymous excusal; the justification is the whole point of the record.
	Reason string `yaml:"reason"`
	// Expires optionally lapses the exception on a date (YYYY-MM-DD). Past its expiry the
	// advisory gates again and the lapse is surfaced. Omit for a standing decision (an
	// architectural fact), which is reported as a permanent exception.
	Expires string `yaml:"expires,omitempty"`
	// Package optionally scopes the exception to a single package name, so a later,
	// unrelated advisory that reuses the same ID against a different package still gates.
	Package string `yaml:"package,omitempty"`
}

type SigningConfig struct {
	Enabled       *bool                  `yaml:"enabled,omitempty"`        // nil/true = signing allowed; false = all signing off
	AutoProvision bool                   `yaml:"auto_provision,omitempty"` // explicit consent to create/manage a Tier-0 identity
	StateDir      StateDir               `yaml:"state_dir,omitempty"`      // where persistent signing material lives
	Profiles      OrderedSigningProfiles `yaml:"profiles,omitempty"`       // id→profile map
}

type SigningProfile struct {
	ID       string       `yaml:"id"`
	Requires StringOrList `yaml:"requires"` // trust class(es); v1 enforces exactly one

	// Class reference blocks — at most one, matching the declared class.
	Key    *KeyTrust    `yaml:"key,omitempty"`
	OIDC   *OIDCTrust   `yaml:"oidc,omitempty"`
	KMS    *KMSTrust    `yaml:"kms,omitempty"`
	PKCS11 *PKCS11Trust `yaml:"pkcs11,omitempty"` // hardware transport selector (optional; absent = FIDO2 --sk)

	// Assurance properties (hardware-class ONLY; enforced in validation). The
	// value is the keyword "required" (absent = not required). The renderer later
	// selects a transport that satisfies them — they are never device names here.
	PhysicalPresence string `yaml:"physical_presence,omitempty"`
	NonExportable    string `yaml:"non_exportable,omitempty"`

	// TransparencyLog overrides the per-class default (on for oidc, off otherwise).
	TransparencyLog *bool `yaml:"transparency_log,omitempty"`

	// Attestation also emits a provenance attestation alongside the signature.
	Attestation bool `yaml:"attestation,omitempty"`

	// Enforce makes a signing failure fatal to the phase (default: best-effort —
	// warn + record a failed outcome, let the build proceed). An orchestration
	// policy, NOT a trust requirement — it never enters the SignPlan; Publish reads
	// it to decide block-vs-proceed (foundational invariant 4).
	Enforce bool `yaml:"enforce,omitempty"`

	// AllowFallback permits an explicitly-configured signer that fails to resolve to
	// fall back to the auto-provisioned Tier-0 identity. Default false: an explicit
	// trust expectation that is unmet fails LOUDLY, never silently downgrades.
	AllowFallback bool `yaml:"allow_fallback,omitempty"`
}

type StageConfig struct {
	From string `yaml:"from"`
	As   string `yaml:"as"`
}

type StateDir struct {
	Type string `yaml:"type,omitempty"` // "volume" | "host_path"
	Name string `yaml:"name,omitempty"` // volume name (type: volume)
	Path string `yaml:"path,omitempty"` // absolute path (type: host_path)
}

type StencilDef struct {
	ID string `yaml:"-"` // set from the stencils map key

	// SOURCE × RENDER.
	Type   string `yaml:"type,omitempty"`   // producer; empty = inline
	Render string `yaml:"render,omitempty"` // form: badge (default) | shield | image | table | list | kv | versions | raw

	// ── inline badge / shield areas ──
	Label      string `yaml:"label,omitempty"`     // left text (defaults to id); also props alt override
	Message    string `yaml:"message,omitempty"`   // right value (templates)
	Color      string `yaml:"color,omitempty"`     // hex or "auto"
	Font       string `yaml:"font,omitempty"`      // badge font override
	FontSize   int    `yaml:"font_size,omitempty"` // badge font size override
	Output     string `yaml:"output,omitempty"`    // SVG output path (badge generation)
	Link       string `yaml:"link,omitempty"`      // clickable URL
	Logo       string `yaml:"logo,omitempty"`      // shields.io logo / props logo
	LogoColor  string `yaml:"logo_color,omitempty"`
	LabelColor string `yaml:"label_color,omitempty"`
	Shield     string `yaml:"shield,omitempty"` // shields.io path (render: shield)

	// ── text (the dumb markdown stencil: facts + {id} stencil embeds, no logic) ──
	// llm shares body: — there it is the composed INPUT (inject {ci-detail} etc.
	// and write the ask inline; no separate prompt slot).
	Body string `yaml:"body,omitempty"`

	// ── llm (AI stencil: composed body × llms: backend → markdown) ──
	LLM string `yaml:"llm,omitempty"` // llms: entry id (the backend reference)

	// ── component ──
	Spec string `yaml:"spec,omitempty"`

	// ── include ──
	Path string `yaml:"path,omitempty"`

	// ── contents (build manifest) / ci (run-state producers) ──
	Build   string `yaml:"build,omitempty"`
	Source  string `yaml:"source,omitempty"`
	Section string `yaml:"section,omitempty"`
	// Limit caps a ci producer's rows (self-bounding: excess becomes "+K more").
	Limit int `yaml:"limit,omitempty"`
	// Include keeps only the inventory items whose name matches one of these globs
	// (case-insensitive), ordered as the globs are listed — a curated subset of a
	// section that would otherwise print every package the image carries.
	Include []string `yaml:"include,omitempty"`
	// contents renderer form lives on the RENDER axis (render:), not a separate
	// renderer: key — one form vocabulary (badges|table|list|kv|versions).
	Columns    []string `yaml:"columns,omitempty"`
	OutputFile string   `yaml:"output_file,omitempty"`
	Wrap       string   `yaml:"wrap,omitempty"`
	Summary    string   `yaml:"summary,omitempty"`

	// ── named-producer coordinate override (props) ──
	Repo string `yaml:"repo,omitempty"` // repos: id whose coordinates the producer uses (default: publish-origin)

	// ── props (github-*, goreportcard, …) ──
	Params map[string]string `yaml:"params,omitempty"`
	Style  string            `yaml:"style,omitempty"`

	// ── k8s-inventory ──
	CatalogPath string `yaml:"catalog,omitempty"`
}

type StringOrList []string

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

type SyncConfig struct {
	Branches *FacetSpec `yaml:"branches,omitempty"`
	Tags     *FacetSpec `yaml:"tags,omitempty"`
	Releases *FacetSpec `yaml:"releases,omitempty"`
	// contains filtered or unexported fields
}

type SyncTopology struct {
	PrimaryID string       `json:"primary_id"`
	Mirrors   []MirrorSync `json:"mirrors,omitempty"`
}

type TagConfig struct {
	Preset   string      `yaml:"preset,omitempty"`
	Defaults TagDefaults `yaml:"defaults"`
	Message  TagMessage  `yaml:"message"`

	// Render controls tag change-log rendering (default DefaultTagPresentation; a
	// partial render: block overlays those defaults).
	Render TagPresentation `yaml:"render,omitempty"`
}

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

	// Forges restricts this target to specific CI forges by provider name
	// (github, gitlab, gitea, forgejo). Empty = every forge. Use it when a
	// registry is reachable/credentialed on some forges but not others — e.g. a
	// private mirror that only resolves from the self-hosted GitLab runner, or a
	// ghcr push that only makes sense on GitHub Actions.
	Forges []string `yaml:"forges,omitempty"`

	// Outcomes gates on the RUN outcome (success | failure | warning) — the
	// notification dimension of the one when: grammar ("failures, but only on
	// main" composes with branches:/events:). Empty = every outcome. Only valid
	// on notifications: a publish target's when: is evaluated for eligibility
	// BEFORE an outcome exists, so outcomes: there is a validation error.
	Outcomes []string `yaml:"outcomes,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: a single condition-set,
	// or a list of them (OR — the target fires if ANY matches). See WhenConditions.
	When WhenConditions `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 registries[].id for registry/metadata targets. Accepts
	// a single id (registry: harbor) or a list (registry: [dockerhub, ghcr, harbor]) —
	// a list fans the target across registries: expandMultiRegistryTargets splits it
	// into one single-registry target per id at load, so resolution/execution always
	// sees exactly one registry. When set, URL/Provider/Path/Credentials resolve from
	// the registry entry. Path can still be overridden on the target.
	Registry StringOrList `yaml:"registry,omitempty"`

	// SigningProfile references a signing.profiles[].id — the trust profile this
	// target signs under. Empty = the synthesized `legacy` profile (key-signing,
	// inert unless a key resolves). Reference-by-id, same pattern as Registry.
	SigningProfile string `yaml:"signing_profile,omitempty"`

	// URL is the registry/forge hostname (kind: registry, metadata, 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, inferred from URL.
	Provider string `yaml:"provider,omitempty"`

	// Path is the image path within the registry (kind: registry).
	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 the short project description/tagline. A scalar for kind:
	// registry; kind: metadata accepts a LIST of length-tiered variants
	// (the engine picks the longest that fits each destination's cap).
	Description StringOrList `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"`

	// Readme is the long markdown 'project page' body (registries only: Docker Hub Overview,
	// Harbor Info, JFrog README, Quay Description). On a forge the README is committed → N/A.
	Readme string `yaml:"readme,omitempty"`

	// Website is the project's external site URL (forges: GitHub, Gitea/Forgejo).
	Website string `yaml:"website,omitempty"`

	// Topics are discovery tags (forges: GitHub, GitLab, Gitea). Authored freely; the engine
	// normalizes to lowercase-hyphenated per destination and warns on any transform.
	Topics []string `yaml:"topics,omitempty"`

	// Logo is a path to the project avatar image (project-scoped forges: GitLab, Gitea/Forgejo);
	// synced idempotently. Org-scoped logos (GitHub, Docker Hub) are out of scope.
	Logo string `yaml:"logo,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"`

	// Notes names the stencil (a type: text body in stencils:) that composes
	// this release's notes document (kind: release). An explicit reference —
	// different targets may name different stencils. Empty = SF's shipped
	// default body.
	Notes string `yaml:"notes,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"`

	// SecuritySummary attaches the security summary to this release; the summary's
	// location is security.output, so this is a yes/no toggle rather than a path.
	// RegistryLinks and CatalogLinks attach the published image and catalog links.
	//
	// Per target, with Notes and Limits, because all four describe what a release
	// CONTAINS, and each channel publishes a different document: a dev release cut on
	// every push and a stable one carry different evidence. Unset omits the content.
	SecuritySummary bool `yaml:"security_summary,omitempty"`
	RegistryLinks   bool `yaml:"registry_links,omitempty"`
	CatalogLinks    bool `yaml:"catalog_links,omitempty"`

	// Limits bound the release-note facts that grow with the repo, in characters
	// (kind: release). Keyed by fact name — changes, changelog — because the body is
	// composed from facts by a stencil, so there is no fixed set of sections to name:
	// a stencil may omit a fact, reorder them, or use one twice.
	//
	// Per target because verbosity is a property of the channel, not the project: a dev
	// release cut on every push wants a terse changelog where a stable one wants the
	// whole thing. Unset uses the engine default; 0 is unbounded.
	//
	// A bound stops between entries and never inside one, and states the remainder as a
	// count — every forge caps a release body, and an over-long one is rejected outright
	// rather than trimmed.
	Limits map[string]int `yaml:"limits,omitempty"`

	// Tag is the immutable identity pattern for a release channel (kind: release).
	// Distinct from Aliases (rolling): Tag names one immutable release per build, e.g.
	// "dev-{sha:8}". Resolved against version info like Aliases ({version}, {sha:8}, ...).
	// When the triggering event is not itself a ref (a branch push), the release runner
	// mints this tag so the channel release has a stable anchor. Empty = no channel tag.
	Tag string `yaml:"tag,omitempty"`

	// Type is the semantic release classification (kind: release):
	//
	//	type: latest        — the stable, "Latest" release (GitHub: make_latest=true)
	//	type: prerelease    — a pre-release (never Latest)
	//	type: unspecified   — explicit default/auto (declarative GitOps; same as omitting)
	//
	// Omitting the field is identical to "unspecified": the type is inferred from the
	// version (a semver prerelease suffix ⇒ prerelease) and the legacy `prerelease` flag.
	// Each forge lowers the intent to what it can express (GitHub: prerelease+make_latest;
	// Gitea: prerelease; GitLab: a plain release; Azure: n/a).
	Type string `yaml:"type,omitempty"`

	// Prerelease marks the forge release as a pre-release (kind: release). DEPRECATED:
	// prefer `type: prerelease`. Still honored when `type` is unset/unspecified.
	Prerelease bool `yaml:"prerelease,omitempty"`

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

	// Repos names the destination repos[].id for a kind: release target. The repo
	// with role primary is the canonical release (authored via the git remote); every
	// other named repo gets an authored copy (release + assets). Forge identity for
	// each is resolved from its repos[] entry. A repo reaches releases via a target's
	// repos: XOR its sync.releases facet — never both (config-time XOR).
	Repos StringOrList `yaml:"repos,omitempty"`

	// Archives references a binary-archive target ID (kind: release and generic-package).
	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", "auto", or "binary" (kind:
	// binary-archive). "auto" picks zip for windows, tar.gz for everything else (default).
	// "binary" is a passthrough: the build's single-file output is carried as the
	// distributable as-is, NOT re-archived — for a build whose output is already packaged
	// (e.g. a kind: command build that emits its own tarball or a raw binary you want
	// uploaded unwrapped), so no double-archiving occurs.
	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"`

	// Repo references a repos[].id (kind: generic-package). The forge identity
	// (provider, url, project, credentials) is resolved from the repo; the package
	// is published to that forge's generic package registry.
	Repo string `yaml:"repo,omitempty"`

	// Package is the generic package name (kind: generic-package).
	// Defaults to the repo project's basename if empty.
	Package string `yaml:"package,omitempty"`

	// Version is the immutable package version pattern (kind: generic-package).
	// Resolved against version info like Aliases ({version}, {sha:8}, ...), e.g.
	// "dev-{sha:8}". Published once, never overwritten. Distinct from a release Tag
	// (a git ref): this names a package *version*, not a git tag. Required — every
	// rolling Alias must have an immutable Version behind it.
	Version string `yaml:"version,omitempty"`

	// Project is the Cloudflare Pages project name (provider: cloudflare). Default:
	// the target id. Cloudflare requires lowercase letters, digits, and hyphens,
	// 1–58 chars, no leading/trailing hyphen — validated at load. Ignored by the
	// github provider (which deploys to the gh-pages branch of the repo).
	Project string `yaml:"project,omitempty"`

	// Dir publishes a repo directory directly instead of a build's output tree
	// (kind: pages). Exactly one of Build or Dir must be set.
	Dir string `yaml:"dir,omitempty"`

	// Exclude drops matching paths from the publish workspace before deploy
	// (kind: pages). Globs, applied after extraction.
	Exclude []string `yaml:"exclude,omitempty"`

	// Domain is the custom domain(s) (kind: pages). Accepts a bare scalar or a list:
	//
	//	domain: precisionplanit.com
	//	domain: [precisionplanit.com, prplanit.com]
	//
	// Cloudflare attaches every listed domain to the project (each auto-wires DNS).
	// GitHub Pages serves a single custom domain, so a list is rejected at load; the
	// one entry is written as the CNAME.
	Domain StringOrList `yaml:"domain,omitempty"`

	// BasePath is the URL path the site is served under (kind: pages). Inferred per
	// provider (Cloudflare "/", GitHub project "/<repo>/") and fed into the build.
	BasePath string `yaml:"base_path,omitempty"`

	// Versioning controls multi-version publishing (kind: pages). P1 accepts only
	// mode: replace; mode: keep is reserved for phase 2 and rejected.
	Versioning *PagesVersioning `yaml:"versioning,omitempty"`
}

type TestConfig struct {
	Preset  string            `yaml:"preset,omitempty"`
	Enabled bool              `yaml:"enabled"`
	Auto    *bool             `yaml:"auto,omitempty"` // nil ⇒ true
	Suites  OrderedTestSuites `yaml:"suites,omitempty"`
}

type TestSuite struct {
	ID      string   `yaml:"id"`
	Tool    TestTool `yaml:"tool"`
	Gate    Gate     `yaml:"gate,omitempty"` // default: perform
	From    string   `yaml:"from,omitempty"` // module/crate dir when not at repo root (e.g. dd-ui's api/)
	Args    []string `yaml:"args,omitempty"` // raw passthrough escape hatch
	Command string   `yaml:"command,omitempty"`

	// ── Go (native `go test` flag projections) ──────────────────────────────
	Packages    []string `yaml:"packages,omitempty"`     // ./p/...   (default ./...)
	Tags        []string `yaml:"tags,omitempty"`         // -tags a,b
	Run         string   `yaml:"run,omitempty"`          // -run <regex>
	Timeout     string   `yaml:"timeout,omitempty"`      // -timeout <d>
	Race        *bool    `yaml:"race,omitempty"`         // -race
	Coverage    *bool    `yaml:"coverage,omitempty"`     // -coverprofile
	CoverageMin *float64 `yaml:"coverage_min,omitempty"` // gate: fail the suite if statement coverage < this %

	// ── Rust (native `cargo test` flag projections) ─────────────────────────
	Workspace *bool    `yaml:"workspace,omitempty"` // --workspace
	Features  []string `yaml:"features,omitempty"`  // --features a,b
	Tests     []string `yaml:"tests,omitempty"`     // --test <name>
	Release   *bool    `yaml:"release,omitempty"`   // --release
	Nextest   *bool    `yaml:"nextest,omitempty"`   // cargo nextest run

	// ── Python (native `pytest` flag projections) ───────────────────────────
	// Selection reuses the shared fields whose meaning is identical across
	// dialects: Packages → positional test paths, Run → -k <expr> (pytest's
	// keyword filter, the analogue of go's -run), Coverage/CoverageMin → --cov.
	Markers []string `yaml:"markers,omitempty"` // -m <marker>
}

type TestTool string

type ToolConstraint struct {
	Constraint string `yaml:"version,omitempty"`
}

type ToolchainConfig map[string]ToolConstraint

type ToolchainSection struct {
	// Want is the tool→constraint map — the versions the operator WANTS (constraints, not
	// necessarily exact pins); the lock records what resolution GOT. Mirrors the internal
	// ToolchainDesired vocabulary. Authoritative, not a hint: a constraint that
	// fails to resolve fails the run, no fallback. Top-level in .stagefreight.yml
	// because toolchains are execution substrate (security scanning, signing, linting,
	// gitops), not CI-specific.
	Want ToolchainConfig `yaml:"want,omitempty"`

	// Retention governs how many resolved versions of each tool are RETAINED on the
	// runner (keep_last newest per tool; unset = engine default 2). The pinned
	// constraint's resolved version and the lock's resolution are always protected —
	// retention rotates superseded residue, never declared intent.
	Retention RetentionPolicy `yaml:"retention,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"`
}

type WhenConditions []TargetCondition

type WorktreeOutput struct {
	BuildID string
	Output  OutputSpec
}

type WorktreeSpec struct {
	Set  bool   // whether worktree was present and truthy
	Path string // explicit landing path; empty means "land at the output's Source"
}