config

type APIConfig struct {
	REST    bool `yaml:"rest,omitempty"`
	OpenAPI bool `yaml:"openapi,omitempty"`
}

type APIKeyConfig struct {
	Header string `yaml:"header,omitempty"` // default: "X-API-Key"
}

type AuthConfig struct {
	Provider    string             `yaml:"provider"` // "jwt", "api_key", "both", "none"
	JWT         JWTConfig          `yaml:"jwt,omitempty"`
	APIKey      APIKeyConfig       `yaml:"api_key,omitempty"`
	MultiTenant *MultiTenantConfig `yaml:"multi_tenant,omitempty"`
}

type CIConfig struct {
	Provider    string       `yaml:"provider"`             // "github" (default)
	GoVersion   string       `yaml:"go_version,omitempty"` // e.g. "1.26"
	Lint        CILintConfig `yaml:"lint,omitempty"`
	Test        CITestConfig `yaml:"test,omitempty"`
	VulnScan    CIVulnConfig `yaml:"vuln_scan,omitempty"`
	E2E         CIE2EConfig  `yaml:"e2e,omitempty"`
	Permissions CIPermConfig `yaml:"permissions,omitempty"`
	ExtraJobs   []CIExtraJob `yaml:"extra_jobs,omitempty"` // user extension point
}

type CIE2EConfig struct {
	Enabled bool   `yaml:"enabled"`           // default false
	Runtime string `yaml:"runtime,omitempty"` // "docker-compose" or "k3d"
}

type CIExtraJob struct {
	Name   string           `yaml:"name"`
	RunsOn string           `yaml:"runs_on,omitempty"` // default "ubuntu-latest"
	Steps  []CIExtraJobStep `yaml:"steps"`
}

type CIExtraJobStep struct {
	Name string            `yaml:"name,omitempty"`
	Uses string            `yaml:"uses,omitempty"`
	Run  string            `yaml:"run,omitempty"`
	With map[string]string `yaml:"with,omitempty"`
}

type CILintConfig struct {
	Golangci        bool `yaml:"golangci"`         // default true
	Buf             bool `yaml:"buf"`              // default true
	BufBreaking     bool `yaml:"buf_breaking"`     // default true
	Frontend        bool `yaml:"frontend"`         // default true
	MigrationSafety bool `yaml:"migration_safety"` // default true
}

type CIPermConfig struct {
	Contents string `yaml:"contents,omitempty"` // default "read"
}

type CITestConfig struct {
	Race     bool `yaml:"race"`     // default true
	Coverage bool `yaml:"coverage"` // default false
}

type CIVulnConfig struct {
	Go     bool `yaml:"go"`     // govulncheck, default true
	Docker bool `yaml:"docker"` // trivy, default true
	NPM    bool `yaml:"npm"`    // npm audit, default true
}

type CRDConfig struct {
	// Name is the PascalCase CRD type name. e.g. "Workspace".
	Name string `yaml:"name"`
	// Group is the API group, defaulting to the parent operator's
	// Group. Stored explicitly so a single operator can manage CRDs
	// from multiple groups.
	Group string `yaml:"group,omitempty"`
	// Version is the API version. Defaults to the parent operator's
	// Version.
	Version string `yaml:"version,omitempty"`
	// Shape is the reconciler scaffold style. One of
	// "state-machine" (phase-driven), "config" (declarative-only,
	// no state), "composite" (manages sub-resources). Drives which
	// template is rendered for the controller shim.
	Shape string `yaml:"shape,omitempty"`
}

