generator

type AuthorSetting struct {
	// Field is the SkeletonConfig field, dotted for a nested one.
	Field string
	Kind  SettingKind
	// Flag is the generate project flag; empty for a run option or a field
	// the wizard and gtb set alone write. Generator.AI is the one setting
	// without a flag, because --ai on generate is the run's own ask (spec
	// 0211 D5, an exception to spec 0197 D4).
	Flag string
	// Wizard is the page key that asks it; empty when the wizard does not.
	Wizard string
	// Manifest is the dotted path from the manifest root, and the vocabulary
	// gtb set understands.
	Manifest string
}

type CommandContext struct {
	// Identity
	Name       string
	ParentPath []string // empty = direct child of root

	// Display
	Short string
	Long  string

	// Routing / feature options
	Aliases              []string
	Args                 string
	WithAssets           bool
	WithInitializer      bool
	WithConfigValidation bool
	PersistentPreRun     bool
	PreRun               bool
	Protected            *bool
	MCPEnabled           *bool // tri-state MCP exposure; mirrors Protected
	MCPHints             setup.MCPHints
	Hidden               bool

	// Project-level settings (carried from the originating generator).
	//
	// Every one of these must be threaded through ToConfig as well as named
	// here. Overwrite was declared on Config but missing from this type, so
	// swapping g.config for a command context silently reset --overwrite to
	// its "ask" default for every command file in the run (issue #13). Taking
	// the whole *Config in buildCommandContext keeps the omission visible in
	// one place rather than spread across four call sites.
	ProjectPath string
	DryRun      bool
	Force       bool
	UpdateDocs  bool
	AI          bool
	NoAI        bool
	AIProvider  string
	AIModel     string
	Overwrite   OverwriteMode
}

type CommandFlag struct {
	Default       string
	DefaultIsCode bool
	Description   string
	Hidden        bool
	Name          string
	Persistent    bool
	Required      bool
	Shorthand     string
	Type          string
}

type CommandPipeline struct {
	// contains filtered or unexported fields
}

type Config struct {
	// NoVerify skips the post-processing steps (go mod tidy, golangci-lint)
	// after generate project and regenerate project, for a caller who knows
	// the tree cannot be verified here (offline, pre-tag). The run then exits
	// 0 having emitted files it did not verify (spec 0197 D10).
	NoVerify bool

	// AI and NoAI are the run's own answer on calling a model (spec 0211 D4);
	// without either, the manifest and then the person's config decide.
	AI         bool
	NoAI       bool
	AIModel    string
	AIProvider string
	// MaxSteps bounds the autonomous repair agent's ReAct loop. Zero uses the
	// framework default (gochat.DefaultMaxSteps). Raise it for complex commands
	// the agent cannot finish within the default budget.
	MaxSteps int
	// NonInteractive withholds the repair agent's query_user tool so a
	// generation never blocks for input (CI / --non-interactive).
	NonInteractive bool
	Aliases        []string
	Args           string
	DryRun         bool
	// GitInit controls the post-generation git step on `generate project`
	// (init + stage + initial commit). It is opt-out: the CLI sets it true by
	// default and false under --no-git. Only honoured by GenerateSkeleton.
	GitInit bool
	// GitPush, when true (--push), adds the derived remote as origin and pushes
	// the initial commit. Opt-in; requires GitInit. Push failures are non-fatal.
	GitPush bool
	// GitBranch is the default branch the initial commit lands on (default
	// "main", overridable via --git-branch).
	GitBranch        string
	Flags            []string
	Force            bool
	Hidden           bool
	Overwrite        OverwriteMode // default ask
	Long             string
	Name             string
	Parent           string
	Path             string
	PersistentPreRun bool
	PreRun           bool
	Prompt           string
	Protected        *bool
	MCPEnabled       *bool // tri-state MCP exposure; mirrors Protected
	MCPHints         setup.MCPHints
	ScriptPath       string
	Short            string
	UpdateDocs       bool
	// PublicAPI marks the module as publicly published (the --public-api flag),
	// so generated package docs defer their API reference to pkg.go.dev. Default
	// false: the reference is stubbed to a local `go doc` hint (no dead links for
	// a private/unpublished module). The manifest module_published property is the
	// persistent equivalent.
	PublicAPI bool
	// NoAIAttribution, when true (the --no-ai-attribution flag on `generate
	// docs`), flips the documentation system prompt so the frontmatter `authors:`
	// field carries the project's human author(s) only — the model is instructed
	// to add no AI/model/assistant identity. Default false: AI attribution is
	// additive (existing human authors preserved, AI model appended as a
	// co-author). See docs.go authorsDirectives and issue #7.
	NoAIAttribution      bool
	WithAssets           bool
	WithConfigValidation bool
	WithInitializer      bool
}

