errors.go

package errors

import (
	"errors"
	"fmt"

	schemaPkg "github.com/cloudposse/atmos/pkg/schema"
)

const (
	// ErrWrapFormat is the standard format string for wrapping errors with context.
	// Use with fmt.Errorf to wrap a sentinel error with an underlying error:
	//   fmt.Errorf(ErrWrapFormat, errUtils.ErrSentinel, underlyingErr)
	ErrWrapFormat = "%w: %w"
	// ErrWrapWithNameFormat is the format string for wrapping errors with a name context.
	// Use with fmt.Errorf to wrap a sentinel error with a name:
	//   fmt.Errorf(ErrWrapWithNameFormat, errUtils.ErrSentinel, name)
	ErrWrapWithNameFormat = "%w: %s"
	// ErrWrapWithNameAndCauseFormat is the format string for wrapping errors with a name and cause.
	// Use with fmt.Errorf to wrap a sentinel error with a name and underlying error:
	//   fmt.Errorf(ErrWrapWithNameAndCauseFormat, errUtils.ErrSentinel, name, underlyingErr)
	ErrWrapWithNameAndCauseFormat = "%w '%s': %w"
)

var (
	ErrDownloadPackage                       = errors.New("failed to download package")
	ErrDownloadFile                          = errors.New("failed to download file")
	ErrInvalidClientMode                     = errors.New("invalid client mode for operation")
	ErrInvalidErrorMode                      = errors.New("invalid error mode")
	ErrParseFile                             = errors.New("failed to parse file")
	ErrParseURL                              = errors.New("failed to parse URL")
	ErrInvalidURL                            = errors.New("invalid URL")
	ErrCreateDownloadClient                  = errors.New("failed to create download client")
	ErrProcessOCIImage                       = errors.New("failed to process OCI image")
	ErrCopyPackage                           = errors.New("failed to copy package")
	ErrCreateTempDir                         = errors.New("failed to create temp directory")
	ErrUnknownPackageType                    = errors.New("unknown package type")
	ErrLocalMixinURICannotBeEmpty            = errors.New("local mixin URI cannot be empty")
	ErrLocalMixinInstallationNotImplemented  = errors.New("local mixin installation not implemented")
	ErrNotImplemented                        = errors.New("not implemented")
	ErrFailedToInitializeTUIModel            = errors.New("failed to initialize TUI model: verify terminal capabilities and permissions")
	ErrSetTempDirPermissions                 = errors.New("failed to set temp directory permissions")
	ErrCopyPackageToTarget                   = errors.New("failed to copy package to target")
	ErrNoValidInstallerPackage               = errors.New("no valid installer package provided")
	ErrFailedToInitializeTUIModelWithDetails = errors.New("failed to initialize TUI model: verify terminal capabilities and permissions")
	ErrValidPackage                          = errors.New("no valid installer package provided for")
	ErrTUIModel                              = errors.New("failed to initialize TUI model")
	ErrTUIRun                                = errors.New("failed to run TUI")
	ErrUIFormatterNotInitialized             = errors.New("ui formatter not initialized")
	ErrMarkdownRendererInit                  = errors.New("failed to initialize markdown renderer")
	ErrMarkdownRender                        = errors.New("failed to render markdown content")
	ErrCastOutputExists                      = errors.New("cast output already exists")
	ErrEmptyCastFile                         = errors.New("empty cast file")
	ErrUnsupportedCastOutputExtension        = errors.New("unsupported cast output extension")
	ErrRenderOutputExists                    = errors.New("render output already exists")
	ErrMissingAgg                            = errors.New("missing required tool `agg`; install asciinema agg and retry")
	ErrMissingFFmpeg                         = errors.New("missing required tool `ffmpeg`; install FFmpeg and retry")
	ErrMissingRenderOutput                   = errors.New("specify an output path with --output")
	ErrRenderToolExecFailed                  = errors.New("managed renderer execution failed")
	ErrUnknownSessionAction                  = errors.New("unknown cast session action type")
	ErrSimulateActionMissingCallback         = errors.New("simulate session action has no callback")
	ErrWaitTimeout                           = errors.New("timed out waiting for cast output")
	ErrUnsupportedCastKey                    = errors.New("unsupported cast key")
	ErrMissingExecCommand                    = errors.New("exec recording requires a command")
	ErrIOContextNotInitialized               = errors.New("global I/O context is nil after initialization")
	ErrNoFilesFound                          = errors.New("no files found in directory")
	ErrMultipleFilesFound                    = errors.New("multiple files found in directory")
	ErrSourceDirNotExist                     = errors.New("source directory does not exist")
	ErrEmptyFilePath                         = errors.New("file path is empty")
	ErrEmptyWorkdir                          = errors.New("workdir cannot be empty")
	ErrWorkdirNotExist                       = errors.New("workdir does not exist")
	ErrPathResolution                        = errors.New("failed to resolve absolute path")
	ErrInvalidTemplateFunc                   = errors.New("invalid template function")
	ErrInvalidTemplateSettings               = errors.New("invalid template settings")
	ErrTemplateEvaluation                    = errors.New("template evaluation failed")
	ErrCommandEnvDecodeFailed                = schemaPkg.ErrCommandEnvDecodeFailed
	ErrCastStepRequiresSteps                 = errors.New("cast step requires nested steps")
	ErrCastSessionRequiresActions            = errors.New("cast session step requires session actions")
	ErrInvalidCastMode                       = errors.New("cast step has invalid mode")
	ErrWriteActionRequiresText               = errors.New("write action requires text")
	ErrKeyActionRequiresKey                  = errors.New("key action requires key")
	ErrPauseActionRequiresDuration           = errors.New("pause action requires duration")
	ErrWaitActionRequiresTextOrRegex         = errors.New("wait action requires exactly one of text or regex")
	ErrUnsupportedSessionAction              = errors.New("unsupported session action type")
	ErrInvalidSimulateMode                   = errors.New("simulate step has invalid mode")
	ErrSimulateTypedRequiresText             = errors.New("simulate typed step requires text")
	ErrInvalidSimulateJitter                 = errors.New("simulate typed step jitter must be between 0 and 1")
	ErrUnsupportedPromptStyle                = errors.New("unsupported simulate prompt style")
	ErrWorkdirPathRequired                   = errors.New("workdir path is required")
	ErrWorkdirSourceRequired                 = errors.New("workdir source is required")
	ErrWorkdirSourceKeyInvalid               = errors.New("workdir source map keys must be strings")
	ErrUnsafeVendorTarget                    = errors.New("unsafe vendor target directory")
	ErrInvalidConfig                         = errors.New("invalid configuration")
	ErrRefuseDeleteSymbolicLink              = errors.New("refusing to delete symbolic link")
	ErrRefuseWriteThroughSymlink             = errors.New("refusing to write through symbolic link")
	ErrNoDocsGenerateEntry                   = errors.New("no docs.generate entry found")
	ErrMissingDocType                        = errors.New("doc-type argument missing")
	ErrUnsupportedInputType                  = errors.New("unsupported input type")
	ErrMissingStackNameTemplateAndPattern    = errors.New("'stacks.name_template' (or the deprecated 'stacks.name_pattern') needs to be specified in 'atmos.yaml'")
	ErrStackNamePatternPartMissing           = errors.New("stack name pattern references a context part that is not defined in the stack file")
	ErrFailedMarshalConfigToYaml             = errors.New("failed to marshal config to YAML")
	ErrStacksDirectoryDoesNotExist           = errors.New("directory for Atmos stacks does not exist")
	ErrMissingAtmosConfig                    = errors.New("atmos configuration not found or invalid")
	ErrNotInGitRepository                    = errors.New("not inside a git repository")
	ErrCommandNil                            = errors.New("command cannot be nil")
	ErrProcessStartFailed                    = errors.New("process start failed")
	ErrProcessWaitFailed                     = errors.New("process wait failed")
	ErrGitHubRateLimitExceeded               = errors.New("GitHub API rate limit exceeded")
	ErrInvalidLimit                          = errors.New("limit must be between 1 and 100")
	ErrInvalidOffset                         = errors.New("offset must be >= 0")
	ErrDuplicateFlagRegistration             = errors.New("duplicate flag registration")
	ErrReservedFlagName                      = errors.New("reserved flag name")
	ErrInvalidSinceDate                      = errors.New("invalid date format for --since")
	ErrTerminalTooNarrow                     = errors.New("terminal too narrow")
	ErrSpinnerReturnedNilModel               = errors.New("spinner returned nil model")
	ErrSpinnerUnexpectedModelType            = errors.New("spinner returned unexpected model type")
	ErrSpinnerOperationInterrupted           = errors.New("operation was interrupted")

	// Version Tracker errors.
	ErrVersionTrackNotFound          = errors.New("version track not found")
	ErrVersionNotFound               = errors.New("version not found")
	ErrVersionNotLocked              = errors.New("version not locked")
	ErrVersionTrackNotVerified       = errors.New("version track is not verified")
	ErrDesiredVersionRequired        = errors.New("desired version is required")
	ErrVersionEntryExists            = errors.New("version entry already exists")
	ErrVersionEntryNotFound          = errors.New("version entry not found")
	ErrInvalidVersionCooldown        = errors.New("invalid cooldown")
	ErrVersionRenderFileRequired     = errors.New("--file is required")
	ErrVersionRenderDrift            = errors.New("rendered output differs from committed file")
	ErrUnsupportedVersionTrackFormat = errors.New("unsupported output format (supported: yaml, json)")
	ErrUnsupportedVersionShow        = errors.New("unsupported --show value (supported: desired, locked)")
	ErrUnsupportedVersionField       = errors.New("unsupported --show value (supported: name, ecosystem, datasource, provider, package, desired, group, update, include, exclude, prerelease, labels, locked)")
	ErrVersionFilesDrift             = errors.New("version-managed files are out of date; run `atmos version track apply`")
	ErrUnknownVersionFileManager     = errors.New("unknown file manager")
	ErrDuplicateVersionFileManager   = errors.New("duplicate file manager registration")
	ErrVersionMarkerBadMatch         = errors.New("marker match expression must compile and contain one capture group")

	// Theme-related errors.
	ErrThemeNotFound = errors.New("theme not found")
	ErrInvalidTheme  = errors.New("invalid theme")

	// Experimental feature errors.
	ErrExperimentalDisabled   = errors.New("experimental command is disabled")
	ErrExperimentalRequiresIn = errors.New("experimental command requires explicit opt-in")

	// Authentication and TTY errors.
	ErrAuthConsole          = errors.New("auth console operation failed")
	ErrProviderNotSupported = errors.New("provider does not support this operation")
	// ErrWebflowRequiresAWSUser indicates --webflow was used without a direct aws/user identity.
	ErrWebflowRequiresAWSUser = errors.New("--webflow requires an aws/user identity")
	ErrUnknownServiceAlias    = errors.New("unknown service alias")
	ErrUnknownHelpTopic       = errors.New("unknown help topic")
	ErrTTYRequired            = errors.New("requires a TTY")
	ErrInvalidAuthManagerType = errors.New("invalid authManager type")

	// Component and positional argument errors.
	ErrComponentRequired          = errors.New("component is required")
	ErrInvalidPositionalArgs      = errors.New("invalid positional arguments")
	ErrWorkflowNameRequired       = errors.New("workflow name is required")
	ErrInvalidStackConfiguration  = errors.New("invalid stack configuration")
	ErrPathNotWithinComponentBase = errors.New("path is not within component base path")
	ErrStackRequired              = errors.New("--stack flag is required")
	ErrStackHasNoLocals           = errors.New("stack has no locals defined")
	ErrNoStackManifestsFound      = errors.New("no stack manifests found")

	// ErrPlanHasDiff is returned when there are differences between two Terraform plan files.
	ErrPlanHasDiff = errors.New("plan files have differences")

	// ErrPlanVerificationFailed is returned when a stored planfile differs from the current state during --verify-plan.
	ErrPlanVerificationFailed = errors.New("plan verification failed: stored plan differs from current state")

	// ErrStoredPlanfileMissing is returned when a deploy expected a stored planfile to verify against but none was found.
	ErrStoredPlanfileMissing = errors.New("plan verification failed: no stored planfile was found to verify against")

	// ErrPlanfileStorageNotConfigured is returned when planfile verification is explicitly requested (`--verify-plan`) but no planfile storage is configured.
	ErrPlanfileStorageNotConfigured = errors.New("planfile verification was requested but planfile storage is not configured")

	ErrInvalidTerraformFlagsWithAffectedFlag                 = errors.New("the `--affected` flag can't be used with the other multi-component (bulk operations) flags `--all`, `--query` and `--components`")
	ErrInvalidTerraformComponentWithMultiComponentFlags      = errors.New("the component argument can't be used with the multi-component (bulk operations) flags `--affected`, `--all`, `--query`, `--components`, `--tags` and `--labels`")
	ErrInvalidTerraformSingleComponentAndMultiComponentFlags = errors.New("the single-component flags (`--from-plan`, `--planfile`) can't be used with the multi-component (bulk operations) flags (`--affected`, `--all`, `--query`, `--components`)")
	ErrClosureFlagsRequireMultiComponent                     = errors.New("the `--include-dependencies` and `--include-dependents` flags expand a multi-component selection and require one of `--all`, `--components`, `--query`, `-s`, `--tags`, `--labels`, or `--affected`")

	ErrYamlFuncInvalidArguments         = errors.New("invalid number of arguments in the Atmos YAML function")
	ErrYamlFuncMaxResolutionDepth       = errors.New("Atmos YAML function resolution exceeded the maximum dependency depth (likely an undetected circular dependency)")
	ErrAwsGetCallerIdentity             = errors.New("failed to get AWS caller identity")
	ErrUnsupportedYamlTag               = errors.New("unsupported YAML tag")
	ErrAwsDescribeOrganization          = errors.New("failed to describe AWS organization")
	ErrDescribeComponent                = errors.New("failed to describe component")
	ErrReadTerraformState               = errors.New("failed to read Terraform state")
	ErrEvaluateTerraformBackendVariable = errors.New("failed to evaluate terraform backend variable")
	ErrEvaluateOutput                   = errors.New("failed to evaluate output expression")

	// Recoverable YAML function errors - use YQ default if available.
	// These errors indicate the data is not available but do not represent API failures.
	ErrTerraformStateNotProvisioned = errors.New("terraform state not provisioned")
	ErrTerraformOutputNotFound      = errors.New("terraform output not found")
	ErrTerraformOutputFailed        = errors.New("failed to retrieve terraform outputs")

	// Terraform output component configuration errors.
	ErrMissingExecutable      = errors.New("component does not have 'command' (executable) defined")
	ErrMissingWorkspace       = errors.New("component does not have terraform workspace defined")
	ErrMissingComponentInfo   = errors.New("component does not have 'component_info' defined")
	ErrInvalidComponentInfoS  = errors.New("component has invalid 'component_info' section")
	ErrMissingComponentPath   = errors.New("component has invalid 'component_info.component_path'")
	ErrBackendFileGeneration  = errors.New("failed to generate backend file")
	ErrProviderFileGeneration = errors.New("failed to generate provider override file")
	ErrTerraformInit          = errors.New("terraform init failed")
	ErrTerraformWorkspaceOp   = errors.New("terraform workspace operation failed")

	// Terraform lint errors.
	ErrTerraformLint             = errors.New("terraform lint failed")
	ErrTerraformLintAuth         = errors.New("failed to initialize authentication for terraform lint")
	ErrTerraformLintAffected     = errors.New("failed to determine affected terraform lint targets")
	ErrBuildTerraformLintTargets = errors.New("failed to build terraform lint targets")

	// --use-mocks errors.
	ErrTerraformComponentMocksNotDeclared = errors.New("terraform component does not declare `mocks` required by --use-mocks")
	ErrTerraformMockOutputNotDeclared     = errors.New("mocked terraform output is not declared for component")

	// API/infrastructure errors - should cause non-zero exit.
	// These errors indicate backend API failures that should not use YQ defaults.
	ErrTerraformBackendAPIError  = errors.New("terraform backend API error")
	ErrUnsupportedBackendType    = errors.New("unsupported backend type")
	ErrProcessTerraformStateFile = errors.New("error processing terraform state file")
	ErrGetObjectFromS3           = errors.New("failed to get object from S3")
	ErrReadS3ObjectBody          = errors.New("failed to read S3 object body")
	ErrS3BucketAccessDenied      = errors.New("access denied to S3 bucket")
	ErrInvalidSSECustomerKey     = errors.New("invalid SSE-C customer encryption key")
	ErrCreateGCSClient           = errors.New("failed to create GCS client")
	ErrGetObjectFromGCS          = errors.New("failed to get object from GCS")
	ErrReadGCSObjectBody         = errors.New("failed to read GCS object body")
	ErrGCSBucketRequired         = errors.New("bucket is required for gcs backend")
	ErrInvalidBackendConfig      = errors.New("invalid backend configuration")

	// Azure Blob Storage specific errors.
	ErrGetBlobFromAzure       = errors.New("failed to get blob from Azure Blob Storage")
	ErrReadAzureBlobBody      = errors.New("failed to read Azure blob body")
	ErrCreateAzureCredential  = errors.New("failed to create Azure credential")
	ErrCreateAzureClient      = errors.New("failed to create Azure Blob Storage client")
	ErrAzureContainerRequired = errors.New("container_name is required for azurerm backend")
	ErrStorageAccountRequired = errors.New("storage_account_name is required for azurerm backend")
	ErrAzurePermissionDenied  = errors.New("permission denied accessing Azure blob")

	// Azure authentication errors.
	ErrAzureOIDClaimNotFound       = errors.New("oid claim not found in token")
	ErrAzureUsernameClaimNotFound  = errors.New("no username claim found in token (tried upn, unique_name, email)")
	ErrAzureInvalidJWTFormat       = errors.New("invalid JWT format")
	ErrAzureExpirationTimeEmpty    = errors.New("expiration time is empty")
	ErrAzureTimeParseFailure       = errors.New("unable to parse time: tried RFC3339, local time formats, and Unix timestamp")
	ErrAzureNoAccountsInCache      = errors.New("no accounts found in cache")
	ErrAzureNoAccountForTenant     = errors.New("no account found for tenant")
	ErrBackendConfigRequired       = errors.New("backend configuration is required")
	ErrBackendTypeRequired         = errors.New("backend_type is required")
	ErrBackendSectionMissing       = errors.New("no 'backend' section configured")
	ErrBackendTypeMissing          = errors.New("no 'backend_type' configured")
	ErrBackendTypeEmptyAfterRender = errors.New("'backend_type' is empty after template processing")
	ErrBackendConfigEmpty          = errors.New("'backend' section is empty but 'backend_type' requires configuration")

	// Git-related errors.
	ErrGitNotAvailable             = errors.New("git must be available and on the PATH")
	ErrGitRoot                     = errors.New("failed to get git repository root")
	ErrGitSHA                      = errors.New("failed to get git SHA")
	ErrGitBranch                   = errors.New("failed to get git branch")
	ErrGitRef                      = errors.New("failed to get git ref")
	ErrGitWorktree                 = errors.New("failed to get git worktree")
	ErrDetachedHead                = errors.New("git HEAD is detached")
	ErrEmptyBranchName             = errors.New("git branch name is empty")
	ErrInvalidGitPort              = errors.New("invalid port number")
	ErrSSHKeyUsage                 = errors.New("error using SSH key")
	ErrGitCommandExited            = errors.New("git command exited with non-zero status")
	ErrGitCommandFailed            = errors.New("failed to execute git command")
	ErrReadDestDir                 = errors.New("failed to read the destination directory during git update")
	ErrRemoveGitDir                = errors.New("failed to remove the .git directory in the destination directory during git update")
	ErrUnexpectedGitOutput         = errors.New("unexpected 'git version' output")
	ErrUnexpectedGitRevParseOutput = errors.New("unexpected 'git rev-parse' output")
	ErrGitVersionMismatch          = errors.New("git version requirement not met")
	ErrRemoteRepoNotGitRepo        = errors.New("target remote repository is not a git repository")
	ErrFailedToGetLocalRepo        = errors.New("failed to get local repository")
	ErrFailedToGetRepoInfo         = errors.New("failed to get repository info")
	ErrLocalRepoFetch              = errors.New("local repo unavailable")
	ErrGitRefNotFound              = errors.New("git reference not found on local filesystem")
	ErrGitFileNotFound             = errors.New("file not found in git reference")
	ErrGitWorktreeAdd              = errors.New("failed to create git worktree")
	ErrGitWorktreePruneIncomplete  = errors.New("git worktree prune completed but worktree path still exists")
	ErrFetchOrigin                 = errors.New("failed to fetch from origin")
	ErrDeepenOrigin                = errors.New("failed to deepen fetch from origin")
	ErrGitRepositoryNotFound       = errors.New("git repository not configured")
	ErrGitAuthFailed               = errors.New("git authentication failed")
	ErrGitPushRejected             = errors.New("git push rejected: non-fast-forward")
	ErrGitDirtyUnmanagedFiles      = errors.New("unmanaged dirty files detected outside commit paths")
	ErrGitPathEscapesWorktree      = errors.New("path resolves outside git worktree")
	ErrGitHookNotConfigured        = errors.New("git hook not configured")
	ErrGitRepositoryRequired       = errors.New("git repository name or URI is required")
	ErrGitProviderNotFound         = errors.New("git provider not registered")
	ErrGitWorkdirExists            = errors.New("git workdir already exists")
	ErrGitNoTrackingBranch         = errors.New("no branch to pull: the current branch has no upstream")
	ErrGitWorkdirNotInitialized    = errors.New("git repository not cloned or initialized")
	ErrGitTargetPathInvalid        = errors.New("git target path must not be empty or the repository root")
	ErrGitArtifactWrite            = errors.New("failed to write provision artifact")
	ErrUnsafeForkCheckout          = errors.New("refusing to clone untrusted fork content in an elevated CI event")
	ErrGitArtifactRead             = errors.New("failed to read provision artifact")

	// I/O and output errors.
	ErrBuildIOConfig  = errors.New("failed to build I/O config")
	ErrUnknownStream  = errors.New("unknown I/O stream")
	ErrWriteToStream  = errors.New("failed to write to stream")
	ErrMaskingContent = errors.New("failed to mask content")
	ErrHeadLookup     = errors.New("HEAD not found")
	ErrInvalidFormat  = errors.New("invalid format")
	ErrOutputFormat   = errors.New("output format error")

	// File operation errors.
	ErrRefusingToDeleteSymlink = ErrRefuseDeleteSymbolicLink

	// Scheduler errors.
	ErrNilGraph      = errors.New("scheduler graph cannot be nil")
	ErrNilDispatcher = errors.New("scheduler dispatcher cannot be nil")
	ErrNodeFailed    = errors.New("scheduler node failed")
	ErrNodeSkipped   = errors.New("scheduler node skipped")
	ErrNodeNotFound  = errors.New("scheduler node not found")
	ErrInvalidGraph  = errors.New("scheduler graph is invalid")
	ErrInvalidWorker = errors.New("scheduler max concurrency must be greater than zero")

	// Slice utility errors.
	ErrNilInput         = errors.New("input must not be nil")
	ErrNonStringElement = errors.New("element is not a string")

	// Merge-related errors.
	ErrEmptyPath                = errors.New("empty path")
	ErrCannotNavigatePath       = errors.New("cannot navigate path: field is not a map")
	ErrUnknownListMergeStrategy = errors.New("unknown list merge strategy")

	ErrReadFile    = errors.New("error reading file")
	ErrInvalidFlag = errors.New("invalid flag")

	// ErrForbiddenSelectorFunction enforces the selector purity contract:
	// metadata.tags/metadata.labels drive scoping decisions before evaluation,
	// so by design they may not contain constructs that require authentication
	// or process execution (e.g. !terraform.state, !store, !exec, atmos.Component).
	ErrForbiddenSelectorFunction = errors.New("forbidden function in labels/tags selector")

	// Dependency management errors.
	ErrDependencyConstraint = errors.New("dependency constraint validation failed")
	ErrDependencyResolution = errors.New("dependency resolution failed")
	ErrToolInstall          = errors.New("tool installation failed")

	// Helm plugin errors.
	ErrInvalidHelmPluginSpec = errors.New("invalid helm plugin specification")
	ErrHelmPluginInstall     = errors.New("helm plugin installation failed")
	ErrHelmBinaryNotFound    = errors.New("helm binary not found")

	// Toolchain errors.
	ErrToolNotFound                    = errors.New("tool not found")
	ErrInvalidToolSpec                 = errors.New("invalid tool specification")
	ErrToolAlreadyInstalled            = errors.New("tool already installed")
	ErrDownloadFailed                  = errors.New("download failed")
	ErrDownloadRetryable               = errors.New("retryable download error")
	ErrSignatureRetryable              = errors.New("retryable signature verification error")
	ErrExtractionFailed                = errors.New("extraction failed")
	ErrChecksumMismatch                = errors.New("checksum mismatch")
	ErrNoVersionsInstalled             = errors.New("no versions installed")
	ErrLatestFileNotFound              = errors.New("latest version file not found")
	ErrRegistryNotReachable            = errors.New("registry not reachable")
	ErrToolNotInRegistry               = errors.New("tool not in registry")
	ErrToolPlatformNotSupported        = errors.New("tool does not support this platform")
	ErrAliasNotFound                   = errors.New("alias not found")
	ErrBinaryNotExecutable             = errors.New("binary not executable")
	ErrBinaryNotFound                  = errors.New("binary not found")
	ErrLockfileVersionMismatch         = errors.New("lockfile version mismatch")
	ErrNoAssetTemplate                 = errors.New("no asset template defined")
	ErrAssetTemplateInvalid            = errors.New("asset template invalid")
	ErrToolVersionsFileOperation       = errors.New("tool-versions file operation failed")
	ErrNoToolsConfigured               = errors.New("no tools configured")
	ErrUnsupportedVersionConstraint    = errors.New("unsupported version constraint format")
	ErrToolchainPlainFormatWithAllFlag = errors.New("--format=plain can't be used with --all")

	// Flag validation errors.
	ErrCompatibilityFlagMissingTarget = errors.New("compatibility flag references non-existent flag")
	ErrInvalidFlagValue               = errors.New("invalid value for flag")

	// File and URL handling errors.
	ErrInvalidPagerCommand   = errors.New("invalid pager command")
	ErrEmptyURL              = errors.New("empty URL provided")
	ErrFailedToFindImport    = errors.New("failed to find import")
	ErrInvalidFilePath       = errors.New("invalid file path")
	ErrRelPath               = errors.New("error determining relative path")
	ErrHTTPRequestFailed     = errors.New("HTTP request failed")
	ErrRedirectLimitExceeded = errors.New("stopped after 10 redirects")

	// Config loading errors.
	ErrAtmosDirConfigNotFound      = errors.New("atmos config directory not found")
	ErrReadConfig                  = errors.New("failed to read config")
	ErrMergeTempConfig             = errors.New("failed to merge temp config")
	ErrPreprocessYAMLFunctions     = errors.New("failed to preprocess YAML functions")
	ErrMergeEmbeddedConfig         = errors.New("failed to merge embedded config")
	ErrExpectedDirOrPattern        = errors.New("expected directory or pattern")
	ErrFileNotFound                = errors.New("file not found")
	ErrFileAccessDenied            = errors.New("file access denied")
	ErrExpectedFile                = errors.New("expected file")
	ErrAtmosArgConfigNotFound      = errors.New("atmos configuration not found")
	ErrEmptyConfigPath             = errors.New("config path is empty")
	ErrEmptyConfigFile             = errors.New("config file path is empty")
	ErrAtmosFilesDirConfigNotFound = errors.New("atmos configuration file not found in directory")
	ErrAtmosConfigNotFound         = errors.New("atmos configuration file not found")

	// Profile errors.
	ErrProfileNotFound         = errors.New("profile not found")
	ErrProfileSyntax           = errors.New("profile syntax error")
	ErrProfileDiscovery        = errors.New("failed to discover profiles")
	ErrProfileLoad             = errors.New("failed to load profile")
	ErrProfileMerge            = errors.New("failed to merge profile configuration")
	ErrProfileDirNotExist      = errors.New("profile directory does not exist")
	ErrProfileDirNotAccessible = errors.New("profile directory not accessible")
	ErrProfileInvalidMetadata  = errors.New("invalid profile metadata")

	ErrMissingStack             = errors.New("stack is required; specify it on the command line using the flag `--stack <stack>` (shorthand `-s`)")
	ErrMissingComponent         = errors.New("component is required")
	ErrNoStacksToSelect         = errors.New("no stacks are configured to choose from")
	ErrNoComponentsToSelect     = errors.New("no components are configured to choose from")
	ErrLoadSelectionOptions     = errors.New("failed to load options for interactive selection")
	ErrMissingComponentType     = errors.New("component type is required")
	ErrRequiredFlagNotProvided  = errors.New("required flag not provided")
	ErrRequiredFlagEmpty        = errors.New("required flag cannot be empty")
	ErrInvalidArguments         = errors.New("invalid arguments")
	ErrUnknownSubcommand        = errors.New("unknown subcommand")
	ErrInvalidComponent         = errors.New("invalid component")
	ErrDuplicateComponentConfig = errors.New("duplicate component configuration")
	// ErrInvalidStack indicates the user provided an identifier that doesn't match
	// the stack's canonical name (e.g., using filename when explicit name is set).
	// This differs from ErrStackNotFound which indicates the stack doesn't exist at all.
	ErrInvalidStack                               = errors.New("invalid stack")
	ErrInvalidComponentMapType                    = errors.New("invalid component map type")
	ErrAbstractComponentCantBeProvisioned         = errors.New("abstract component cannot be provisioned")
	ErrLockedComponentCantBeProvisioned           = errors.New("locked component cannot be provisioned")
	ErrSpaceliftAdminStackWorkspaceNotEnabled     = errors.New("spacelift admin stack does not have workspace enabled")
	ErrSpaceliftAdminStackComponentNotProvisioned = errors.New("spacelift admin stack component cannot be provisioned")

	// Terraform-specific errors.
	ErrHTTPBackendWorkspaces            = errors.New("workspaces are not supported for the HTTP backend")
	ErrInvalidTerraformComponent        = errors.New("invalid Terraform component")
	ErrNoTty                            = errors.New("no TTY attached")
	ErrNoSuitableShell                  = errors.New("no suitable shell found")
	ErrFailedToLoadTerraformComponent   = errors.New("failed to load terraform component")
	ErrNoJSONOutput                     = errors.New("no JSON output found in terraform show output")
	ErrOriginalPlanFileRequired         = errors.New("original plan file is required")
	ErrOriginalPlanFileNotExist         = errors.New("original plan file does not exist")
	ErrNewPlanFileNotExist              = errors.New("new plan file does not exist")
	ErrTerraformGenerateBackendArgument = errors.New("invalid arguments")
	ErrFileTemplateRequired             = errors.New("file-template is required")
	ErrInteractiveNotAvailable          = errors.New("interactive confirmation not available in non-TTY environment")
	ErrDeprecatedCmdNotCallable         = errors.New("deprecated command should not be called")

	ErrMissingPackerTemplate = errors.New("packer template is required")
	ErrMissingPackerManifest = errors.New("packer manifest is missing")

	ErrAtmosConfigIsNil              = errors.New("atmos config is nil")
	ErrFailedToInitializeAtmosConfig = errors.New("failed to initialize atmos config")
	ErrInvalidListMergeStrategy      = errors.New("invalid list merge strategy")
	ErrMerge                         = errors.New("merge error")
	ErrMergeNilDst                   = errors.New("merge destination must not be nil")
	ErrMergeTypeMismatch             = errors.New("cannot override two slices with different type")
	ErrMergeKeyCollision             = errors.New("distinct map keys collide after normalization")
	ErrEncode                        = errors.New("encoding error")
	ErrDecode                        = errors.New("decoding error")

	// Stack processing errors.
	ErrStackManifestFileNotFound                  = errors.New("stack manifest file not found")
	ErrInvalidStackManifest                       = errors.New("invalid stack manifest")
	ErrStackManifestSchemaValidation              = errors.New("stack manifest schema validation failed")
	ErrStackImportSelf                            = errors.New("stack manifest imports itself")
	ErrStackImportNotFound                        = errors.New("stack import not found")
	ErrImportPathTemplate                         = errors.New("failed to render Go template in import path")
	ErrStackCircularInheritance                   = errors.New("circular component inheritance detected")
	ErrInvalidHooksSection                        = errors.New("invalid 'hooks' section in the file")
	ErrInvalidTerraformHooksSection               = errors.New("invalid 'terraform.hooks' section in the file")
	ErrInvalidComponentVars                       = errors.New("invalid component vars section")
	ErrInvalidComponentLocals                     = errors.New("invalid component locals section")
	ErrInvalidComponentSettings                   = errors.New("invalid component settings section")
	ErrInvalidComponentEnv                        = errors.New("invalid component env section")
	ErrInvalidComponentProviders                  = errors.New("invalid component providers section")
	ErrInvalidComponentRequiredProviders          = errors.New("invalid component required_providers section")
	ErrInvalidComponentRequiredVersion            = errors.New("invalid component required_version attribute")
	ErrInvalidComponentHooks                      = errors.New("invalid component hooks section")
	ErrUnknownHookKind                            = errors.New("unknown hook kind")
	ErrInvalidHookOnFailure                       = errors.New("invalid hook on_failure value")
	ErrInvalidComponentSecrets                    = errors.New("invalid component secrets section")
	ErrStoreIsSecret                              = errors.New("store is a secret store; use !secret instead of !store")
	ErrInvalidComponentGenerate                   = errors.New("invalid component generate section")
	ErrInvalidComponentAuth                       = errors.New("invalid component auth section")
	ErrInvalidComponentProvision                  = errors.New("invalid component provision section")
	ErrInvalidComponentMetadata                   = errors.New("invalid component metadata section")
	ErrInvalidComponentDependencies               = errors.New("invalid component dependencies section")
	ErrInvalidComponentBackendType                = errors.New("invalid component backend_type attribute")
	ErrInvalidComponentBackend                    = errors.New("invalid component backend section")
	ErrInvalidComponentRemoteStateBackendType     = errors.New("invalid component remote_state_backend_type attribute")
	ErrInvalidComponentRemoteStateBackend         = errors.New("invalid component remote_state_backend section")
	ErrInvalidComponentCommand                    = errors.New("invalid component command attribute")
	ErrInvalidComponentSource                     = errors.New("invalid component source section")
	ErrInvalidComponentOverrides                  = errors.New("invalid component overrides section")
	ErrInvalidComponentOverridesVars              = errors.New("invalid component overrides vars section")
	ErrInvalidComponentOverridesSettings          = errors.New("invalid component overrides settings section")
	ErrInvalidComponentOverridesEnv               = errors.New("invalid component overrides env section")
	ErrInvalidComponentOverridesAuth              = errors.New("invalid component overrides auth section")
	ErrInvalidComponentOverridesCommand           = errors.New("invalid component overrides command attribute")
	ErrInvalidComponentOverridesProviders         = errors.New("invalid component overrides providers section")
	ErrInvalidComponentOverridesRequiredProviders = errors.New("invalid component overrides required_providers section")
	ErrInvalidComponentOverridesRequiredVersion   = errors.New("invalid component overrides required_version attribute")
	ErrInvalidComponentOverridesHooks             = errors.New("invalid component overrides hooks section")
	ErrInvalidComponentOverridesGenerate          = errors.New("invalid component overrides generate section")
	ErrInvalidComponentAttribute                  = errors.New("invalid component attribute")
	ErrInvalidComponentMetadataComponent          = errors.New("invalid component metadata.component attribute")
	ErrInvalidSpaceLiftSettings                   = errors.New("invalid spacelift settings section")
	ErrInvalidComponentMetadataInherits           = errors.New("invalid component metadata.inherits section")
	ErrComponentNotDefined                        = errors.New("component not defined in any config files")

	// Component registry errors.
	ErrComponentProviderNotFound     = errors.New("component provider not found")
	ErrComponentProviderNil          = errors.New("component provider cannot be nil")
	ErrComponentTypeEmpty            = errors.New("component type is empty")
	ErrComponentEmpty                = errors.New("component is empty")
	ErrStackEmpty                    = errors.New("stack is empty")
	ErrComponentConfigInvalid        = errors.New("component configuration invalid")
	ErrComponentListFailed           = errors.New("failed to list components")
	ErrComponentValidationFailed     = errors.New("component validation failed")
	ErrComponentExecutionFailed      = errors.New("component execution failed")
	ErrNoRunningContainer            = errors.New("no running container found")
	ErrComponentArtifactGeneration   = errors.New("component artifact generation failed")
	ErrComponentProviderRegistration = errors.New("failed to register component provider")

	// Emulator errors.
	ErrUnknownEmulatorDriver       = errors.New("unknown emulator driver")
	ErrEmulatorNotRunning          = errors.New("emulator is not running")
	ErrEmulatorNotConfigured       = errors.New("emulator is not configured")
	ErrEmulatorResolutionFailed    = errors.New("failed to resolve emulator")
	ErrEmulatorAmbiguous           = errors.New("emulator identity is ambiguous")
	ErrEmulatorTargetMismatch      = errors.New("emulator target does not match")
	ErrEmulatorConfigInvalid       = errors.New("emulator configuration invalid")
	ErrEmulatorResolverUnavailable = errors.New("emulator resolver is not available")
	ErrEmulatorResetFailed         = errors.New("emulator reset failed")

	ErrInvalidTerraformBackend            = errors.New("invalid terraform.backend section")
	ErrInvalidTerraformRemoteStateBackend = errors.New("invalid terraform.remote_state_backend section")
	ErrUnsupportedComponentType           = errors.New("unsupported component type")

	// Custom component errors.
	ErrCustomComponentTypeRegistration = errors.New("failed to register custom component type")
	ErrComponentArgumentNotFound       = errors.New("no argument or flag with type 'component' found")
	ErrStackArgumentNotFound           = errors.New("no argument or flag with type 'stack' found")

	// Generator errors.
	ErrGeneratorNotFound     = errors.New("generator not found")
	ErrInvalidGeneratorCtx   = errors.New("invalid generator context")
	ErrGeneratorValidation   = errors.New("generator validation failed")
	ErrGenerationFailed      = errors.New("generation failed")
	ErrGeneratorWriteFailed  = errors.New("failed to write generated file")
	ErrMissingWorkingDir     = errors.New("working directory is required")
	ErrMissingProviderSource = errors.New("required_providers entry missing 'source' field")

	// Archive package errors (pkg/archive).
	ErrArchiveUnknownFormat           = errors.New("unknown or unsupported archive format")
	ErrArchiveActionNotImplemented    = errors.New("archive action is not yet implemented")
	ErrArchiveUpdateUnsupportedFormat = errors.New("archive update is not supported for this format")
	ErrArchiveOptionsRequired         = errors.New("archive options are required")
	ErrArchiveSourceRequired          = errors.New("archive source is required")
	ErrArchiveSourceNotFound          = errors.New("archive source does not exist")
	ErrArchiveDestinationRequired     = errors.New("archive destination is required")
	ErrArchiveInvalidGlobPattern      = errors.New("invalid archive include/exclude glob pattern")
	ErrArchiveInvalidSubpath          = errors.New("invalid archive subpath")
	ErrArchiveFormatNotImplemented    = errors.New("archive format is not yet implemented")
	ErrArchiveWriteFailed             = errors.New("failed to write archive")
	ErrArchiveWalkFailed              = errors.New("failed to walk archive source")
	ErrArchiveInvalidMtimeMode        = errors.New("invalid archive mtime mode")

	// List command errors.
	ErrInvalidStackPattern          = errors.New("invalid stack pattern")
	ErrEmptyTargetComponentName     = errors.New("target component name cannot be empty")
	ErrComponentsSectionNotFound    = errors.New("components section not found in stack")
	ErrComponentNotFoundInSections  = errors.New("component not found in terraform or helmfile sections")
	ErrUnknownComposition           = errors.New("component references an undeclared composition")
	ErrUnknownCompositionMembership = errors.New("component claims membership in a service not declared by the composition")
	ErrQueryFailed                  = errors.New("query execution failed")
	ErrScalarExtractionNotSupported = errors.New("scalar extraction queries are not supported")
	ErrQueryUnexpectedResultType    = errors.New("query returned unexpected result type")
	ErrTableTooWide                 = errors.New("the table is too wide to display properly")
	ErrGettingCommonFlags           = errors.New("error getting common flags")
	ErrGettingAbstractFlag          = errors.New("error getting abstract flag")
	ErrGettingVarsFlag              = errors.New("error getting vars flag")
	ErrInitializingCLIConfig        = errors.New("error initializing CLI config")
	ErrDescribingStacks             = errors.New("error describing stacks")
	ErrComponentNameRequired        = errors.New("component name is required")
	ErrCreateColumnSelector         = errors.New("failed to create column selector")

	// Version command errors.
	ErrVersionDisplayFailed   = errors.New("failed to display version information")
	ErrVersionCheckFailed     = errors.New("failed to check for version updates")
	ErrVersionFormatInvalid   = errors.New("invalid version output format")
	ErrVersionCacheLoadFailed = errors.New("failed to load version check cache")
	ErrVersionGitHubAPIFailed = errors.New("failed to query GitHub API for releases")

	// Version constraint errors.
	ErrVersionConstraint        = errors.New("version constraint not satisfied")
	ErrInvalidVersionConstraint = errors.New("invalid version constraint")

	// Atlantis errors.
	ErrAtlantisInvalidFlags          = errors.New("incompatible atlantis flags")
	ErrAtlantisProjectTemplateNotDef = errors.New("atlantis project template is not defined")
	ErrAtlantisConfigTemplateNotDef  = errors.New("atlantis config template is not defined")
	ErrAtlantisConfigTemplateNotSpec = errors.New("atlantis config template is not specified")

	// Validation errors.
	ErrValidationFailed              = errors.New("validation failed")
	ErrUnsupportedValidationFormat   = errors.New("unsupported validation format: expected text or rich")
	ErrUnsupportedCIValidationFormat = errors.New("unsupported CI validation format: expected text, rich, or sarif")
	ErrWorkflowArgsWithWorkflowPath  = errors.New("workflow-file arguments cannot be used with --workflow-path")
	ErrAffectedWithFileArgsOrPath    = errors.New("--affected cannot be used with workflow-file arguments or --workflow-path")
	ErrCIValidatorNotRegistered      = errors.New("CI validator is not registered")

	// EditorConfig validation errors.
	ErrEditorConfigValidationFailed = errors.New("EditorConfig validation failed")
	ErrEditorConfigVersionMismatch  = errors.New("EditorConfig version mismatch")
	ErrEditorConfigGetFiles         = errors.New("failed to get files for EditorConfig validation")
	ErrEditorConfigInvalidFormat    = errors.New("invalid EditorConfig output format")

	// Global/Stack-level section errors.
	ErrInvalidVarsSection               = errors.New("invalid vars section")
	ErrInvalidSettingsSection           = errors.New("invalid settings section")
	ErrInvalidEnvSection                = errors.New("invalid env section")
	ErrInvalidGenerateSection           = errors.New("invalid generate section")
	ErrInvalidDependenciesSection       = errors.New("invalid dependencies section")
	ErrInvalidTerraformSection          = errors.New("invalid terraform section")
	ErrInvalidHelmfileSection           = errors.New("invalid helmfile section")
	ErrInvalidPackerSection             = errors.New("invalid packer section")
	ErrInvalidComponentsSection         = errors.New("invalid components section")
	ErrInvalidAuthSection               = errors.New("invalid auth section")
	ErrInvalidGlobalMetadataSection     = errors.New("invalid metadata section")
	ErrGlobalMetadataFieldNotAllowed    = errors.New("metadata field is not allowed at global (stack-wide) scope")
	ErrInvalidImportSection             = errors.New("invalid import section")
	ErrInvalidImport                    = errors.New("invalid import")
	ErrInvalidRemoteImport              = errors.New("invalid remote import")
	ErrDownloadRemoteImport             = errors.New("failed to download remote import")
	ErrCacheDirectoryCreation           = errors.New("failed to create cache directory")
	ErrClearCache                       = errors.New("failed to clear cache")
	ErrInvalidOverridesSection          = errors.New("invalid overrides section")
	ErrInvalidTerraformOverridesSection = errors.New("invalid terraform overrides section")
	ErrInvalidHelmOverridesSection      = errors.New("invalid helm overrides section")
	ErrInvalidHelmfileOverridesSection  = errors.New("invalid helmfile overrides section")
	ErrInvalidBaseComponentConfig       = errors.New("invalid base component config")
	ErrCircularComponentInheritance     = ErrStackCircularInheritance

	// Terraform-specific subsection errors.
	ErrInvalidTerraformCommand            = errors.New("invalid terraform command")
	ErrInvalidTerraformVars               = errors.New("invalid terraform vars section")
	ErrInvalidTerraformSettings           = errors.New("invalid terraform settings section")
	ErrInvalidTerraformEnv                = errors.New("invalid terraform env section")
	ErrInvalidTerraformProviders          = errors.New("invalid terraform providers section")
	ErrInvalidTerraformGenerateSection    = errors.New("invalid terraform generate section")
	ErrInvalidTerraformBackendType        = errors.New("invalid terraform backend_type")
	ErrMissingTerraformBackendType        = errors.New("'backend_type' is missing for the component")
	ErrMissingTerraformBackendConfig      = errors.New("'backend' config is missing for the component")
	ErrMissingTerraformWorkspaceKeyPrefix = errors.New("backend config is missing 'workspace_key_prefix'")
	ErrInvalidTerraformRemoteStateType    = errors.New("invalid terraform remote_state_backend_type")
	ErrInvalidTerraformRemoteStateSection = errors.New("invalid terraform remote_state_backend section")
	ErrInvalidTerraformAuth               = errors.New("invalid terraform auth section")
	ErrInvalidTerraformDependencies       = errors.New("invalid terraform dependencies section")
	ErrInvalidTerraformSource             = errors.New("invalid terraform source section")
	ErrInvalidTerraformProvision          = errors.New("invalid terraform provision section")
	ErrUnresolvedComputedTerraformVar     = errors.New("terraform variable contains an unresolved computed value")

	// Helmfile-specific subsection errors.
	ErrInvalidHelmfileCommand      = errors.New("invalid helmfile command")
	ErrInvalidHelmfileVars         = errors.New("invalid helmfile vars section")
	ErrInvalidHelmfileSettings     = errors.New("invalid helmfile settings section")
	ErrInvalidHelmfileEnv          = errors.New("invalid helmfile env section")
	ErrInvalidHelmfileAuth         = errors.New("invalid helmfile auth section")
	ErrInvalidHelmfileDependencies = errors.New("invalid helmfile dependencies section")

	// Helmfile configuration errors.
	ErrMissingHelmfileBasePath           = errors.New("helmfile base path is required")
	ErrMissingHelmfileKubeconfigPath     = errors.New("helmfile kubeconfig path is required")
	ErrMissingHelmfileAwsProfilePattern  = errors.New("helmfile AWS profile pattern is required")
	ErrMissingHelmfileClusterNamePattern = errors.New("helmfile cluster name pattern is required")
	ErrMissingHelmfileClusterName        = errors.New("helmfile cluster name is required")
	ErrMissingHelmfileAuth               = errors.New("helmfile AWS authentication is required")

	// Packer configuration errors.
	ErrMissingPackerBasePath = errors.New("packer base path is required")

	// Packer-specific subsection errors.
	ErrInvalidPackerCommand      = errors.New("invalid packer command")
	ErrInvalidPackerVars         = errors.New("invalid packer vars section")
	ErrInvalidPackerSettings     = errors.New("invalid packer settings section")
	ErrInvalidPackerEnv          = errors.New("invalid packer env section")
	ErrInvalidPackerAuth         = errors.New("invalid packer auth section")
	ErrInvalidPackerDependencies = errors.New("invalid packer dependencies section")

	// Ansible configuration errors.
	ErrMissingAnsibleBasePath = errors.New("ansible base path is required")

	// Ansible-specific subsection errors.
	ErrInvalidAnsibleSection      = errors.New("invalid ansible section")
	ErrInvalidAnsibleCommand      = errors.New("invalid ansible command")
	ErrInvalidAnsibleVars         = errors.New("invalid ansible vars section")
	ErrInvalidAnsibleSettings     = errors.New("invalid ansible settings section")
	ErrInvalidAnsibleEnv          = errors.New("invalid ansible env section")
	ErrInvalidAnsibleAuth         = errors.New("invalid ansible auth section")
	ErrInvalidAnsibleDependencies = errors.New("invalid ansible dependencies section")

	// Ansible execution errors.
	ErrAnsiblePlaybookMissing = errors.New("ansible playbook is required")

	// Component type-specific section errors.
	ErrInvalidComponentsTerraform = errors.New("invalid components.terraform section")
	ErrInvalidComponentsHelmfile  = errors.New("invalid components.helmfile section")
	ErrInvalidComponentsPacker    = errors.New("invalid components.packer section")
	ErrInvalidComponentsAnsible   = errors.New("invalid components.ansible section")

	// Specific component configuration errors.
	ErrInvalidSpecificTerraformComponent = errors.New("invalid terraform component configuration")
	ErrInvalidSpecificHelmfileComponent  = errors.New("invalid helmfile component configuration")
	ErrInvalidSpecificPackerComponent    = errors.New("invalid packer component configuration")
	ErrInvalidSpecificAnsibleComponent   = errors.New("invalid ansible component configuration")

	// Pro API client errors.
	ErrFailedToCreateRequest        = errors.New("failed to create request")
	ErrFailedToMarshalPayload       = errors.New("failed to marshal request body")
	ErrFailedToCreateAuthRequest    = errors.New("failed to create authenticated request")
	ErrFailedToMakeRequest          = errors.New("failed to make request")
	ErrFailedToUploadStacks         = errors.New("failed to upload stacks")
	ErrFailedToReadResponseBody     = errors.New("failed to read response body")
	ErrFailedToLockStack            = errors.New("failed to lock stack")
	ErrFailedToUnlockStack          = errors.New("failed to unlock stack")
	ErrOIDCWorkspaceIDRequired      = errors.New("workspace ID environment variable is required for OIDC authentication")
	ErrOIDCTokenExchangeFailed      = errors.New("failed to exchange OIDC token for Atmos token")
	ErrOIDCAuthFailedNoToken        = errors.New("OIDC authentication failed: no token")
	ErrNotInGitHubActions           = errors.New("not running in GitHub Actions or missing OIDC token environment variables")
	ErrFailedToGetOIDCToken         = errors.New("failed to get OIDC token")
	ErrFailedToDecodeOIDCResponse   = errors.New("failed to decode OIDC token response")
	ErrFailedToExchangeOIDCToken    = errors.New("failed to exchange OIDC token")
	ErrFailedToDecodeTokenResponse  = errors.New("failed to decode token response")
	ErrFailedToGetGitHubOIDCToken   = errors.New("failed to get GitHub OIDC token")
	ErrFailedToUploadInstances      = errors.New("failed to upload instances")
	ErrFailedToUploadInstanceStatus = errors.New("failed to upload instance status")
	ErrUploadRetryExhausted         = errors.New("upload failed after all retries")
	ErrTokenRefreshFailed           = errors.New("failed to refresh API token")
	ErrFailedToUnmarshalAPIResponse = errors.New("failed to unmarshal API response")
	ErrNilRequestDTO                = errors.New("nil request DTO")

	// Pro commit errors.
	ErrCommitMessageRequired = errors.New("commit message is required")
	ErrCommitMessageTooLong  = errors.New("commit message exceeds 500 characters")
	ErrCommentTooLong        = errors.New("comment exceeds 2000 characters")
	ErrBranchRequired        = errors.New("GITHUB_HEAD_REF is required (this command only runs in PR workflows)")
	ErrBranchInvalid         = errors.New("branch name contains invalid characters")
	ErrTooManyChanges        = errors.New("too many changed files (max 200)")
	ErrCommitInvalidFilePath = errors.New("invalid file path for commit")
	ErrFileTooLarge          = errors.New("file exceeds 2 MiB size limit")
	ErrFailedToStageChanges  = errors.New("failed to stage changes")
	ErrFailedToDetectChanges = errors.New("failed to detect git changes")
	ErrFailedToCreateCommit  = errors.New("failed to create commit via Atmos Pro")
	ErrStagingFlagConflict   = errors.New("--add and --all are mutually exclusive")
	ErrAPIResponseError      = errors.New("API response error")

	// Exec package errors.
	ErrComponentAndStackRequired     = errors.New("component and stack are both required")
	ErrFailedToCreateAPIClient       = errors.New("failed to create API client")
	ErrFailedToProcessArgs           = errors.New("failed to process command-line arguments")
	ErrFailedToInitConfig            = errors.New("failed to initialize Atmos configuration")
	ErrFailedToCreateLogger          = errors.New("failed to create logger")
	ErrFailedToGetComponentFlag      = errors.New("failed to get '--component' flag")
	ErrFailedToGetStackFlag          = errors.New("failed to get '--stack' flag")
	ErrOPAPolicyViolations           = errors.New("OPA policy violations detected")
	ErrOPATimeout                    = errors.New("timeout evaluating OPA policy")
	ErrInvalidRegoPolicy             = errors.New("invalid Rego policy")
	ErrInvalidOPAPolicy              = errors.New("invalid OPA policy")
	ErrTerraformEnvCliVarJSON        = errors.New("failed to parse JSON variable from TF_CLI_ARGS environment variable")
	ErrWorkflowBasePathNotConfigured = errors.New("'workflows.base_path' must be configured in 'atmos.yaml'")
	ErrWorkflowDirectoryDoesNotExist = errors.New("workflow directory does not exist")
	ErrWorkflowNoSteps               = errors.New("workflow has no steps defined")
	ErrInvalidWorkflowStepType       = errors.New("invalid workflow step type")
	ErrInvalidFromStep               = errors.New("invalid from-step flag")
	ErrWorkflowStepFailed            = errors.New("workflow step execution failed")
	ErrWorkflowNoWorkflow            = errors.New("no workflow found")
	ErrWorkflowFileNotFound          = errors.New("workflow file not found")
	ErrInvalidWorkflowManifest       = errors.New("invalid workflow manifest")
	ErrUnknownStepType               = errors.New("unknown step type")
	ErrStepOptionsRequired           = errors.New("options is required for step")
	ErrStepContentOrOptionsRequired  = errors.New("either content or options is required for step")
	ErrStepDataOrContentRequired     = errors.New("either data or content is required for step")
	ErrStepEmptyCommand              = errors.New("empty command for step")
	ErrStepNoFilesFound              = errors.New("no files found matching criteria")
	ErrStepFieldRequired             = errors.New("required field missing for step")
	ErrStepExecutionFailed           = errors.New("step execution failed")
	ErrStepTTYRequired               = errors.New("interactive terminal required for step")
	ErrHTTPStepURLRequired           = errors.New("url is required for http step")
	ErrHTTPStepInvalidMethod         = errors.New("invalid HTTP method for http step")
	ErrHTTPStepBodyFormConflict      = errors.New("http step cannot set both body and form")
	ErrHTTPStepInvalidExpectPattern  = errors.New("invalid expect.response regex pattern for http step")
	ErrHTTPStepRequestFailed         = errors.New("http request failed")
	ErrHTTPStepUnexpectedStatus      = errors.New("http response did not match expected status")
	ErrHTTPStepUnexpectedResponse    = errors.New("http response body did not match expected pattern")
	ErrArchiveStepInvalidAction      = errors.New("invalid action for archive step")
	ErrArchiveStepInvalidSource      = errors.New("archive step source must be a string path")
	ErrStoreStepInvalidAction        = errors.New("invalid action for store step")
	ErrStoreStepWriteFailed          = errors.New("store step failed to write value")
	ErrRequireStepEmpty              = errors.New("require step must specify at least one of tools, files, or dirs")
	ErrRequirementsNotMet            = errors.New("required tools or paths are missing")
	ErrWorkingDirNotFound            = errors.New("working directory does not exist")
	ErrWorkingDirNotDirectory        = errors.New("working directory path is not a directory")
	ErrWorkingDirAccessFailed        = errors.New("failed to access working directory")
	ErrWorkflowExit                  = errors.New("workflow exit requested")
	ErrAuthProviderNotAvailable      = errors.New("auth provider is not available")
	ErrInvalidComponentArgument      = errors.New("invalid arguments. The command requires one argument 'componentName'")
	ErrValidation                    = errors.New("validation failed")
	ErrCUEValidationUnsupported      = errors.New("validation using CUE is not supported yet")

	// List package errors.
	ErrExecuteDescribeStacks     = errors.New("failed to execute describe stacks")
	ErrProcessInstances          = errors.New("failed to process instances")
	ErrParseFlag                 = errors.New("failed to parse flag value")
	ErrFailedToFinalizeCSVOutput = errors.New("failed to finalize CSV output")
	ErrParseStacks               = errors.New("could not parse stacks")
	ErrParseComponents           = errors.New("could not parse components")
	ErrNoComponentsFound         = errors.New("no components found")
	ErrNoStacksFound             = errors.New("no stacks found")
	ErrStackNotFound             = errors.New("stack not found")
	ErrProcessStack              = errors.New("error processing stack")

	// Dependency errors.
	ErrUnsupportedDependencyType = errors.New("unsupported dependency type")
	ErrMissingDependencyField    = errors.New("dependency missing required field")
	ErrDependencyTargetNotFound  = errors.New("dependency target not found")

	// Terraform --all flag errors.
	ErrComponentWithAllFlagConflict = errors.New("component argument can't be used with --all flag")

	// ErrCacheCertUntrusted is returned when the OS trust store does not trust the
	// registry cache proxy's certificate (macOS/Windows require a one-time trust step).
	ErrCacheCertUntrusted = errors.New("registry cache certificate is not trusted")

	// ErrTrustStore is returned when installing or removing the registry cache proxy's
	// certificate in the OS trust store fails.
	ErrTrustStore = errors.New("registry cache trust store operation failed")

	// Terraform execution errors.
	ErrTerraformExecFailed          = errors.New("terraform execution failed")
	ErrDescribeAffected             = errors.New("describe affected failed")
	ErrUploadRequiresSupportedEvent = errors.New("upload requires a supported CI event")
	ErrDescribeStacks               = errors.New("describe stacks failed")
	ErrBuildDepGraph                = errors.New("build dependency graph failed")
	ErrTopologicalOrder             = errors.New("topological sort failed")
	ErrGraphExecutionCanceled       = errors.New("graph execution canceled")
	ErrGraphExecutionOptions        = errors.New("graph execution options are invalid")
	ErrFormatForLogging             = errors.New("format affected for logging failed")
	ErrQueryEvaluation              = errors.New("query evaluation failed")
	ErrNilResult                    = errors.New("nil result")

	// Cache-related errors.
	ErrCacheLocked    = errors.New("cache file is locked")
	ErrCacheRead      = errors.New("cache read failed")
	ErrCacheWrite     = errors.New("cache write failed")
	ErrCacheFetch     = errors.New("failed to fetch content for cache")
	ErrCacheUnmarshal = errors.New("cache unmarshal failed")
	ErrCacheMarshal   = errors.New("cache marshal failed")
	ErrCacheDir       = errors.New("cache directory creation failed")

	// Logger errors.
	ErrInvalidLogLevel = errors.New("invalid log level")

	// File operation errors.
	ErrCopyFile            = errors.New("failed to copy file")
	ErrCreateDirectory     = errors.New("failed to create directory")
	ErrCreateFile          = errors.New("failed to create file")
	ErrOpenFile            = errors.New("failed to open file")
	ErrWriteFile           = errors.New("failed to write to file")
	ErrCloseFile           = errors.New("failed to close file")
	ErrStatFile            = errors.New("failed to stat file")
	ErrRemoveDirectory     = errors.New("failed to remove directory")
	ErrSetPermissions      = errors.New("failed to set permissions")
	ErrReadDirectory       = errors.New("failed to read directory")
	ErrComputeRelativePath = errors.New("failed to compute relative path")
	ErrFileOperation       = errors.New("file operation failed")

	// OCI/Container image errors.
	ErrCreateTempDirectory   = ErrCreateTempDir // Alias to avoid duplicate sentinels
	ErrInvalidImageReference = errors.New("invalid image reference")
	ErrPullImage             = errors.New("failed to pull image")
	ErrGetImageDescriptor    = errors.New("cannot get a descriptor for the OCI image")
	ErrGetImageLayers        = errors.New("failed to get image layers")
	ErrProcessLayer          = errors.New("failed to process layer")
	ErrLayerDecompression    = errors.New("layer decompression error")
	ErrLayerExtraction       = errors.New("layer extraction error")
	ErrArchiveTooLarge       = errors.New("archive exceeds maximum size")
	ErrArchiveEntryTooLarge  = errors.New("archive entry exceeds maximum extracted size")

	// Initialization and configuration errors.
	ErrInitializeCLIConfig    = errors.New("error initializing CLI config")
	ErrGetHooks               = errors.New("error getting hooks")
	ErrPerComponentHookFailed = errors.New("per-component hook failed")
	ErrSetFlag                = errors.New("failed to set flag")
	ErrVersionMismatch        = errors.New("version mismatch")

	// Download and client errors.
	ErrMergeConfiguration = errors.New("failed to merge configuration")

	// Template and documentation errors.
	ErrGenerateTerraformDocs = errors.New("failed to generate terraform docs")
	ErrMergeInputYAMLs       = errors.New("failed to merge input YAMLs")
	ErrRenderTemplate        = errors.New("failed to render template with datasources")
	ErrResolveOutputPath     = errors.New("failed to resolve output path")
	ErrWriteOutput           = errors.New("failed to write output")

	// Import-related errors.
	ErrBasePath             = errors.New("base path required to process imports")
	ErrTempDir              = errors.New("temporary directory required to process imports")
	ErrResolveLocal         = errors.New("failed to resolve local import path")
	ErrSourceDestination    = errors.New("source and destination cannot be nil")
	ErrImportPathRequired   = errors.New("import path required to process imports")
	ErrNoFileMatchPattern   = errors.New("no files matching patterns found")
	ErrMaxImportDepth       = errors.New("maximum import depth reached")
	ErrNoValidAbsolutePaths = errors.New("no valid absolute paths found")
	ErrDownloadRemoteConfig = errors.New("failed to download remote config")
	ErrMockImportFailure    = errors.New("mock error: simulated import failure")
	ErrProcessNestedImports = errors.New("failed to process nested imports")

	// Profiler-related errors.
	ErrProfilerStart           = errors.New("profiler start failed")
	ErrProfilerUnsupportedType = errors.New("profiler: unsupported profile type")
	ErrProfilerStartCPU        = errors.New("profiler: failed to start CPU profile")
	ErrProfilerStartTrace      = errors.New("profiler: failed to start trace profile")
	ErrProfilerCreateFile      = errors.New("profiler: failed to create profile file")

	// Auth package errors.
	ErrAuthNotConfigured            = errors.New("authentication not configured in atmos.yaml")
	ErrInvalidAuthConfig            = errors.New("invalid auth config")
	ErrInvalidIdentityKind          = errors.New("invalid identity kind")
	ErrInvalidIdentityConfig        = errors.New("invalid identity config")
	ErrInvalidProviderKind          = errors.New("invalid provider kind")
	ErrInvalidProviderConfig        = errors.New("invalid provider config")
	ErrInvalidBrowserExecutable     = errors.New("invalid browser executable")
	ErrAuthenticationFailed         = errors.New("authentication failed")
	ErrPrepareShellEnvironment      = errors.New("failed to prepare authenticated shell environment")
	ErrInvalidADCContent            = errors.New("invalid ADC content")
	ErrWriteADCFile                 = errors.New("failed to write ADC file")
	ErrWritePropertiesFile          = errors.New("failed to write properties file")
	ErrWriteAccessTokenFile         = errors.New("failed to write access token file")
	ErrPostAuthenticationHookFailed = errors.New("post authentication hook failed")
	ErrAuthManager                  = errors.New("auth manager error")
	ErrDefaultIdentity              = errors.New("default identity error")
	ErrAwsAuth                      = errors.New("aws auth error")
	ErrAwsUserNotConfigured         = errors.New("aws user not configured")
	ErrAwsUserKeyringReadFailed     = errors.New("failed to read AWS user credentials from keyring")
	ErrAwsSAMLDecodeFailed          = errors.New("aws saml decode failed")
	ErrPlaywrightDriverSeed         = errors.New("failed to pre-seed the Playwright driver")
	ErrAwsMissingEnvVars            = errors.New("missing required AWS environment variables")
	ErrUnsupportedPlatform          = errors.New("unsupported platform")
	ErrChromeNotFound               = errors.New("chrome/chromium not found for isolated browser sessions")
	ErrSayNotFound                  = errors.New("text-to-speech command not found")
	ErrVoiceListUnsupported         = errors.New("voice enumeration not supported for backend")
	ErrUserAborted                  = errors.New("user aborted")

	// AWS SSO specific errors.
	ErrSSOSessionExpired      = errors.New("aws sso session expired")
	ErrSSODeviceAuthFailed    = errors.New("aws sso device authorization failed")
	ErrSSOTokenCreationFailed = errors.New("aws sso token creation failed")
	ErrSSOAccountListFailed   = errors.New("failed to list aws sso accounts")
	ErrSSORoleListFailed      = errors.New("failed to list aws sso roles")
	ErrSSOProvisioningFailed  = errors.New("aws sso identity provisioning failed")
	ErrSSOInvalidToken        = errors.New("invalid aws sso token")

	// AWS browser webflow errors.
	ErrWebflowAuthFailed     = errors.New("browser authentication failed")
	ErrWebflowDisabled       = errors.New("browser authentication is disabled")
	ErrWebflowTokenExchange  = errors.New("failed to exchange authorization code for credentials")
	ErrWebflowCallbackServer = errors.New("failed to start local callback server")
	ErrWebflowTimeout        = errors.New("browser authentication timed out")
	ErrWebflowRefreshFailed  = errors.New("failed to refresh browser credentials")
	// ErrWebflowRefreshTokenRevoked indicates the refresh token has been definitively
	// rejected by the AWS signin service (e.g. HTTP 400 invalid_grant/invalid_token).
	// This is the only condition under which the cached refresh token should be deleted;
	// transient failures (HTTP 5xx, 429, network errors) must preserve the cache.
	ErrWebflowRefreshTokenRevoked = errors.New("browser refresh token has been revoked")
	ErrWebflowCodeRequired        = errors.New("authorization code is required")
	ErrWebflowReadAuthCodeFailed  = errors.New("failed to read authorization code")
	ErrWebflowAuthorizationError  = errors.New("authorization error")
	ErrWebflowMissingCallbackCode = errors.New("missing authorization code in callback")
	ErrWebflowStateMismatch       = errors.New("state mismatch: possible CSRF attack")
	ErrWebflowEmptyCachedToken    = errors.New("cached refresh token is empty")
	// ErrWebflowDPoP indicates a failure generating or serializing the RFC 9449
	// DPoP proof required on AWS signin token requests (issue #2542).
	ErrWebflowDPoP = errors.New("failed to build DPoP proof")

	// Credential errors.
	ErrCredentialsInvalid = errors.New("credentials are invalid or have been revoked")
	ErrInvalidDuration    = errors.New("invalid duration format")

	// Auth manager and identity/provider resolution errors (centralized sentinels).
	ErrFailedToInitializeAuthManager = errors.New("failed to initialize auth manager")
	ErrNoCredentialsFound            = errors.New("no credentials found for identity")
	ErrExpiredCredentials            = errors.New("credentials for identity are expired or invalid")
	ErrNilParam                      = errors.New("parameter cannot be nil")
	ErrInitializingProviders         = errors.New("failed to initialize providers")
	ErrInitializingIdentities        = errors.New("failed to initialize identities")
	ErrInitializingCredentialStore   = errors.New("failed to initialize credential store")
	ErrCircularDependency            = errors.New("circular dependency detected in identity chain")
	ErrIdentityNotFound              = errors.New("identity not found")
	ErrProviderNotFound              = errors.New("provider not found")
	ErrMutuallyExclusiveFlags        = errors.New("mutually exclusive flags provided")
	ErrNoDefaultIdentity             = errors.New("no default identity configured for authentication")
	ErrMultipleDefaultIdentities     = errors.New("multiple default identities found")
	ErrNoIdentitiesAvailable         = errors.New("no identities available")
	ErrNoProvidersAvailable          = errors.New("no providers available")
	ErrNoIdentitiesMatchTags         = errors.New("no identities match the specified tags")
	ErrNoProvidersMatchTags          = errors.New("no providers match the specified tags")
	ErrNoDefaultProvider             = errors.New("no default provider configured and multiple providers exist")
	ErrIdentitySelectionRequiresTTY  = fmt.Errorf("interactive identity selection: %w", ErrTTYRequired)
	ErrProviderSelectionRequiresTTY  = fmt.Errorf("interactive provider selection: %w", ErrTTYRequired)
	ErrAuthenticationChainNotBuilt   = errors.New("authentication chain not built")
	ErrInvalidStackConfig            = errors.New("invalid stack config")
	ErrNoCommandSpecified            = errors.New("no command specified")
	ErrCommandNotFound               = errors.New("command not found")
	ErrCommandFailed                 = errors.New("command execution failed")

	// Auth validation errors - specific sentinel errors for configuration validation.
	ErrMissingPrincipal     = errors.New("principal is required")
	ErrMissingAssumeRole    = errors.New("assume_role is required in principal")
	ErrMissingPermissionSet = errors.New("permission set name is required in principal")
	ErrMissingAccountSpec   = errors.New("account specification is required in principal")

	ErrInvalidSubcommand = errors.New("invalid subcommand")
	ErrSubcommandFailed  = errors.New("subcommand failed")

	ErrInvalidArgumentError = errors.New("invalid argument error")
	ErrMissingInput         = errors.New("missing input")

	ErrAuthAwsFileManagerFailed = errors.New("failed to create AWS file manager")

	ErrAuthOidcDecodeFailed    = errors.New("failed to decode OIDC token")
	ErrAuthOidcUnmarshalFailed = errors.New("failed to unmarshal oidc claims")

	// Realm errors.
	ErrFailedToComputeRealm = errors.New("failed to compute realm")
	ErrInvalidRealm         = errors.New("invalid realm value")
	ErrEmptyRealm           = errors.New("realm is required for credential isolation but was not set")

	// Logout errors.
	ErrFailedGetConfigDir   = errors.New("failed to get config directory")
	ErrFailedDiscoverRealms = errors.New("failed to discover realms")
	ErrFailedRemoveRealm    = errors.New("failed to remove realm")

	// Store and hook errors.
	ErrNilTerraformOutput = errors.New("terraform output returned nil")
	ErrNilStoreValue      = errors.New("cannot store nil value")

	// Devcontainer errors.
	ErrDevcontainerNotFound      = errors.New("devcontainer not found")
	ErrContainerRuntimeOperation = errors.New("container runtime operation failed")
	ErrContainerNotFound         = errors.New("container not found")
	ErrContainerAlreadyExists    = errors.New("container already exists")
	ErrContainerNotRunning       = errors.New("container is not running")
	ErrContainerRunning          = errors.New("container is running")
	ErrContainerNotHealthy       = errors.New("container did not become healthy")
	ErrInvalidDevcontainerConfig = errors.New("invalid devcontainer configuration")
	ErrRuntimeNotAvailable       = errors.New("container runtime not available")
	ErrDevcontainerNameEmpty     = errors.New("devcontainer name cannot be empty")
	ErrDevcontainerNameInvalid   = errors.New("devcontainer name contains invalid characters")
	ErrDevcontainerNameTooLong   = errors.New("devcontainer name is too long")
	ErrPTYNotSupported           = errors.New("PTY not supported on this platform")

	// Container bulk-operation errors.
	ErrNoContainerComponentSelected = errors.New("no container component selected")
	ErrContainerComponentWithAll    = errors.New("cannot combine a component argument with --all")

	// Container run configuration errors.
	ErrInvalidContainerRestartPolicy = errors.New("invalid container restart policy")
	ErrInvalidContainerHealthCheck   = errors.New("invalid container healthcheck")

	// Logout errors.
	ErrLogoutFailed                         = errors.New("logout failed")
	ErrPartialLogout                        = errors.New("partial logout")
	ErrLogoutNotSupported                   = errors.New("logout not supported for this provider")
	ErrLogoutNotImplemented                 = errors.New("logout not implemented for this provider")
	ErrKeyringDeletion                      = errors.New("keyring deletion failed")
	ErrKeychainDeletionRequiresConfirmation = errors.New("keychain deletion requires interactive confirmation or --force flag")
	ErrProviderLogout                       = errors.New("provider logout failed")
	ErrIdentityLogout                       = errors.New("identity logout failed")
	ErrIdentityNotInConfig                  = errors.New("identity not found in configuration")
	ErrProviderNotInConfig                  = errors.New("provider not found in configuration")
	ErrInvalidLogoutOption                  = errors.New("invalid logout option")

	// Provision target (delivery destination) errors.
	ErrProvisionTargetNotFound    = errors.New("provision target not found")
	ErrProvisionTargetKindUnknown = errors.New("provision target kind is not registered")
	ErrProvisionTargetKindMissing = errors.New("provision target is missing a kind")
	ErrProvisionTargetNoFetch     = errors.New("provision target kind does not support reading current state")
	ErrGitPullRequestNotSupported = errors.New("git pull request publishing is not supported by the cli provider")

	// Backend provisioning errors.
	ErrBucketRequired            = errors.New("backend.bucket is required")
	ErrRegionRequired            = errors.New("backend.region is required")
	ErrBackendNotFound           = errors.New("backend configuration not found")
	ErrProvisioningNotConfigured = errors.New("provisioning not configured")
	ErrCreateNotImplemented      = errors.New("create not implemented for backend type")
	ErrDeleteNotImplemented      = errors.New("delete not implemented for backend type")
	ErrProvisionerFailed         = errors.New("provisioner failed")
	ErrLoadAWSConfig             = errors.New("failed to load AWS config")
	ErrCheckBucketExist          = errors.New("failed to check bucket existence")
	ErrCreateBucket              = errors.New("failed to create bucket")
	ErrApplyBucketDefaults       = errors.New("failed to apply bucket defaults")
	ErrEnableVersioning          = errors.New("failed to enable versioning")
	ErrEnableEncryption          = errors.New("failed to enable encryption")
	ErrBlockPublicAccess         = errors.New("failed to block public access")
	ErrApplyTags                 = errors.New("failed to apply tags")
	ErrForceRequired             = errors.New("--force flag required for backend deletion")
	ErrBucketNotEmpty            = errors.New("bucket contains objects and cannot be deleted")
	ErrStateFilesExist           = errors.New("bucket contains terraform state files")
	ErrDeleteObjects             = errors.New("failed to delete objects from bucket")
	ErrDeleteBucket              = errors.New("failed to delete bucket")
	ErrListObjects               = errors.New("failed to list bucket objects")

	// Component path resolution errors.
	ErrPathNotInComponentDir  = errors.New("path is not within Atmos component directories")
	ErrComponentTypeMismatch  = errors.New("path component type does not match command")
	ErrComponentNotInStack    = errors.New("component not found in stack configuration")
	ErrPathResolutionFailed   = errors.New("failed to resolve component from path")
	ErrPathIsComponentBase    = errors.New("must specify a component directory, not the base directory")
	ErrAmbiguousComponentPath = errors.New("ambiguous component path")
	ErrComponentPathNotFound  = errors.New("component path does not exist")

	// Interactive prompt errors.
	ErrInteractiveModeNotAvailable = errors.New("interactive mode not available")
	ErrNoOptionsAvailable          = errors.New("no options available")

	// Locals-related errors.
	ErrLocalsInvalidType        = errors.New("locals must be a map")
	ErrLocalsCircularDep        = errors.New("circular dependency in locals")
	ErrLocalsDependencyExtract  = errors.New("failed to extract dependencies for local")
	ErrLocalsResolution         = errors.New("failed to resolve local")
	ErrLocalsYamlFunctionFailed = errors.New("failed to process YAML function in local")

	// Init and scaffold errors.
	ErrScaffoldNotFound        = errors.New("scaffold template not found")
	ErrScaffoldValidation      = errors.New("scaffold validation failed")
	ErrScaffoldGeneration      = errors.New("scaffold generation failed")
	ErrInitialization          = errors.New("initialization failed")
	ErrTemplateProcessing      = errors.New("template processing failed")
	ErrInvalidScaffoldConfig   = errors.New("invalid scaffold configuration")
	ErrTargetDirectoryExists   = errors.New("target directory already exists")
	ErrTargetDirectoryNotEmpty = errors.New("target directory is not empty")
	ErrScaffoldParseYAML       = errors.New("failed to parse scaffold YAML")
	ErrPromptFailed            = errors.New("interactive prompt failed")

	// Manifest registry errors (pkg/manifest).
	ErrManifestKindUnknown    = errors.New("unknown manifest kind")
	ErrManifestKindEmpty      = errors.New("manifest kind is empty")
	ErrManifestKindMismatch   = errors.New("manifest kind mismatch")
	ErrManifestAPIVersion     = errors.New("unsupported manifest apiVersion")
	ErrManifestParse          = errors.New("failed to parse manifest")
	ErrManifestPrototypeNil   = errors.New("manifest prototype is nil")
	ErrManifestSchemaGenerate = errors.New("failed to generate manifest JSON schema")
	ErrManifestValidation     = errors.New("manifest validation failed")

	// Generator errors.
	ErrReadTemplatesDirectory        = errors.New("failed to read templates directory")
	ErrReadTemplateFiles             = errors.New("failed to read template files")
	ErrReadTargetDirectory           = errors.New("failed to read target directory")
	ErrInvalidBaseRef                = errors.New("invalid base reference")
	ErrTemplateExecution             = errors.New("template execution failed")
	ErrDirectoryCreation             = errors.New("directory creation failed")
	ErrFileExists                    = errors.New("file already exists")
	ErrFileWrite                     = errors.New("file write failed")
	ErrUnprocessedTemplate           = errors.New("unprocessed template variable found")
	ErrThreeWayMerge                 = errors.New("three-way merge failed")
	ErrMergeConflict                 = errors.New("merge conflict detected")
	ErrCreateIOContext               = errors.New("failed to create IO context")
	ErrLoadScaffoldTemplates         = errors.New("failed to load scaffold templates")
	ErrResolveTargetDirectory        = errors.New("failed to resolve target directory")
	ErrScaffoldInvalidPrompt         = errors.New("invalid scaffold prompt configuration")
	ErrCreateGeneratorContext        = errors.New("failed to create generator context")
	ErrReadScaffoldConfig            = errors.New("failed to read scaffold configuration")
	ErrTargetDirRequired             = errors.New("target directory is required")
	ErrTemplateNameRequired          = errors.New("template name is required")
	ErrScaffoldFileNotFound          = errors.New("scaffold file not found")
	ErrInvalidScaffoldFile           = errors.New("invalid scaffold file")
	ErrScaffoldDirectoryRead         = errors.New("failed to read scaffold directory")
	ErrScaffoldReadFile              = errors.New("failed to read scaffold file")
	ErrScaffoldMissingName           = errors.New("scaffold is missing required name field")
	ErrScaffoldMergeTemplates        = errors.New("failed to merge scaffold templates")
	ErrScaffoldLoadFromFS            = errors.New("failed to load scaffold from filesystem")
	ErrScaffoldCreateFromPath        = errors.New("failed to create scaffold from path")
	ErrScaffoldSelectTemplate        = errors.New("failed to select scaffold template")
	ErrScaffoldDryRunValues          = errors.New("failed to load dry run values")
	ErrScaffoldRenderFilePath        = errors.New("failed to render file path")
	ErrScaffoldValidateSingleFile    = errors.New("scaffold file validation failed")
	ErrScaffoldFilesNotUnique        = errors.New("scaffold files must be unique")
	ErrScaffoldTemplatesNotAvailable = errors.New("scaffold templates not available")
	ErrScaffoldLoadConfig            = errors.New("failed to load scaffold configuration")
	ErrInvalidTemplateData           = errors.New("invalid template data")
	ErrMergeThresholdExceeded        = errors.New("merge threshold exceeded")
	ErrNoCommonAncestor              = errors.New("no common ancestor found")
	ErrUnknownMergeStrategy          = errors.New("unknown merge strategy")
	ErrGeneratorFieldRequired        = errors.New("field is required")
	ErrDuplicateScaffoldFieldName    = errors.New("duplicate scaffold field name")
	ErrScaffoldConfigMissing         = errors.New("scaffold configuration not found")
	ErrInitializationPartialFailure  = errors.New("initialization partially failed")
	ErrInitTemplateNotFound          = errors.New("init template not found")
	ErrInvalidScaffoldSection        = errors.New("invalid scaffold section")
	ErrScaffoldSourceUnsupported     = errors.New("scaffold source scheme not supported")
	ErrScaffoldFetchSource           = errors.New("failed to fetch scaffold source")
	ErrScaffoldCatalogLoad           = errors.New("failed to load scaffold catalog")
	ErrTemplateConfigNameRequired    = errors.New("template config with metadata.name is required to write a project record")
	ErrPathTraversal                 = errors.New("path traversal not allowed")
	ErrSymlinkWrite                  = errors.New("refusing to write through a symlink")
	ErrMetadataLoad                  = errors.New("failed to load init metadata")
	ErrMetadataSave                  = errors.New("failed to save init metadata")
	ErrScaffoldHookKindUnsupported   = errors.New("scaffold hook kind not supported")

	// Source provisioner errors.
	ErrSourceProvision       = errors.New("source provisioning failed")
	ErrSourceNotFound        = errors.New("source not found")
	ErrSourceAccessDenied    = errors.New("source access denied")
	ErrSourceInvalidSpec     = errors.New("invalid source specification")
	ErrSourceAlreadyVendored = errors.New("source already vendored")
	ErrSourceCacheOperation  = errors.New("source cache operation failed")
	ErrSourceCopyFailed      = errors.New("failed to copy source files")
	ErrSourceMissing         = errors.New("source not configured for component")

	// Workdir provisioner errors.
	ErrSourceDownload   = errors.New("failed to download component source")
	ErrSourceCacheRead  = errors.New("failed to read source cache")
	ErrSourceCacheWrite = errors.New("failed to write source cache")
	ErrInvalidSource    = errors.New("invalid source configuration")
	ErrWorkdirCreation  = errors.New("failed to create working directory")
	ErrWorkdirSync      = errors.New("failed to sync files to working directory")
	ErrWorkdirMetadata  = errors.New("failed to read/write workdir metadata")
	ErrWorkdirProvision = errors.New("workdir provisioning failed")
	ErrWorkdirClean     = errors.New("failed to clean working directory")

	// Integration errors.
	ErrIntegrationNotFound    = errors.New("integration not found")
	ErrUnknownIntegrationKind = errors.New("unknown integration kind")
	ErrIntegrationFailed      = errors.New("integration execution failed")
	ErrNoLinkedIntegrations   = errors.New("identity has no linked integrations")

	// ECR authentication errors.
	ErrECRAuthFailed       = errors.New("ECR authentication failed")
	ErrECRTokenExpired     = errors.New("ECR authorization token expired")
	ErrECRRegistryNotFound = errors.New("ECR registry not found")
	ErrECRInvalidRegistry  = errors.New("invalid ECR registry URL")
	ErrECRLoginNoArgs      = errors.New("specify an server name, --identity, or --registry")
	ErrECRLoginFailed      = errors.New("ECR login failed")
	ErrDockerConfigWrite   = errors.New("failed to write Docker config")
	ErrDockerConfigRead    = errors.New("failed to read Docker config")

	// ECR Public authentication errors.
	ErrECRPublicAuthFailed    = errors.New("ECR Public authentication failed")
	ErrECRPublicInvalidRegion = errors.New("invalid ECR Public region: only us-east-1 and us-west-2 are supported")

	// EKS server errors.
	ErrEKSDescribeCluster   = errors.New("failed to describe EKS cluster")
	ErrEKSClusterNotFound   = errors.New("EKS cluster not found")
	ErrEKSIntegrationFailed = errors.New("EKS integration failed")
	ErrEKSTokenGeneration   = errors.New("failed to generate EKS token")
	ErrKubeconfigPath       = errors.New("failed to determine kubeconfig path")
	ErrKubeconfigWrite      = errors.New("failed to write kubeconfig")
	ErrKubeconfigMerge      = errors.New("failed to merge kubeconfig")

	// Atmos Pro authentication (atmos/pro provider) errors.
	ErrProAuthFailed         = errors.New("authentication to Atmos Pro failed")
	ErrProWorkspaceIDMissing = errors.New("workspace ID for Atmos Pro is required (set via auth provider spec.workspace_id, settings.pro.workspace_id, or ATMOS_PRO_WORKSPACE_ID)")
	ErrProCredentialsType    = errors.New("expected Atmos Pro credentials")

	// GitHub STS integration (github/sts) errors.
	ErrSTSMintFailed           = errors.New("failed to mint GitHub STS tokens")
	ErrSTSNoEntitlement        = errors.New("workspace is not entitled to GitHub STS or the feature is disabled")
	ErrNotGitHubActionsSession = errors.New("GitHub STS requires a GitHub Actions session")
	ErrGitHubTokenRevokeFailed = errors.New("failed to revoke GitHub installation token")
	ErrGitSTSStateWrite        = errors.New("failed to write GitHub STS state")
	ErrGitSTSStateRead         = errors.New("failed to read GitHub STS state")

	// Integration via configuration errors.
	ErrIntegrationViaMissing   = errors.New("integration must define via.identity or via.provider")
	ErrIntegrationViaAmbiguous = errors.New("integration must define exactly one of via.identity or via.provider")

	// Identity authentication errors.
	ErrIdentityAuthFailed      = errors.New("failed to authenticate identity")
	ErrIdentityCredentialsNone = errors.New("credentials not available for identity")

	// CI-related errors.
	ErrCIDisabled              = errors.New("CI server is disabled")
	ErrCIProviderNotDetected   = errors.New("CI provider not detected")
	ErrCIProviderNotFound      = errors.New("CI provider not found")
	ErrCIOperationNotSupported = errors.New("operation not supported by CI provider")
	ErrCICheckRunCreateFailed  = errors.New("failed to create check run")
	ErrCICheckRunUpdateFailed  = errors.New("failed to update check run")
	ErrCIStatusFetchFailed     = errors.New("failed to fetch CI status")
	ErrCIOutputWriteFailed     = errors.New("failed to write CI output")
	ErrCISummaryWriteFailed    = errors.New("failed to write CI summary")
	ErrCIAnnotationFailed      = errors.New("failed to emit CI annotations")
	ErrCISARIFUploadFailed     = errors.New("failed to upload SARIF to CI provider")
	ErrCICommentPostFailed     = errors.New("failed to post PR comment")
	ErrCICommentListFailed     = errors.New("failed to list PR comments")
	ErrCICommentUpdateFailed   = errors.New("failed to update PR comment")
	ErrCICommentNotFound       = errors.New("PR comment not found")
	ErrGitHubTokenNotFound     = errors.New("GitHub token not found")

	// Planfile storage errors.
	ErrPlanfileNotFound           = errors.New("planfile not found")
	ErrPlanfileUploadFailed       = errors.New("failed to upload planfile")
	ErrPlanfileDownloadFailed     = errors.New("failed to download planfile")
	ErrPlanfileDeleteFailed       = errors.New("failed to delete planfile")
	ErrPlanfileListFailed         = errors.New("failed to list planfiles")
	ErrPlanfileStoreNotFound      = errors.New("planfile store not found")
	ErrPlanfileKeyInvalid         = errors.New("planfile key generation failed: stack, component, and SHA are required")
	ErrPlanfileStatFailed         = errors.New("failed to check planfile status")
	ErrPlanfileMetadataFailed     = errors.New("failed to load planfile metadata")
	ErrPlanfileMetadataInvalid    = errors.New("planfile metadata validation failed: stack, component, and SHA are required")
	ErrArtifactMetadataInvalid    = errors.New("artifact metadata validation failed: stack, component, and SHA are required")
	ErrPlanfileStoreInvalidArgs   = errors.New("invalid planfile store arguments")
	ErrPlanfileDeleteRequireForce = errors.New("deletion requires --force flag")
	ErrAWSConfigLoadFailed        = errors.New("failed to load AWS configuration")

	// Artifact storage errors.
	ErrArtifactNotFound         = errors.New("artifact not found")
	ErrArtifactUploadFailed     = errors.New("failed to upload artifact")
	ErrArtifactDownloadFailed   = errors.New("failed to download artifact")
	ErrArtifactDeleteFailed     = errors.New("failed to delete artifact")
	ErrArtifactListFailed       = errors.New("failed to list artifacts")
	ErrArtifactStoreNotFound    = errors.New("artifact store not found")
	ErrArtifactStoreInvalidArgs = errors.New("invalid artifact store arguments")
	ErrArtifactMetadataFailed   = errors.New("failed to load artifact metadata")
	ErrArtifactIntegrityFailed  = errors.New("artifact integrity check failed")

	// CI cache errors.
	ErrCacheUnavailable     = errors.New("CI cache is not available in this environment")
	ErrCacheNotFound        = errors.New("cache entry not found")
	ErrCacheAlreadyExists   = errors.New("cache entry already exists")
	ErrCacheSaveFailed      = errors.New("failed to save cache entry")
	ErrCacheRestoreFailed   = errors.New("failed to restore cache entry")
	ErrCacheDeleteFailed    = errors.New("failed to delete cache entry")
	ErrCacheListFailed      = errors.New("failed to list cache entries")
	ErrCacheBackendNotFound = errors.New("cache backend not found")
	ErrCacheInvalidArgs     = errors.New("invalid cache arguments")
	ErrCacheKeyRequired     = errors.New("cache key is required")
	ErrCacheArchiveFailed   = errors.New("failed to build cache archive")
	ErrCacheExtractFailed   = errors.New("failed to extract cache archive")
	ErrCacheBackendRequest  = errors.New("cache backend request failed")

	// AI-related errors.
	ErrAINotEnabled                 = errors.New("AI features are not enabled")
	ErrAIDisabledInConfiguration    = errors.New("AI features are disabled in configuration")
	ErrAIAPIKeyNotFound             = errors.New("API key not found in environment variable")
	ErrAINoStackFilesFound          = errors.New("no stack files found")
	ErrAIUnsupportedProvider        = errors.New("unsupported AI provider")
	ErrAIClientNil                  = errors.New("AI client cannot be nil")
	ErrAINoResponseCandidates       = errors.New("no response candidates returned")
	ErrAINoResponseContent          = errors.New("no content in response")
	ErrAIResponseNotText            = errors.New("response part does not contain text")
	ErrAINoResponseChoices          = errors.New("no response choices returned")
	ErrAISessionNotFound            = errors.New("AI session not found")
	ErrAISessionAlreadyExists       = errors.New("AI session already exists")
	ErrAIToolNotFound               = errors.New("AI tool not found")
	ErrAIToolExecutionDenied        = errors.New("AI tool execution denied by user")
	ErrAIToolExecutionFailed        = errors.New("AI tool execution failed")
	ErrAIToolParameterRequired      = errors.New("tool parameter is required")
	ErrAIToolNameEmpty              = errors.New("tool name cannot be empty")
	ErrAIToolAlreadyRegistered      = errors.New("tool already registered")
	ErrAIToolBlocked                = errors.New("tool is blocked")
	ErrAIToolsDisabled              = errors.New("tools are disabled")
	ErrAINoPrompter                 = errors.New("no prompter available")
	ErrAIPermissionPromptFailed     = errors.New("permission prompt failed")
	ErrAISessionsNotEnabled         = errors.New("sessions are not enabled in configuration")
	ErrAIInvalidDurationFormat      = errors.New("invalid duration format")
	ErrAIUnsupportedDurationUnit    = errors.New("unsupported duration unit")
	ErrAIUnsupportedComponentType   = errors.New("unsupported component type")
	ErrAIFileAccessDeniedComponents = errors.New("access denied: file path must be within components directory")
	ErrAIFileAccessDeniedStacks     = errors.New("access denied: file path must be within stacks directory")
	ErrAIInvalidConfiguration       = errors.New("invalid AI configuration")
	ErrAINotInitialized             = errors.New("AI client not initialized")
	ErrAIFileNotFound               = errors.New("file not found")
	ErrAIPathIsDirectory            = errors.New("path is a directory, not a file")
	ErrAISessionManagerNotAvailable = errors.New("session manager not available")
	ErrAISessionNameEmpty           = errors.New("session name cannot be empty")
	ErrAISQLitePragmaFailed         = errors.New("failed to set SQLite pragma")
	ErrAIAgentNil                   = errors.New("AI agent cannot be nil")
	ErrAIAgentNameEmpty             = errors.New("AI agent name cannot be empty")
	ErrAIAgentNotFound              = errors.New("AI agent not found")
	ErrAIAgentAlreadyRegistered     = errors.New("AI agent already registered")
	ErrAISkillNil                   = errors.New("AI skill cannot be nil")
	ErrAISkillNameEmpty             = errors.New("AI skill name cannot be empty")
	ErrAISkillNotFound              = errors.New("AI skill not found")
	ErrAISkillAlreadyRegistered     = errors.New("AI skill already registered")
	ErrAISkillRequiresAIFlag        = errors.New("--skill flag requires --ai")
	ErrAISkillLoadFailed            = errors.New("failed to load AI skills")
	ErrAIPromptRequired             = errors.New("prompt is required")
	ErrAIExecutionFailed            = errors.New("AI execution failed")
	ErrAISendMessage                = errors.New("failed to send message to AI provider")
	ErrAIClientCreation             = errors.New("failed to create AI client")
	ErrAIMarshalRequest             = errors.New("failed to marshal AI request")
	ErrAIUnmarshalResponse          = errors.New("failed to unmarshal AI response")
	ErrAIParseToolInput             = errors.New("failed to parse tool input")
	ErrAILoadAWSConfig              = errors.New("failed to load AWS configuration for AI")
	ErrAIBaseURLRequired            = errors.New("base URL is required for AI provider")
	ErrAIAccessDeniedBasePath       = errors.New("access denied: file must be within Atmos base path")
	ErrAIAccessDeniedSearchPath     = errors.New("access denied: search path must be within Atmos base path")
	ErrAIUnknownOperation           = errors.New("unknown operation")
	ErrAISearchTextNotFound         = errors.New("search text not found in file")
	ErrAILineNumberOutOfRange       = errors.New("line number out of range")
	ErrAIInvalidLineRange           = errors.New("invalid line range")
	ErrAICommandEmpty               = errors.New("command cannot be empty")
	ErrAICommandBlacklisted         = errors.New("command is blacklisted for security reasons")
	ErrAICommandRmNotAllowed        = errors.New("rm with recursive or force flags is not allowed")
	ErrAILSPNotEnabled              = errors.New("LSP is not enabled")
	ErrAIFileDoesNotExist           = errors.New("file does not exist")
	ErrAIConfigNil                  = errors.New("cannot switch provider: atmosConfig is nil")
	ErrAIInvalidProviderSelection   = errors.New("invalid provider selection")

	// AI session checkpoint/compaction errors.
	ErrAICompactPlanNil               = errors.New("compact plan is nil")
	ErrAIUnsupportedExportFormat      = errors.New("unsupported export format")
	ErrAICheckpointNil                = errors.New("checkpoint is nil")
	ErrAICheckpointVersionMissing     = errors.New("checkpoint version is missing")
	ErrAIUnsupportedCheckpointVersion = errors.New("unsupported checkpoint version")
	ErrAISessionNameRequired          = errors.New("session name is required")
	ErrAISessionProviderRequired      = errors.New("session provider is required")
	ErrAISessionModelRequired         = errors.New("session model is required")
	ErrAICheckpointNoMessages         = errors.New("checkpoint must contain at least one message")
	ErrAIMessageRoleRequired          = errors.New("message role is required")
	ErrAIMessageInvalidRole           = errors.New("invalid message role")
	ErrAIStatisticsMismatch           = errors.New("statistics message count does not match actual messages")
	ErrAIUnsupportedCheckpointFormat  = errors.New("unsupported checkpoint format")
	ErrAIComponentPathNotFound        = errors.New("component path not found")
	ErrAIComponentPathNotDirectory    = errors.New("component path is not a directory")

	// AI MCP config/stack/vendor get-set-delete-format-list tool errors.
	ErrAIConfigFileNotFound         = errors.New("atmos config file not found")
	ErrAIStackConfigPathNotEditable = errors.New("stack config path is not editable without an explicit file")
	ErrAIVendorFileNotFound         = errors.New("no vendor manifest found")
	ErrAICommandNotFound            = errors.New("command not found")
	ErrAICommandTreeNotConfigured   = errors.New("command tree provider is not configured")
	ErrAIToolInvalidOutputType      = errors.New("invalid output_type: must be one of 'list', 'map', or 'all'")
	ErrAINoSchemaForFile            = errors.New("no schema registered for this file; pass schema_path explicitly")

	// AWS security and compliance errors.
	ErrAWSSecurityNotEnabled       = errors.New("security features are not enabled: add 'aws.security.enabled: true' to atmos.yaml")
	ErrAWSSecurityNoFindings       = errors.New("no security findings found matching the specified filters")
	ErrAWSSecurityFetchFailed      = errors.New("failed to fetch security findings from AWS")
	ErrAWSSecurityMappingFailed    = errors.New("failed to map security finding to Atmos component")
	ErrAWSSecurityInvalidSeverity  = errors.New("invalid severity filter: valid values are CRITICAL, HIGH, MEDIUM, LOW, INFORMATIONAL")
	ErrAWSSecurityInvalidSource    = errors.New("invalid finding source: valid values are security-hub, config, inspector, guardduty, macie, access-analyzer, all")
	ErrAWSSecurityInvalidFramework = errors.New("invalid compliance framework: valid values are cis-aws, pci-dss, soc2, hipaa, nist")
	ErrAWSSecurityInvalidFormat    = errors.New("invalid output format: valid values are markdown, json, yaml, csv, sarif")
	ErrAWSSecurityAnalysisFailed   = errors.New("AI analysis of security findings failed")
	ErrAWSCredentialsNotValid      = errors.New("AWS credentials are not configured or have expired")

	// CLI provider errors.
	ErrCLIProviderBinaryNotFound    = errors.New("CLI provider binary not found on PATH")
	ErrCLIProviderExecFailed        = errors.New("CLI provider execution failed")
	ErrCLIProviderParseResponse     = errors.New("failed to parse CLI provider response")
	ErrCLIProviderToolsNotSupported = errors.New("tool execution not supported for CLI providers; use MCP pass-through instead")

	// Web search errors.
	ErrWebSearchFailed      = errors.New("web search request failed")
	ErrWebSearchParseFailed = errors.New("failed to parse web search results")
	ErrWebSearchNotEnabled  = errors.New("web search is not enabled in configuration")

	// MCP errors.
	ErrMCPNotEnabled            = errors.New("MCP server is not enabled")
	ErrMCPToolNotFound          = errors.New("MCP tool not found")
	ErrMCPInvalidJSONRPCVersion = errors.New("invalid JSON-RPC version")
	ErrMCPInvalidTransport      = errors.New("invalid transport type")
	ErrMCPUnsupportedTransport  = errors.New("unsupported transport")
	ErrMCPServerNotFound        = errors.New("MCP server not found in configuration")
	ErrMCPServerNotRunning      = errors.New("MCP server is not running")
	ErrMCPServerStartFailed     = errors.New("MCP server failed to start")
	ErrMCPServerCommandEmpty    = errors.New("MCP server command must not be empty")
	ErrMCPServerInvalidTimeout  = errors.New("MCP server timeout is invalid")
	ErrMCPServerToolListFailed  = errors.New("failed to list tools from MCP server")
	ErrMCPServerToolError       = errors.New("MCP server returned error for tool")
	ErrMCPConfigWriteFailed     = errors.New("failed to write MCP config file")
	ErrMCPConfigPermsFailed     = errors.New("failed to set MCP config file permissions")
	ErrMCPConfigMarshalFailed   = errors.New("failed to marshal MCP config")
	ErrMCPServerAuthUnavailable = errors.New("MCP server requires identity but auth manager is not available")
	ErrLSPInvalidTransport      = errors.New("invalid LSP transport type")
	ErrLSPConfigNil             = errors.New("LSP config is nil")
	ErrLSPNoServerForFile       = errors.New("no LSP server found for file")
	ErrLSPRPCError              = errors.New("RPC error")
	ErrLSPNoContentLengthHeader = errors.New("no Content-Length header found")

	// Kubernetes-native component errors.
	ErrKubernetesFlagsMutuallyExclusive     = errors.New("--all and --affected are mutually exclusive")
	ErrKubernetesComponentArgWithSelection  = errors.New("component argument cannot be used with --all, --affected, --tags, or --labels")
	ErrKubernetesOutputSingleComponentOnly  = errors.New("--output and --output-dir are only supported when rendering one component")
	ErrKubernetesComponentArgRequired       = errors.New("requires exactly one component argument unless --all or --affected is set")
	ErrKubernetesUnsupportedOperation       = errors.New("unsupported kubernetes operation")
	ErrKubernetesUnsupportedSubcommand      = errors.New("unsupported kubernetes subcommand")
	ErrKubernetesMissingMetadataName        = errors.New("object is missing metadata.name")
	ErrKubernetesMissingGVK                 = errors.New("object is missing group/version/kind")
	ErrManifestEntryInvalidType             = errors.New("manifest entries must be YAML strings or maps")
	ErrManifestMissingAPIVersionKind        = errors.New("manifest is missing apiVersion or kind")
	ErrManifestListItemNotObject            = errors.New("list item is not an unstructured object")
	ErrKubernetesOutputDirMutuallyExclusive = errors.New("--output and --output-dir are mutually exclusive")
	ErrKubernetesSplitRequiresOutputDir     = errors.New("--split requires --output-dir and cannot be used with --output")
	ErrKubernetesSplitNeedsOutputDir        = errors.New("--split requires --output-dir")
	ErrKubernetesClientInit                 = errors.New("failed to initialize kubernetes client")
	ErrKubernetesApply                      = errors.New("failed to apply kubernetes object")
	ErrKubernetesDelete                     = errors.New("failed to delete kubernetes object")
	ErrKubernetesDiff                       = errors.New("failed to diff kubernetes object")
	ErrKubernetesMarshal                    = errors.New("failed to marshal kubernetes object")
	ErrKubernetesResolveResource            = errors.New("failed to resolve kubernetes resource")
	ErrKubernetesComponentDir               = errors.New("failed to create kubernetes component directory")
	ErrKubernetesRenderOutput               = errors.New("failed to write rendered kubernetes manifests")
	ErrKubernetesRender                     = errors.New("failed to render kubernetes object")
	ErrKubernetesProviderType               = errors.New("provider must be a string")
	ErrManifestPathTraversal                = errors.New("manifest path escapes the component directory")
	ErrKubernetesValidationFailed           = errors.New("kubernetes manifest validation failed")
	ErrKubernetesManifestInvalidName        = errors.New("object metadata.name is not a valid DNS-1123 subdomain")
	ErrKubernetesValidate                   = errors.New("failed to validate kubernetes object")

	// Helm-native component errors.
	ErrHelmFlagsMutuallyExclusive    = errors.New("--all and --affected are mutually exclusive")
	ErrHelmComponentArgWithSelection = errors.New("component argument cannot be used with --all, --affected, --tags, or --labels")
	ErrHelmOutputSingleComponentOnly = errors.New("--output and --output-dir are only supported when rendering one component")
	ErrHelmComponentArgRequired      = errors.New("requires exactly one component argument unless --all or --affected is set")
	ErrHelmUnsupportedOperation      = errors.New("unsupported helm operation")
	ErrHelmUnsupportedSubcommand     = errors.New("unsupported helm subcommand")
	ErrHelmChartNotConfigured        = errors.New("helm component is missing a 'chart' reference")
	ErrHelmRenderFailed              = errors.New("failed to render helm chart")
	ErrHelmReleaseNameRequired       = errors.New("helm component is missing a release name")
	ErrHelmDiffFailed                = errors.New("failed to compute helm diff")
	ErrHelmBaselineRead              = errors.New("failed to read helm diff baseline")
	ErrHelmLifecycleDecode           = errors.New("failed to decode helm release lifecycle")
	ErrHelmFailureActionInvalid      = errors.New("invalid helm on_failure action")
	ErrHelmWaitStrategyInvalid       = errors.New("invalid helm wait strategy")
	ErrHelmTimeoutInvalid            = errors.New("invalid helm release timeout")
	ErrHelmMaxHistoryInvalid         = errors.New("invalid helm release history limit")
	ErrHelmWaitForJobsRequiresWait   = errors.New("helm wait_for_jobs requires watcher or legacy wait strategy")
	ErrHelmLifecycleFlagInapplicable = errors.New("helm release lifecycle flag does not apply to selected operation")
	ErrHelmLifecycleExternalTarget   = errors.New("helm release lifecycle flags require a Kubernetes target")
	ErrHelmReleaseHistory            = errors.New("failed to inspect helm release history")
	ErrHelmReleaseUpgrade            = errors.New("failed to upgrade helm release")
	ErrHelmReleaseUninstall          = errors.New("failed to uninstall helm release")
	ErrHelmReleaseOperation          = errors.New("helm release operation failed")
)