type ComponentConfig struct {
	Name string `yaml:"name"`
	// Kind is THE discriminator: server|worker|cron|operator|binary.
	// See the ComponentKind* constants.
	Kind string `yaml:"kind"`
	Path string `yaml:"path"`
	// Ports is a named port map (http/grpc/metrics/proxy/…). Each entry
	// unmarshals from EITHER a scalar int (`http: 8080`) or a struct
	// (`http: {port: 8080, protocol: tcp, expose: true}`). Consumers
	// reference ports BY NAME; a server's primary HTTP port is ports.http.
	Ports         map[string]PortSpec `yaml:"ports,omitempty"`
	Schedule      string              `yaml:"schedule,omitempty"` // cron expression for kind=cron
	ProtoPackages []string            `yaml:"proto_packages,omitempty"`
	// Group is the API group for kind=operator components. e.g.
	// "reliant.dev". Set when scaffolded via `forge add operator`.
	Group string `yaml:"group,omitempty"`
	// Version is the API version for kind=operator components. e.g.
	// "v1alpha1". Set when scaffolded via `forge add operator`.
	Version string `yaml:"version,omitempty"`
	// CRDs lists the CRDs reconciled by this operator. Each entry is
	// a CRD added via `forge add crd <name>` and lives under
	// operators/<operator>/<crd-name>_controller.go plus
	// api/<version>/<crd-name>_types.go.
	CRDs []CRDConfig `yaml:"crds,omitempty"`
}

type ConfigGuardConfig struct {
	// EnforceTypedAccess selects the env-access guardrail strictness:
	// "off" | "warn" | "error". Empty resolves to "warn" — use
	// [ConfigGuardConfig.EffectiveEnforceTypedAccess], don't read the raw
	// string. Unknown values are rejected at load time (validate.go).
	EnforceTypedAccess string `yaml:"enforce_typed_access,omitempty"`
	// LoaderPackage is the allowlisted package path that may read the
	// environment directly — the home of forge's generated config loader.
	// Empty resolves to [DefaultLoaderPackage] ("pkg/config"); use
	// [ConfigGuardConfig.EffectiveLoaderPackage].
	LoaderPackage string `yaml:"loader_package,omitempty"`
}

type ContractsConfig struct {
	Strict             bool     `yaml:"strict"`               // require contract.go for all internal packages with exported methods (default: true)
	AllowExportedVars  bool     `yaml:"allow_exported_vars"`  // allow exported package vars (default: false)
	AllowExportedFuncs bool     `yaml:"allow_exported_funcs"` // allow exported funcs without contract (default: true)
	Exclude            []string `yaml:"exclude"`              // packages that opt out
	// InterfaceTypes lists additional cross-package interface types (over
	// and above the built-in list in internal/generator/contract) that the
	// mock generator should treat as mockable — i.e. emit "nil" as the
	// fallback zero value instead of the invalid composite literal "T{}".
	//
	// Entries are matched against the rendered Go type expression of a
	// contract method's return value, e.g. "billing.MeterClient" or
	// "myproject.SomeProjectLocalInterface". Use this when a contract
	// method returns a project-local interface that the mock generator
	// would otherwise mistakenly treat as a struct.
	InterfaceTypes []string `yaml:"interface_types"`
}

type DatabaseConfig struct {
	Driver          string                `yaml:"driver"` // "postgres" or "none"
	MigrationsDir   string                `yaml:"migrations_dir"`
	MigrationSafety MigrationSafetyConfig `yaml:"migration_safety,omitempty"`
}

type DeployConcurrency struct {
	Enabled          bool `yaml:"enabled"`                      // default true
	CancelInProgress bool `yaml:"cancel_in_progress,omitempty"` // default false
}

type DeployConfig struct {
	Registry       string            `yaml:"registry,omitempty"` // DEPRECATED: prefer docker.registry + per-env KCL; tolerated pending the §4 CI rewire
	Environments   []DeployEnvConfig `yaml:"environments,omitempty"`
	Concurrency    DeployConcurrency `yaml:"concurrency,omitempty"`
	FrontendDeploy string            `yaml:"frontend_deploy,omitempty"` // "firebase", "vercel", "none"
	MigrationTest  bool              `yaml:"migration_test,omitempty"`  // test migrations before deploy

	// TargetArch is the GOARCH the deploy target cluster runs on. When
	// unset, forge defaults to amd64 (the predominant k8s host arch).
	// Setting this at the project level means Mac/arm64 dev machines
	// will cross-compile the Go binary (GOOS=linux GOARCH=<target>
	// CGO_ENABLED=0) and pass --platform=linux/<target> to docker
	// buildx so the image kubelet pulls actually runs on the node.
	//
	// Without cross-compile, an arm64-built image deployed onto an
	// amd64 node fails at pod startup with the opaque kernel-level
	// "exec format error". The CLI's --target-arch flag overrides
	// this per-invocation.
	TargetArch string `yaml:"target_arch,omitempty"`
}