type DryRunResult struct {
	Created  []FilePreview `json:"created,omitempty"`
	Modified []FilePreview `json:"modified,omitempty"`
	// Actions describes non-file side effects the run would perform (e.g. the
	// post-generation git init/commit/push), surfaced as plain text lines.
	Actions []string `json:"actions,omitempty"`
}

type ExternalCommandSpec = ManifestExternalCommand

type FilePreview struct {
	Path    string `json:"path"`
	Content []byte `json:"content,omitempty"`
	Diff    string `json:"diff,omitempty"`
}

type Generator struct {
	// contains filtered or unexported fields
}

type IgnoreCheckResult struct {
	Path    string // the queried path
	Ignored bool   // final decision under last-match-wins + ! negation
	Matched bool   // whether any rule matched at all
	Rule    string // the winning rule line as written (empty when Matched is false)
	Negated bool   // whether the winning rule was a negation
	// State is the resolved tier: managed, ignored or sealed. Ignored stays for
	// the render question specifically; State is what distinguishes a path the
	// generator may still wire from one it must not touch at all (spec 0188 D7).
	State RuleState
}

type IgnoreListEntry struct {
	Path    string
	Ignored bool
	Rule    string // winning rule line (empty when no rule matched)
	State   RuleState
}

type IgnoreListing struct {
	Rules      []string          // active rule lines, in file order
	Entries    []IgnoreListEntry // tracked files governed by a rule, sorted by path
	StaleRules []string          // rules that match no tracked file
}

type IgnoreRules struct {
	// contains filtered or unexported fields
}

type Manifest struct {
	Properties    ManifestProperties    `yaml:"properties"`
	ReleaseSource ManifestReleaseSource `yaml:"release_source"`
	Version       ManifestVersion       `yaml:"version"`
	Hashes        map[string]string     `yaml:"hashes,omitempty"` // project-level file hashes (relative path → SHA256)
	Commands      []ManifestCommand     `yaml:"commands,omitempty"`
}

type ManifestBootstrap struct {
	// AutoInitialise runs a non-interactive init to write the default config
	// when it is missing, instead of failing. Defaults to false.
	AutoInitialise bool `yaml:"auto_initialise,omitempty"`
	// SkipConfigCheck lists commands (by Name() or full CommandPath()) whose
	// missing-config gate is relaxed to a tolerant load so they own bootstrap.
	SkipConfigCheck []string `yaml:"skip_config_check,omitempty"`
	// AuxiliaryCommands names commands that take the root pre-run's
	// auxiliary fast path (props.Tool.AuxiliaryCommands); spec 0197 D4.
	AuxiliaryCommands []string `yaml:"auxiliary_commands,omitempty"`
}

type ManifestCI struct {
	// ComponentSource is the include base for the phpboyscout/cicd
	// components in the scaffolded .gitlab-ci.yml. Empty means "use the
	// framework default" (DefaultCICDComponentSource,
	// gitlab.com/phpboyscout/cicd); a mirrored/self-hosted downstream sets
	// this to repoint the include base. Defaulted on render so a manifest
	// with no ci block still produces a complete pipeline.
	ComponentSource string `yaml:"component_source,omitempty"`
}