// Stack dependency (`depends_on`) resolution errors.
var (
	// ErrInvalidDependsOn indicates a legacy `settings.spacelift.depends_on` value
	// does not resolve to a known stack or to a component in the current stack.
	ErrInvalidDependsOn = errors.New("invalid 'depends_on' dependency")
	// ErrInvalidSettingsDependsOn indicates a `settings.depends_on` value does not
	// resolve to a known component in a known stack.
	ErrInvalidSettingsDependsOn = errors.New("invalid 'settings.depends_on' dependency")
)

// Vendor update/diff errors.
var (
	// ErrComponentUpdaterConfig indicates invalid component updater configuration.
	ErrComponentUpdaterConfig = errors.New("invalid component updater configuration")
	// ErrComponentUpdaterDirtyWorktree indicates a publisher's Git worktree has uncommitted changes.
	ErrComponentUpdaterDirtyWorktree = errors.New("component updater requires a clean Git worktree")
	// ErrPullRequestPublisherUnavailable indicates the selected forge integration is not registered.
	ErrPullRequestPublisherUnavailable = errors.New("pull request publisher is unavailable")
	// ErrGitHubAuthorization indicates an authentication or permission failure from the GitHub API.
	ErrGitHubAuthorization = errors.New("GitHub authorization failed")
	// ErrPullRequestReconciliation indicates Atmos could not reconcile an existing or new PR.
	ErrPullRequestReconciliation = errors.New("pull request reconciliation failed")
	// ErrGitFetchFailed indicates `git fetch` of a base or feature branch failed.
	ErrGitFetchFailed = errors.New("git fetch failed")
	// ErrGitCheckoutFailed indicates `git checkout` of a feature branch failed.
	ErrGitCheckoutFailed = errors.New("git checkout failed")
	// ErrGitLocalBranchDiverged indicates a local feature branch has commits absent from both
	// the remote feature branch and the base branch.
	ErrGitLocalBranchDiverged = errors.New("local branch has unpushed commits")
	// ErrGitDefaultBranchResolution indicates the remote's default branch could not be resolved.
	ErrGitDefaultBranchResolution = errors.New("remote default branch resolution failed")

	// ErrGitLsRemoteFailed indicates listing refs from a remote Git repository failed.
	ErrGitLsRemoteFailed = errors.New("failed to list refs from remote Git repository")
	// ErrNoVersionsAvailable indicates no versions were found for a source.
	ErrNoVersionsAvailable = errors.New("no versions available")
	// ErrNoVersionsMatchConstraints indicates no available version satisfies the configured constraints.
	ErrNoVersionsMatchConstraints = errors.New("no versions match the configured constraints")
	// ErrInvalidSemverConstraint indicates a constraints.version value is not a valid semver constraint.
	ErrInvalidSemverConstraint = errors.New("invalid semver constraint")
	// ErrVersionRangeConflictsWithConstraints indicates a source declared both a semver-range
	// version: and a constraints.version ceiling. These are mutually exclusive. constraints.version's
	// entire purpose is to bound what `atmos vendor update` can bump an *exact* pin to; that purpose
	// no longer applies once version: is itself already a range.
	ErrVersionRangeConflictsWithConstraints = errors.New("version: is a semver range; constraints.version is also set. These are mutually exclusive; remove one")
	// ErrVendorSourceNotFound indicates a requested component/source was not found in the vendor manifest.
	ErrVendorSourceNotFound = errors.New("vendor source not found")
	// ErrVendorSourceNotGit indicates a vendor source is not a Git repository (unsupported for update/diff).
	ErrVendorSourceNotGit = errors.New("vendor source is not a Git repository")
	// ErrVendorDiffFailed indicates the vendor diff operation failed.
	ErrVendorDiffFailed = errors.New("failed to produce vendor diff")
	// ErrVendorUpdateFailed indicates the vendor update operation failed.
	ErrVendorUpdateFailed = errors.New("failed to update vendor manifest")
	// ErrReadVendorFile indicates a vendor manifest file could not be read.
	ErrReadVendorFile = errors.New("failed to read vendor manifest")
	// ErrParseVendorFile indicates a vendor manifest file could not be parsed.
	ErrParseVendorFile = errors.New("failed to parse vendor manifest")
	// ErrInvalidGitRef indicates a Git ref (tag, branch, or commit) could not be resolved.
	ErrInvalidGitRef = errors.New("invalid Git ref")
	// ErrComponentManifestNotFound indicates no component.yaml/component.yml exists in a component's directory.
	ErrComponentManifestNotFound = errors.New("component vendoring manifest not found")
	// ErrInvalidComponentManifestKind indicates a component.yaml's "kind" is not "ComponentVendorConfig".
	ErrInvalidComponentManifestKind = errors.New("invalid kind in component vendoring manifest; expected ComponentVendorConfig")
	// ErrComponentDirNotFound indicates a component's resolved base directory does not exist.
	ErrComponentDirNotFound = errors.New("component directory does not exist")
)

// ExitCodeError is a typed error that preserves subcommand exit codes.
// This allows the root command to exit with the same code as the subcommand.
// When Code is 0, it indicates successful completion that should exit cleanly without printing errors.
// This avoids deep exits (os.Exit) which are untestable.
type ExitCodeError struct {
	Code int
	// Silent suppresses themed error rendering: the process exits with Code
	// without printing an error box. Used for terminal-handoff steps (tty,
	// interactive, exec) where, like a shell, a non-zero exit from the child
	// program should propagate the code without Atmos rendering its own error
	// (which would query the terminal and can hang when stdin is contended).
	Silent bool
}

func (e ExitCodeError) Error() string {
	return fmt.Sprintf("subcommand exited with code %d", e.Code)
}