type DeployEnvConfig struct {
	Name       string `yaml:"name"`                 // staging, preprod, prod
	Auto       bool   `yaml:"auto,omitempty"`       // auto-deploy
	Protection bool   `yaml:"protection,omitempty"` // environment protection gates
	URL        string `yaml:"url,omitempty"`        // environment URL
}

type Deps struct{}

type DockerConfig struct {
	Registry string `yaml:"registry"`
	// BuildContexts maps a build-context name to anything `docker buildx
	// --build-context name=value` accepts:
	//
	//   - A local filesystem path. Relative paths are resolved against the
	//     project root (the directory holding forge.yaml). The typical
	//     case is a sibling-checkout local replace directive (e.g. a
	//     `replace x => ../x` in go.mod where ../x lives outside the
	//     project's build context).
	//   - A `docker-image://<image>` ref. Passed through verbatim so a
	//     Dockerfile `FROM <name>` can be overridden with a specific image
	//     at build time (local override of a base image during dev,
	//     pin-by-digest in CI, etc.).
	//   - Any other scheme buildkit understands (e.g. `oci-layout://`,
	//     `https://`). Anything containing `://` is passed through
	//     unchanged.
	//
	// Each entry becomes a `--build-context name=value` arg to `docker
	// build`, letting Dockerfiles consume it via `FROM <name>` or
	// `COPY --from=<name>`. Empty when not set; existing projects with no
	// contexts see no change in build behaviour or output.
	BuildContexts map[string]string `yaml:"build_contexts,omitempty"`
}

type DocsConfig struct {
	Enabled            *bool    `yaml:"enabled,omitempty"`              // nil = true (enabled by default)
	OutputDir          string   `yaml:"output_dir,omitempty"`           // default: "docs/generated"
	Format             string   `yaml:"format,omitempty"`               // "markdown" (default) or "hugo"
	Generators         []string `yaml:"generators,omitempty"`           // e.g. ["api", "architecture", "config", "contracts"]
	CustomTemplatesDir string   `yaml:"custom_templates_dir,omitempty"` // user template overrides
}

type ExperimentalConfig struct {
	Ingress        bool `yaml:"ingress,omitempty"`
	ExternalBuilds bool `yaml:"external_builds,omitempty"`
	Operators      bool `yaml:"operators,omitempty"`
	StrictWiring   bool `yaml:"strict_wiring,omitempty"`
}

type FeatureName = string

type FeaturesConfig struct {
	ORM           *bool `yaml:"orm,omitempty"`           // ORM projection of db/migrations (internal/db/*_orm.go)
	Codegen       *bool `yaml:"codegen,omitempty"`       // service/handler codegen from protos
	Migrations    *bool `yaml:"migrations,omitempty"`    // auto-generate SQL migrations
	CI            *bool `yaml:"ci,omitempty"`            // generate CI/CD workflows
	Build         *bool `yaml:"build,omitempty"`         // `forge build` Go binary + docker image pipeline
	Contracts     *bool `yaml:"contracts,omitempty"`     // contract linter enforcement
	Docs          *bool `yaml:"docs,omitempty"`          // documentation generation
	Frontend      *bool `yaml:"frontend,omitempty"`      // frontend scaffolding + codegen
	Observability *bool `yaml:"observability,omitempty"` // alloy, grafana dashboards, otel wiring
	HotReload     *bool `yaml:"hot_reload,omitempty"`    // air config generation
	Packs         *bool `yaml:"packs,omitempty"`         // forge packs (install/list/info), pack-generate hooks
	Deploy        *bool `yaml:"deploy,omitempty"`        // deploy pipeline: KCL render → kubectl apply, per-env deploy config codegen

	// Diagnostics enables runtime emission of pkg/diagnostics records at
	// Bootstrap time — slog warn lines for every unwired scaffold the
	// codegen pipeline registered (Tier-1 stubs, nil-wired Deps fields).
	// Default OFF: existing projects don't suddenly start logging warns on
	// regen. Opt-in by setting `features.diagnostics: true` in forge.yaml.
	Diagnostics *bool `yaml:"diagnostics,omitempty"`

	// Experimental gates surface that hasn't been battle-tested across
	// real projects + cloud providers. Everything inside is default-OFF
	// (opt-in), every gated CLI invocation prints a one-line warning the
	// first time per process, and the schema is allowed to break between
	// forge versions without a deprecation cycle. Graduates to the
	// top-level FeaturesConfig (with the usual opt-out default-ON
	// semantics) when the feature has shipped through enough real
	// deployments to earn a backwards-compatibility promise.
	Experimental ExperimentalConfig `yaml:"experimental,omitempty"`
	// contains filtered or unexported fields
}