type ManifestChat struct {
	Providers []string            `yaml:"providers"`
	Default   ManifestChatDefault `yaml:"default,omitempty"`
	// ToolBridge set false leaves go/chat-mcptools unlinked even though
	// claude-local or codex-local is selected: the tool carries no MCP SDK,
	// and those providers refuse tools. Unset links it when they need it.
	ToolBridge *bool `yaml:"tool_bridge,omitempty"`
}

type ManifestChatDefault struct {
	Provider   string `yaml:"provider,omitempty"`
	Model      string `yaml:"model,omitempty"`
	BaseURL    string `yaml:"base_url,omitempty"`
	APIVersion string `yaml:"api_version,omitempty"`
	Project    string `yaml:"project,omitempty"`
	Location   string `yaml:"location,omitempty"`
}

type ManifestCommand struct {
	Name                 string            `yaml:"name"`
	Description          MultilineString   `yaml:"description"`
	LongDescription      MultilineString   `yaml:"long_description,omitempty"`
	Aliases              []string          `yaml:"aliases,omitempty"`
	Hidden               bool              `yaml:"hidden,omitempty"`
	Args                 string            `yaml:"args,omitempty"`
	Hash                 string            `yaml:"hash,omitempty"` // Deprecated: use Hashes
	Hashes               map[string]string `yaml:"hashes,omitempty"`
	WithAssets           bool              `yaml:"with_assets,omitempty"`
	WithInitializer      bool              `yaml:"with_initializer,omitempty"`
	WithConfigValidation bool              `yaml:"with_config_validation,omitempty"`
	Protected            *bool             `yaml:"protected,omitempty"`
	// MCPEnabled is the tri-state MCP-exposure decision for this command:
	// nil = inherit (default exposed), true = explicitly exposed, false =
	// excluded from the MCP tool surface. Build-time only; see
	// https://gitlab.com/phpboyscout/go-tool-base/-/wikis/specs/0089-mcp-command-exposure-gating.
	MCPEnabled *bool `yaml:"mcp_enabled,omitempty"`
	// MCPHints are the MCP tool annotations the command declares about itself
	// (spec 0201 D5). Absent means it states nothing; each hint is tri-state.
	MCPHints *ManifestMCPHints `yaml:"mcp_hints,omitempty"`

	PersistentPreRun  bool              `yaml:"persistent_pre_run,omitempty"`
	PreRun            bool              `yaml:"pre_run,omitempty"`
	MutuallyExclusive [][]string        `yaml:"mutually_exclusive,omitempty"`
	RequiredTogether  [][]string        `yaml:"required_together,omitempty"`
	Flags             []ManifestFlag    `yaml:"flags,omitempty"`
	Commands          []ManifestCommand `yaml:"commands,omitempty"`
	Warning           string            `yaml:"-"` // Used for comments
}

type ManifestCommandUpdate struct {
	Name                 string
	Description          string
	LongDescription      string
	Aliases              []string
	Args                 string
	Hashes               map[string]string
	Flags                []ManifestFlag
	WithAssets           bool
	WithInitializer      bool
	WithConfigValidation bool
	PersistentPreRun     bool
	PreRun               bool
	Protected            *bool
	MCPEnabled           *bool
	MCPHints             *ManifestMCPHints
	Hidden               bool
}

type ManifestConfig struct {
	// Layers is the stack by name, lowest precedence first (see
	// props.ConfigLayer). Empty means the project states nothing and inherits
	// the framework default.
	Layers []string `yaml:"layers,omitempty"`
	// Formats are the config formats the tool links beyond YAML, which is
	// built in and never listed (spec 0204 D2). Each is a blank import in
	// cmd/<name>/config.go.
	Formats []string `yaml:"formats,omitempty"`
	// Format is the tool's own config format; empty is YAML.
	Format string `yaml:"format,omitempty"`
	// Sources are the declared config source slots, each placed in Layers
	// (spec 0204 D15).
	Sources []ManifestConfigSource `yaml:"sources,omitempty"`
	// KeyCase is the config stack's key mode, folded or exact; empty is
	// folded (spec 0209).
	KeyCase string `yaml:"key_case,omitempty"`
}

type ManifestConfigSource struct {
	Name string `yaml:"name"`
	Kind string `yaml:"kind"`
	// Required, when absent, is true (spec 0204 D6).
	Required *bool `yaml:"required,omitempty"`
	// Writable, when absent, is the kind's default (spec 0204 D7, D12).
	Writable *bool `yaml:"writable,omitempty"`
}

type ManifestDirectSource struct {
	URLTemplate          string `yaml:"url_template,omitempty"`
	ChecksumURLTemplate  string `yaml:"checksum_url_template,omitempty"`
	SignatureURLTemplate string `yaml:"signature_url_template,omitempty"`
	VersionURL           string `yaml:"version_url,omitempty"`
	VersionFormat        string `yaml:"version_format,omitempty"`
	VersionKey           string `yaml:"version_key,omitempty"`
	PinnedVersion        string `yaml:"pinned_version,omitempty"`
}

type ManifestExternalAttach struct {
	// Constructor is the exported symbol to call, e.g. "NewCmdSign".
	Constructor string `yaml:"constructor"`
	// Args are injection tokens from the closed vocabulary
	// ([templates.ExternalArgTokens]), rendered in order. Empty means a
	// zero-argument constructor.
	Args []string `yaml:"args,omitempty"`
	// Wrap is true when Constructor returns *cobra.Command and must be wrapped
	// via setup.Wrap("", …); false when it returns *setup.Command and is
	// attached directly. It describes the constructor's return type, not gating
	// — declarative attachments are un-gated (always-on) in v1.
	Wrap bool `yaml:"wrap"`
	// Name, if set, is the expected top-level command name, used only for
	// best-effort collision detection. It does not affect the rendered call.
	Name string `yaml:"name,omitempty"`
}

type ManifestExternalCommand struct {
	// Module is the Go module path providing the commands, e.g.
	// "gitlab.com/phpboyscout/go/signing-cli". Used for the go.mod require.
	Module string `yaml:"module"`
	// Version is the module version to require, e.g. "v0.1.0". Required — an
	// explicit pin; there is no implicit latest resolution.
	Version string `yaml:"version"`
	// ImportPath is the package to import for the constructors. Defaults to
	// Module when empty (the signing-cli case: the constructors live in the
	// module root package).
	ImportPath string `yaml:"import_path,omitempty"`
	// Alias is the import alias for ImportPath in the generated root. Defaults
	// to the import path's base name when empty.
	Alias string `yaml:"alias,omitempty"`
	// Attach lists the constructor calls to render onto the root. At least one
	// entry is required — a module with nothing to attach is meaningless.
	Attach []ManifestExternalAttach `yaml:"attach"`
}

type ManifestFeature struct {
	Name    string `yaml:"name"`
	Enabled bool   `yaml:"enabled"`
}

type ManifestFlag struct {
	Name          string          `yaml:"name"`
	Type          string          `yaml:"type"`
	Description   MultilineString `yaml:"description"`
	Persistent    bool            `yaml:"persistent,omitempty"`
	Shorthand     string          `yaml:"shorthand,omitempty"`
	Default       string          `yaml:"default,omitempty"`
	DefaultIsCode bool            `yaml:"default_is_code,omitempty"`
	Required      bool            `yaml:"required,omitempty"`
	Hidden        bool            `yaml:"hidden,omitempty"`
	Warning       string          `yaml:"-"` // Used for comments
}

type ManifestGenerator struct {
	// AI is the project's recorded choice on gtb calling a model while
	// generating it. Absent defers to the person's generator.ai (spec 0211).
	AI *bool `yaml:"ai,omitempty"`
}

type ManifestHelp struct {
	Type         string `yaml:"type,omitempty"`
	SlackChannel string `yaml:"slack_channel,omitempty"`
	SlackTeam    string `yaml:"slack_team,omitempty"`
	TeamsChannel string `yaml:"teams_channel,omitempty"`
	TeamsTeam    string `yaml:"teams_team,omitempty"`
}