type FrontendConfig struct {
	Name string `yaml:"name"`
	Type string `yaml:"type"`           // "nextjs", "react-native", "vite-spa"
	Kind string `yaml:"kind,omitempty"` // "web" (default/Next.js), "mobile" (React Native), "vite-spa" (Vite + React + tanstack-router)
	Path string `yaml:"path"`
	Port int    `yaml:"port"`
	// Output selects the Next.js build/runtime shape for this frontend.
	// Only meaningful when Type == "nextjs"; ignored for react-native and
	// vite-spa (those have their own production shapes).
	//
	// Valid values:
	//   - "standalone" (default): production builds emit a self-contained
	//     Node server at `.next-prod/standalone/server.js`. This is the shape
	//     the shipped Dockerfile copies into its runner image, and the
	//     only default that supports the dynamic `[id]` CRUD detail/edit
	//     routes forge generates for every entity.
	//   - "static": production builds emit a static export
	//     (`output: "export"` gated on NODE_ENV=production) — pure HTML +
	//     JS + CSS the user can drop on a CDN or object store. The dev
	//     server stays unchanged (`next dev`). EXPLICIT OPT-IN ONLY:
	//     `output: "export"` requires generateStaticParams() on every
	//     dynamic route segment, and the generated CRUD detail/edit
	//     pages (`/<slug>/[id]`) are dynamic client routes whose ids
	//     only exist at runtime — `npm run build` fails on any project
	//     with a CRUD entity unless those pages are removed or given
	//     hand-written static params.
	//   - "server": full Next.js dev AND prod (no `output:` set). Use
	//     when you want `next start` semantics in prod for custom edge /
	//     ISR workflows.
	//
	// Defaults to "standalone" when empty. Pre-existing projects keep
	// their checked-in `next.config.ts`; the field doesn't
	// retroactively rewrite it.
	Output string `yaml:"output,omitempty"`
	// BasePath is the URL path prefix this frontend is mounted under
	// when it is NOT served from the host root — e.g. "/admin" for an
	// admin UI that a reverse proxy blends with another app on the same
	// host. Only meaningful when Type == "nextjs".
	//
	// Shape rules (validated by `forge validate` / LoadStrict):
	//   - must start with "/"            ("/admin", "/internal/admin")
	//   - must not end with "/"          ("/admin/" is rejected)
	//   - must not be bare "/"           (root mount == leave it empty)
	//   - segments are limited to [A-Za-z0-9._-]
	//
	// What it drives:
	//   - next.config.ts: rendered as the build-time default for both
	//     `basePath` and `assetPrefix` (same value — assetPrefix is what
	//     keeps RSC/chunk URLs under the prefix so hydration works).
	//   - src/lib/basepath_gen.ts (Tier-1, regenerated every `forge
	//     generate`): exports BASE_PATH + joinBasePath() for URLs Next.js
	//     can't rewrite (window.location-built redirects, share links).
	//
	// The single runtime override is the NEXT_PUBLIC_BASE_PATH env var —
	// the ONLY base-path variable forge ever reads or writes. Empty
	// (the default) means the frontend is served from the host root.
	BasePath string `yaml:"base_path,omitempty"`
}