type ManifestMCP struct {
	Mode string `yaml:"mode,omitempty"`
}

type ManifestMCPHints struct {
	Title       string `yaml:"title,omitempty"`
	ReadOnly    *bool  `yaml:"read_only,omitempty"`
	Destructive *bool  `yaml:"destructive,omitempty"`
	Idempotent  *bool  `yaml:"idempotent,omitempty"`
	OpenWorld   *bool  `yaml:"open_world,omitempty"`
}

type ManifestProperties struct {
	Name        string            `yaml:"name"`
	Description MultilineString   `yaml:"description"`
	Features    []ManifestFeature `yaml:"features"`
	EnvPrefix   string            `yaml:"env_prefix,omitempty"`
	// UpdatePolicy is the generated tool's self-update posture baseline
	// (disabled / prompt / enabled). Empty = framework default (disabled).
	UpdatePolicy string `yaml:"update_policy,omitempty"`
	// UpdateCheckInterval is the generated tool's baseline self-update-check
	// throttle as a Go duration string (e.g. "24h"). Empty = framework
	// default (24h).
	UpdateCheckInterval string            `yaml:"update_check_interval,omitempty"`
	Help                ManifestHelp      `yaml:"help,omitempty"`
	Telemetry           ManifestTelemetry `yaml:"telemetry,omitempty"`
	Signing             ManifestSigning   `yaml:"signing,omitempty"`
	// Chat records the chat providers the tool ships, each a blank import of
	// the module that registers it in cmd/<name>/chat.go. A project generated
	// before this field existed has no block; regenerate reads that as every
	// provider the framework could configure at the time and writes the list
	// out explicitly (spec 0194 D5, D7).
	Chat      ManifestChat      `yaml:"chat,omitempty"`
	Bootstrap ManifestBootstrap `yaml:"bootstrap,omitempty"`
	Generator ManifestGenerator `yaml:"generator,omitempty"`
	CI        ManifestCI        `yaml:"ci,omitempty"`
	// Templates records the custom template-overlay sources applied to the
	// project, in render (layer) order: embedded base → templates[0] →
	// templates[1] → … (last writer wins for a shared path). Each entry is
	// provenance + pinning only; suppression behaviour lives in the source's
	// own gtb-template.yaml descriptor. See
	// https://gitlab.com/phpboyscout/go-tool-base/-/wikis/specs/0080-generator-custom-partial-templates.
	Templates []TemplateSource `yaml:"templates,omitempty"`
	// ModulePath is the Go module path (spec 0195 D5). A hosted project
	// derives <host>/<org>/<repo>; one that is not names its own. Absent on a
	// manifest that predates the field; regenerate derives and records it.
	ModulePath string `yaml:"module_path,omitempty"`
	// ForgeCredentials are forges enabled for their credential wizard and
	// adapter only, never the release source (spec 0195 D6).
	ForgeCredentials []props.FeatureID `yaml:"forge_credentials,omitempty"`
	// Config declares the project's configuration stack (spec 0204). It is
	// declared here rather than hand-wired in the scaffolded main because the
	// manifest reconstructs byte-exactly from scratch: a hand-wired stack would
	// be a hole reconstruction cannot fill (spec 0183 D8).
	Config ManifestConfig `yaml:"config,omitempty"`
	// LegacyConfigLayers is spec 0183's config_layers, read so the first
	// regenerate can move it into Config.Layers (spec 0204 D13) and never
	// written.
	LegacyConfigLayers []string `yaml:"config_layers,omitempty"`
	// MCP is the tool's MCP publication mode (spec 0201 D3): "direct" publishes
	// one native tool per command; absent or "compact" publishes the three
	// discovery tools. Rendered into props.Tool.MCP; the binary never reads it.
	MCP ManifestMCP `yaml:"mcp,omitempty"`
	// DocsLayout records the documentation tree layout: [DocsLayoutDiataxis]
	// (the default for newly generated projects) or [DocsLayoutFlat] (the legacy
	// docs/commands + docs/packages tree). Empty is treated as flat for backward
	// compatibility with projects generated before this field existed.
	DocsLayout string `yaml:"docs_layout,omitempty"`
	// ModulePublished indicates the module is publicly published (e.g. on
	// pkg.go.dev), allowing generated explanation docs to defer the package API
	// reference there. Default false: the API reference is stubbed locally, since
	// an unpublished module has no pkg.go.dev page to link.
	ModulePublished bool `yaml:"module_published,omitempty"`
	// ExternalCommands declares external Cobra command trees attached to the
	// generated project's root via the declarative channel — the manifest
	// records the module pin + the call descriptors, and the generator renders
	// the attach calls into pkg/cmd/root/cmd.go on every root render (so they
	// survive regenerate / enable / disable). See
	// https://gitlab.com/phpboyscout/go-tool-base/-/wikis/specs/0182-external-command-attachment.
	ExternalCommands []ManifestExternalCommand `yaml:"external_commands,omitempty"`
	// ExternalCommandsAdapter, when true, wires the user-owned adapter escape
	// hatch (pkg/cmd/external/attach.go, exposing external.Commands(p)) into the
	// generated root. The adapter file is scaffolded once and thereafter
	// author-owned; this flag only records that the root must emit the call.
	ExternalCommandsAdapter bool `yaml:"external_commands_adapter,omitempty"`
}