type FrontendLintConfig struct {
	CSSHealth      bool   `yaml:"css_health,omitempty"`       // enable stylelint-backed CSS health checks
	NoImportant    string `yaml:"no_important,omitempty"`     // error, warn, off
	NoInlineStyles string `yaml:"no_inline_styles,omitempty"` // error, warn, off
}

type FrontendProjectConfig struct {
	// Workspaces opts the project into the pnpm-workspaces layout. When
	// true:
	//
	//   - A `pnpm-workspace.yaml` is emitted at the project root listing
	//     `packages/*` and `frontends/*` as members.
	//   - `packages/api/` contains the buf-generated Connect TS clients
	//     and proto types as a single workspace package (`@<scope>/api`).
	//   - `packages/hooks/` contains the React Query wrappers
	//     (`use-api-query.ts` / `use-api-mutation.ts`) and the generated
	//     per-service hooks (`packages/hooks/src/generated/`), exposed as
	//     `@<scope>/hooks`.
	//   - Each frontend `package.json` declares the workspace deps via
	//     `"@<scope>/api": "workspace:*"` and imports them by package name
	//     rather than by relative path.
	//
	// When false (the default), forge emits the historic per-frontend
	// layout — `frontends/<name>/src/gen/` for buf output, hooks
	// templated into each `frontends/<name>/src/hooks/` — byte-identical
	// to projects scaffolded before this flag landed.
	Workspaces bool `yaml:"workspaces,omitempty"`
}

type JWTConfig struct {
	Issuer        string `yaml:"issuer,omitempty"`
	Audience      string `yaml:"audience,omitempty"`
	JWKSURL       string `yaml:"jwks_url,omitempty"`
	SigningMethod string `yaml:"signing_method,omitempty"` // HS256, RS256, ES256
}

type K8sConfig struct {
	KCLDir string `yaml:"kcl_dir"`
}

type LintConfig struct {
	Contract bool               `yaml:"contract"`
	Frontend FrontendLintConfig `yaml:"frontend,omitempty"`
	// HandlerFileMaxLOC is the per-file LOC threshold above which the
	// forgeconv-handler-file-size analyzer warns. Counts non-blank, non-
	// comment Go source lines under handlers/<svc>/*.go. A value of 0 (or
	// the field unset) is treated as the built-in default — see
	// [LintConfig.EffectiveHandlerFileMaxLOC] for the canonical value.
	HandlerFileMaxLOC int `yaml:"handler_file_max_loc,omitempty"`
}

type MigrationSafetyConfig struct {
	Enabled            *bool    `yaml:"enabled,omitempty"`             // nil = enabled
	UnsafeAddColumn    string   `yaml:"unsafe_add_column,omitempty"`   // error, warn, off
	DestructiveChange  string   `yaml:"destructive_change,omitempty"`  // error, warn, off
	VolatileDefault    string   `yaml:"volatile_default,omitempty"`    // warn, error, off
	AllowedDestructive []string `yaml:"allowed_destructive,omitempty"` // file globs that may contain destructive changes
}

type MockService struct {
	contractkit.Recorder
	EffectiveKindFunc func(string) string
}

type MultiTenantConfig struct {
	Enabled    bool   `yaml:"enabled"`
	ClaimField string `yaml:"claim_field,omitempty"` // JWT claim to extract tenant ID from, default: "org_id"
	ColumnName string `yaml:"column_name,omitempty"` // DB column name for tenant scoping, default: "org_id"
}

type PackOverride struct {
	// SkipMigrations skips rendering the pack's `migrations:` block at
	// install time. Useful when the project's own migrations supersede
	// the pack's (typical during forge migrations of an existing repo
	// where the schema is already in place).
	SkipMigrations bool `yaml:"skip_migrations,omitempty"`
}

type PackageConfig struct {
	Name string `yaml:"name"`
	Kind string `yaml:"kind,omitempty"` // "" (default/generic), "client", "eventbus"
	// Type captures the hexagonal-architecture role chosen at scaffold
	// time: "service" (default — bootstrap-wired contract package),
	// "adapter" (outbound boundary, marked `// forge:adapter`),
	// "interactor" (use-case orchestrator, marked `// forge:interactor`).
	// Empty (omitted) is treated as "service" for backward compatibility
	// with packages scaffolded before the --type flag landed.
	Type string `yaml:"type,omitempty"`
}