type ManifestReleaseSource struct {
	Type string `yaml:"type"`
	// Backend is the forge the project is hosted on (spec 0195 D2). Absent on
	// a manifest that predates the field; regenerate derives and records it.
	Backend props.FeatureID `yaml:"backend,omitempty"`
	Host    string          `yaml:"host"`
	Owner   string          `yaml:"owner"`
	Repo    string          `yaml:"repo"`
	Private bool            `yaml:"private,omitempty"`
	// Static is the static release channel's one setting when Type is static
	// (spec 0203 D1).
	Static ManifestStaticSource `yaml:"static,omitempty"`
	// Direct is the withdrawn direct channel's block (spec 0195 D7). It is
	// kept so an older manifest loads; nothing reads it and regenerate drops
	// it (spec 0203 D9).
	Direct ManifestDirectSource `yaml:"direct,omitempty"`
}

type ManifestSigning struct {
	// Enabled gates all signing scaffolding. Defaults to false; set true
	// by `gtb enable signing` or `gtb generate project --signing`.
	Enabled bool `yaml:"enabled,omitempty"`
	// ExternalKeyEmail derives the WKD URL and enables the external
	// (WKD) trust-anchor leg. Empty leaves verification embedded-only.
	ExternalKeyEmail string `yaml:"external_key_email,omitempty"`
	// RequireSignature fails an update closed when no valid signature is
	// present. Stays false until a signed release has shipped (the N+1
	// rollout); only ever flipped via `gtb enable signing --require-signature`.
	RequireSignature bool `yaml:"require_signature,omitempty"`
	// RequireChecksum is the author's baseline for checksum enforcement on
	// self-update downloads (props.Tool.RequireChecksum); spec 0197 D4.
	RequireChecksum bool `yaml:"require_checksum,omitempty"`
	// KeySource selects the trust-anchor source: "embedded", "external"
	// or "both" (the framework default when empty).
	KeySource string `yaml:"key_source,omitempty"`
	// RequireExternalCrosscheck fails closed when the external (WKD)
	// resolver is unreachable, rather than degrading to embedded-only.
	RequireExternalCrosscheck bool `yaml:"require_external_crosscheck,omitempty"`
	// Backend selects the `gtb sign` backend the generated release
	// pipeline signs with (e.g. "aws-kms", "local"). Defaults to
	// "aws-kms" when a key id is recorded. Drives the GoReleaser signs
	// block; backend-specific args (e.g. kms_region) are emitted only for
	// the backends that take them.
	Backend string `yaml:"backend,omitempty"`
	// KeyID is the backend-specific signing key identifier passed to
	// `gtb sign --key-id` (a KMS id/ARN/alias, or a PEM path for the
	// local backend). Recording it is what turns the GoReleaser signs
	// block on; empty leaves the release pipeline untouched.
	KeyID string `yaml:"key_id,omitempty"`
	// KMSRegion is the AWS region for the aws-kms backend
	// (`gtb sign --kms-region`). Defaults to "eu-west-2". Ignored by
	// backends that don't take a region.
	KMSRegion string `yaml:"kms_region,omitempty"`
	// PublicKey is the path to the armored public-key file the signature
	// identifies (`gtb sign --public-key`), relative to the project root.
	// Defaults to the embedded-key convention
	// internal/trustkeys/keys/signing-key-v1.asc.
	PublicKey string `yaml:"public_key,omitempty"`
}

type ManifestStaticSource struct {
	BaseURL string `yaml:"base_url,omitempty"`
}

type ManifestTelemetry struct {
	Endpoint     string `yaml:"endpoint,omitempty"`
	OTelEndpoint string `yaml:"otel_endpoint,omitempty"`
}

type ManifestVersion struct {
	GoToolBase string `yaml:"gtb"`
	// Go is the go directive the project was generated with, so regenerate
	// rewrites the go line only when this changes and never because the
	// author's toolchain moved (spec 0197 D3). Absent in older manifests.
	Go string `yaml:"go,omitempty"`
}

type MultilineString string

type OverwriteMode string

type PipelineOptions struct {
	SkipAssets        bool // do not generate asset files
	SkipDocumentation bool // do not run documentation generation
	SkipRegistration  bool // do not modify the parent cmd.go
	// BoilerplateDocsOnly writes a missing doc page without consulting a chat
	// provider: a regenerate is a deterministic rewrite, and its AI pass is
	// what --update-docs or --ai asks for (#35, spec 0211).
	BoilerplateDocsOnly bool
}

type PipelineResult struct {
	Warnings []StepWarning
}

type RuleState int

type SettingKind string

type SkeletonConfig struct {
	Name                  string
	Repo                  string
	Host                  string
	Description           string
	Path                  string
	GoVersion             string // overrides autodetected version when set
	Features              []ManifestFeature
	Private               bool   // true if the repository requires authentication to access
	HelpType              string // "slack", "teams", or ""
	SlackChannel          string
	SlackTeam             string
	TeamsChannel          string
	TeamsTeam             string
	TelemetryEndpoint     string // populated from manifest telemetry.endpoint
	TelemetryOTelEndpoint string // populated from manifest telemetry.otel_endpoint
	EnvPrefix             string // environment variable prefix for config overrides
	// ConfigLayers declares which config-stack layers the project wires. Empty
	// inherits the framework default, which is what every project generated
	// before this field existed does.
	ConfigLayers []string
	// ConfigFormats are the config formats the tool links; ConfigFormat is its
	// own (spec 0204 D2).
	ConfigFormats []string
	ConfigFormat  string
	// ConfigSources are the declared config source slots (spec 0204 D15).
	ConfigSources []ManifestConfigSource
	// ConfigKeyCase is the config stack's key mode, folded or exact (spec 0209).
	ConfigKeyCase string
	Signing       ManifestSigning   // self-update signature-verification posture (disabled by default)
	Chat          ManifestChat      // chat providers the tool links (cmd/<name>/chat.go)
	Bootstrap     ManifestBootstrap // config-bootstrap lifecycle policy (auto-init / skip-config-check)
	Generator     ManifestGenerator // how gtb itself may work on the project (spec 0211)
	// MCPMode is the MCP publication mode: "" or "compact" for the discovery
	// facade, "direct" for one native tool per command (spec 0201 D3).
	MCPMode string
	// UpdatePolicy is the generated tool's self-update posture baseline
	// (disabled / prompt / enabled). Empty leaves it unset so the framework
	// default (disabled) applies; wired into the generated root command's
	// props.Tool.UpdatePolicy. See https://gitlab.com/phpboyscout/go-tool-base/-/wikis/specs/0087-forced-update-feature.
	UpdatePolicy string
	// UpdateCheckInterval is the generated tool's baseline self-update-check
	// throttle as a Go duration string (e.g. "24h"). Empty leaves it unset so
	// the framework default (24h) applies; wired into the generated root
	// command's props.Tool.UpdateCheckInterval.
	UpdateCheckInterval string
	// CIComponentSource overrides the phpboyscout/cicd include base in the
	// scaffolded GitLab pipeline. Empty falls back to
	// DefaultCICDComponentSource. GitLab-only; ignored for GitHub projects.
	CIComponentSource string
	// Templates carries the custom template-overlay sources (in layer order)
	// through generation. The wizard/flags populate it and
	// writeSkeletonManifest persists it.
	Templates []TemplateSource
	// ForgeBackend is the forge the project is hosted on (spec 0195 D2 and
	// D4). Empty means not hosted: no forge feature, adapter or credential
	// wizard, and ModulePath must be given.
	ForgeBackend props.FeatureID
	// ForgeCredentials are further forges enabled for credential capture and
	// their adapter, without affecting the release source (spec 0195 D6).
	ForgeCredentials []props.FeatureID
	// ModulePath is the Go module path; empty derives <host>/<repo> for a
	// hosted project (spec 0195 D5).
	ModulePath string
	// ReleaseChannel is forge or static when the update feature is enabled
	// (spec 0195 D7, spec 0203 D1); empty falls back to the backend's source
	// type.
	ReleaseChannel string
	// ReleaseBaseURL is the static channel's location (spec 0203 D1), read
	// only when ReleaseChannel is static.
	ReleaseBaseURL string
}