type PlanEntity struct {
	Name       string            `yaml:"name" json:"name"`                                 // PascalCase message name, e.g. "Project"
	TableName  string            `yaml:"table_name,omitempty" json:"table_name,omitempty"` // override; defaults to pluralized snake_case
	SoftDelete bool              `yaml:"soft_delete,omitempty" json:"soft_delete,omitempty"`
	Timestamps bool              `yaml:"timestamps,omitempty" json:"timestamps,omitempty"`
	Fields     []PlanEntityField `yaml:"fields" json:"fields"`
}

type PlanEntityField struct {
	Name       string `yaml:"name" json:"name"` // snake_case proto field name
	Type       string `yaml:"type" json:"type"` // "string", "int64", "bool", "google.protobuf.Timestamp"
	PrimaryKey bool   `yaml:"primary_key,omitempty" json:"primary_key,omitempty"`
	NotNull    bool   `yaml:"not_null,omitempty" json:"not_null,omitempty"`
	Unique     bool   `yaml:"unique,omitempty" json:"unique,omitempty"`
	Default    string `yaml:"default,omitempty" json:"default,omitempty"`
	References string `yaml:"references,omitempty" json:"references,omitempty"` // "users.id"
	TenantKey  bool   `yaml:"tenant_key,omitempty" json:"tenant_key,omitempty"`
	// Generated marks a GENERATED ALWAYS AS (...) STORED column: the DB
	// computes it, so the ORM emits ,scanonly (never written on
	// INSERT/UPDATE).
	Generated bool `yaml:"generated,omitempty" json:"generated,omitempty"`
}

type PlanField struct {
	Name string `yaml:"name" json:"name"`
	Type string `yaml:"type" json:"type"`
}

type PlanFile struct {
	ProjectName string         `yaml:"project_name"`
	GoModule    string         `yaml:"go_module"`
	GoVersion   string         `yaml:"go_version,omitempty"`
	License     string         `yaml:"license,omitempty"`
	MockData    bool           `yaml:"mock_data,omitempty"`
	Services    []PlanService  `yaml:"services,omitempty"`
	Packages    []PlanPackage  `yaml:"packages,omitempty"`
	Frontends   []PlanFrontend `yaml:"frontends,omitempty"`
	Entities    []PlanEntity   `yaml:"entities,omitempty" json:"entities,omitempty"`
}

type PlanFrontend struct {
	Name string `yaml:"name"`
	Kind string `yaml:"kind,omitempty"` // "mobile" for React Native; empty/default = Next.js web
}

type PlanPackage struct {
	Name        string `yaml:"name"`
	Kind        string `yaml:"kind,omitempty"` // "eventbus", "client", or empty
	Description string `yaml:"description,omitempty"`
}

type PlanRPC struct {
	Name        string      `yaml:"name" json:"name"`
	Description string      `yaml:"description,omitempty" json:"description,omitempty"`
	Request     []PlanField `yaml:"request,omitempty" json:"request,omitempty"`
	Response    []PlanField `yaml:"response,omitempty" json:"response,omitempty"`
}

type PlanService struct {
	Name        string    `yaml:"name" json:"name"`
	Description string    `yaml:"description,omitempty" json:"description,omitempty"`
	RPCs        []PlanRPC `yaml:"rpcs,omitempty" json:"rpcs,omitempty"`
}

type PortSpec struct {
	Port     int    `yaml:"port"`
	Protocol string `yaml:"protocol,omitempty"` // tcp (default), udp
	Expose   bool   `yaml:"expose,omitempty"`   // surface on the k8s Service / Dockerfile EXPOSE
}