type StepWarning struct {
	Step string
	Err  error
}

type TemplateContractData struct {
	Name              string
	Description       string
	Repo              string
	Host              string
	Org               string
	RepoName          string
	ModulePath        string
	ReleaseProvider   string
	GoVersion         string
	GoToolBaseVersion string
	EnvPrefix         string
	EnabledFeatures   []string
	DisabledFeatures  []string
	Private           bool
	// SigningEnabled / HelpType expose only presence/shape, never secrets.
	SigningEnabled bool
	HelpType       string
}

type TemplateDescriptor struct {
	// Contract is the data-contract version the set targets. Zero is treated
	// as version 1 (the only version) for descriptors that omit it; any
	// value above supportedContractVersion is rejected.
	Contract int `yaml:"contract"`
	// Description is a human-facing summary of the template set.
	Description string `yaml:"description"`
	// Replaces names the embedded scaffolds this set supersedes. Each entry
	// must be a known alias in suppressibleAliases.
	Replaces []string `yaml:"replaces"`
}

type TemplateSource struct {
	// Name is an optional operator-assigned handle used by
	// `gtb template update/remove <name>`. Defaults to the repo/dir base
	// name when unset.
	Name string `yaml:"name,omitempty"`
	// Type is "git" or "local".
	Type TemplateSourceType `yaml:"type"`
	// Location is the forge repo path (org/repo, nested GitLab groups
	// supported) or a full clone URL for git sources, or a filesystem path
	// for local sources.
	Location string `yaml:"location"`
	// Ref is the branch/tag/commit the operator specified, recorded verbatim
	// (provenance). Empty/"" defaults to the source's default branch.
	Ref string `yaml:"ref,omitempty"`
	// Resolved is the commit SHA Ref resolved to at generate time — the pin
	// regenerate reproduces from. Empty for local sources.
	Resolved string `yaml:"resolved,omitempty"`
	// Fingerprint is a content fingerprint of a local source's tree at
	// generate time, so regenerate can warn when the on-disk source drifts.
	// Empty for git sources (the resolved SHA is the pin).
	Fingerprint string `yaml:"fingerprint,omitempty"`
	// Hashes records each rendered overlay file's SHA256 keyed by output
	// relative path, so a source's footprint is self-contained and can be
	// removed cleanly (D5).
	Hashes map[string]string `yaml:"hashes,omitempty"`
}

type TemplateSourceType string