type ProjectConfig struct {
	Name       string `yaml:"name"`
	ModulePath string `yaml:"module_path"`
	// Kind is the project shape (service|cli|library). It is NO LONGER a
	// forge.yaml field: as of the ProjectStore Phase-2 data move it DERIVES
	// from the components (see DeriveProjectKind) — a project with a
	// server-shaped component is a service, a binary-only project is a cli,
	// an empty one is a library. The loader sets this field after reading
	// components.json; the yaml tag is "-" so a stale `kind:` in forge.yaml
	// is rejected with a migration hint. Every consumer that reads cfg.Kind
	// is unchanged.
	Kind    string `yaml:"-"`
	Binary  string `yaml:"binary,omitempty"` // "per-service" (default), "shared" — one Go binary, cobra subcommand per service
	Version string `yaml:"version,omitempty"`
	// ForgeVersion records the forge binary version that this project's
	// generated artifacts were last produced against. It is set at
	// `forge new` time, bumped after a successful `forge upgrade`, and
	// consulted by `forge generate` to warn when the forge binary on
	// PATH has drifted from the version pinned by the project. Empty
	// (legacy) projects are treated as "0.0.0".
	ForgeVersion string `yaml:"forge_version,omitempty"`
	// HotReload toggles the air-based hot-reload dev loop for `forge run`.
	// *bool so "absent" (nil → derived: on for service kind, off otherwise)
	// is distinguishable from an explicit `hot_reload: false` opt-out. Use
	// EffectiveHotReload; don't read the pointer directly.
	HotReload *bool `yaml:"hot_reload,omitempty"`
	// Components is the unified list of everything this project builds and
	// runs: Connect-RPC servers, in-process workers, scheduled crons,
	// controller-runtime operators, and standalone binaries. The Kind field
	// on each entry is THE discriminator (server|worker|cron|operator|binary).
	//
	// Components are DERIVED from the project's real sources (proto
	// descriptor, the pkg/app service registry, the deploy/kcl tree,
	// internal/handlers, and cmd/ binaries) — NOT authored in forge.yaml.
	// The yaml tag is therefore "-": forge.yaml can no longer carry a
	// `components:` block (a stale one is rejected with a migration hint —
	// see removedSchemaKeys). The loader introspects the real sources and
	// populates this field, so every consumer that reads cfg.Components (and
	// the ProjectStore wrapping it) is unchanged.
	Components []ComponentConfig `yaml:"-"`
	Packages   []PackageConfig   `yaml:"packages,omitempty"`
	Frontends  []FrontendConfig  `yaml:"frontends,omitempty"`
	// Frontend holds project-level frontend settings — distinct from
	// the per-frontend `Frontends []FrontendConfig` slice above. Today
	// it only carries the opt-in `workspaces:` flag that turns on the
	// pnpm-workspace + packages/api + packages/hooks layout so multiple
	// frontends (web + mobile) can share generated Connect clients and
	// React Query hook wrappers. When the flag is false (the default)
	// forge keeps the historic per-frontend layout exactly as before.
	Frontend FrontendProjectConfig `yaml:"frontend,omitempty"`
	// The section blocks below are all omitempty: a freshly scaffolded
	// forge.yaml leaves them absent and the loader fills shape-derived
	// defaults (see ApplyDerivedDefaults in derive.go). A present block
	// is taken literally — write the block (or a single key) to override.
	Database DatabaseConfig `yaml:"database,omitempty"`
	CI       CIConfig       `yaml:"ci,omitempty"`
	// NOTE: there is intentionally NO `build:` field. Build is declared
	// per-service, per-env in KCL (the polymorphic Build union —
	// GoBuild | DockerBuild | ShellBuild on each forge.Service); forge.yaml
	// carries zero build config. A `build:` key in forge.yaml is REJECTED
	// as an unknown key by the strict loader (walkUnknownKeys) rather than
	// silently ignored — version stamping moves to a KCL GoBuild.ldflags
	// `-X` entry.
	Deploy    DeployConfig    `yaml:"deploy,omitempty"`
	Docker    DockerConfig    `yaml:"docker,omitempty"`
	K8s       K8sConfig       `yaml:"k8s,omitempty"`
	Lint      LintConfig      `yaml:"lint,omitempty"`
	Contracts ContractsConfig `yaml:"contracts,omitempty"`
	// Config steers humans and LLMs away from reading the environment
	// directly (os.Getenv / os.LookupEnv / os.Environ) and toward forge's
	// generated, dependency-injected typed config object. See
	// [ConfigGuardConfig] for the enforce_typed_access / loader_package
	// semantics and the absent-key default (warn).
	Config   ConfigGuardConfig `yaml:"config,omitempty"`
	Auth     AuthConfig        `yaml:"auth,omitempty"`
	Docs     DocsConfig        `yaml:"docs,omitempty"`
	Features FeaturesConfig    `yaml:"features,omitempty"`
	Stack    StackConfig       `yaml:"stack,omitempty"`
	// API toggles project-level API protocol skins layered on top of the
	// Connect mux. Default zero-value leaves both REST and OpenAPI off so
	// existing projects regenerate identically. See [APIConfig] for the
	// per-field semantics.
	API APIConfig `yaml:"api,omitempty"`
	// Packs lists the installed forge packs by name. Two KINDS of pack are
	// recorded here, distinguished NOT by a forge.yaml flag but by the
	// pack's own manifest (see internal/packs Pack.Generate):
	//
	//   - ONGOING packs declare a `generate:` block (generate hooks). They
	//     are re-run on every `forge generate` and stay coupled to the
	//     project's codegen — listing them here is load-bearing: the
	//     pipeline replays their hooks. Removing the entry stops the hooks.
	//   - INSTALL-ONCE starters declare only `files:` (no `generate:`). They
	//     copy their scaffold in once and the project OWNS the result after;
	//     the forge.yaml entry is a provenance record, not a re-run trigger.
	//
	// The distinction is derivable from the manifest at install/generate
	// time (a pack with a non-empty Generate is ongoing); it is documented
	// here rather than encoded as a per-entry field so existing forge.yaml
	// files keep their plain string list. See the `packs` vs `starters`
	// skills for the user-facing split.
	Packs         []string                `yaml:"packs,omitempty"`
	PackOverrides map[string]PackOverride `yaml:"pack_overrides,omitempty"`
	// Smoke declares APP-FLOW health checks that `forge smoke <env>` runs in
	// addition to its built-in ingress route / dev-port probes. A route probe
	// only proves listeners are up; a flow check proves the APP actually works
	// (an end-to-end invariant only the app can express). See [SmokeConfig].
	Smoke SmokeConfig `yaml:"smoke,omitempty"`
}

type Service interface {
	// EffectiveKind normalizes a raw kind string to one of the canonical
	// ProjectKind* constants, defaulting to "service" for empty/unknown input.
	EffectiveKind(kind string) string
}

type SmokeConfig struct {
	// FlowChecks are the declared app-flow health endpoints. Each is an HTTP
	// endpoint smoke probes; 2xx = PASS, anything else (typically 503) = FAIL
	// (RED), and any FAIL fails the whole smoke run (non-zero exit), exactly
	// like a failed route probe.
	FlowChecks []SmokeFlowCheck `yaml:"flow_checks,omitempty"`
}

type SmokeFlowCheck struct {
	// Name labels the check in the smoke table / JSON (e.g. "daemon-flow").
	Name string `yaml:"name"`
	// URL is the flow-health endpoint smoke GETs. It may be a per-env literal
	// (e.g. "http://localhost:28091/flow-health" for dev) — scope it with Envs
	// when the URL differs per env. A 2xx is PASS; any other status (or a
	// transport failure) is FAIL.
	URL string `yaml:"url"`
	// Envs optionally scopes the check to specific smoke environments (by
	// name). Empty = probe in every env. Use it when the endpoint URL is
	// env-specific (the usual case — different host/port per env).
	Envs []string `yaml:"envs,omitempty"`
	// Description is an optional human note shown in the smoke detail column.
	Description string `yaml:"description,omitempty"`
}

type StackConfig struct {
	Frontend StackFrontend `yaml:"frontend,omitempty"`
}

type StackFrontend struct {
	Framework string `yaml:"framework,omitempty"` // "nextjs" (default), "react-native", "svelte", "none"
}

type ValidationError struct {
	Path   string
	Issues []validationIssue
}