workflow

type Bag struct {
	// Inputs (set by cmd/ before Run)
	Args               []string
	JSONFlag           bool
	RepoFlag           string // --registry filter
	RemoteFlag         bool   // --remote: show available skills from registries
	BrowseFlag         bool   // browse mode: remote catalog UI with install-first actions
	KitBrowseFlag      bool   // browse mode shows registry kits instead of skills
	InitialQuery       string // initial search/filter text for TUI surfaces
	TrustAllFlag       bool   // --trust-all: approve all package commands without prompting
	InstallAllFlag     bool   // --all: install all available skills without prompting
	ForceBudget        bool   // --force: allow projection over agent description-byte budgets
	ForceKits          bool   // --force-kits: overwrite existing kit files from connect/resync
	RefreshKits        bool   // --refresh-kits: opt into kit refresh during registry resync
	AliasName          string // --alias: install incoming skill under another name on projection conflict
	SkillAliases       map[string]string
	PinnedSkillSources map[string]string
	LazyGitHub         bool // skip eager GitHub client/provider setup for local-only flows
	Factory            *app.Factory

	// SkillFilter is populated by StepSelectSkills with the names the user chose.
	// If non-empty, StepSyncSkills passes it to the Syncer so only those skills
	// are installed. Nil means no filter (all eligible skills processed).
	SkillFilter []string

	// KitFilter is populated by StepResolveKitFilter from the project's
	// .scribe.yaml. When non-nil, StepSyncSkills passes it to the Syncer so
	// only kit-resolved skills are projected into the project's tool dirs.
	KitFilter        []string
	KitFilterEnabled bool

	// ProjectMCPServers is populated by StepResolveMCPServers from kit-declared
	// MCP server names. It is read-only workflow state for future projection;
	// no agent settings are written from this value yet.
	ProjectMCPServers        []string
	ProjectMCPServersEnabled bool

	ProjectSnippets []string

	// Populated by steps
	Config        *config.Config
	State         *state.State
	Client        *gh.Client
	Visibility    RepositoryVisibilityClient
	RegistryIndex registryindex.MetadataClient
	Tools         []tools.Tool
	ProjectRoot   string
	TeamShareMode bool
	Repos         []string // filtered registries to process
	Formatter     Formatter
	StateDirty    bool

	// Provider is the skill discovery/fetch backend. Set by StepLoadConfig.
	Provider provider.Provider

	// Connect-specific
	RepoArg   string // resolved owner/repo from args or prompt
	SourceArg source.SourceSpec
	SourceKey string
	SourceID  string

	// FilterRegistries is injected by cmd/ to bridge flag resolution.
	// If nil, defaults to returning all repos.
	FilterRegistries func(flag string, repos []string) ([]string, error)

	// Results populated by steps for cmd/ to render.
	// List command results (JSON path only — TUI loads its own data):
	LocalSkills   []discovery.Skill             // populated when listing local skills
	RegistryDiffs map[string][]sync.SkillStatus // repo → skill statuses (remote list)
	MultiRegistry bool                          // whether multiple registries are shown
	Partial       bool                          // true when a mutating workflow completed with failures

	// Registry list command results:
	RegistryRepos   []string                // connected registries
	RegistryConfigs []config.RegistryConfig // connected registry config rows
	RegistryCounts  map[string]int          // skills per registry

	// Registry-published kits populated by connect/resync.
	Kits          []provider.KitFile
	KitsInstalled []string
	// contains filtered or unexported fields
}

type ConflictMode int

type Formatter interface {
	// Sync lifecycle
	OnSyncStart(repoCount int)
	OnRegistryStart(repo string)
	OnSkillResolved(name string, status sync.SkillStatus)
	OnSkillDownloading(name string)
	OnSkillInstalled(name string, updated bool, revision int)
	OnSkillSkipped(name string, status sync.SkillStatus)
	OnSkillSkippedByDenyList(name, registry string)
	OnSkillError(name string, err error)
	OnBudgetWarning(agent, message string)
	OnNameConflictResolved(conflict sync.NameConflict, resolution sync.NameConflictResolution)
	OnSyncComplete(summary sync.SyncCompleteMsg)
	OnReconcileConflict(name string, conflict state.ProjectionConflict)
	OnReconcileComplete(summary sync.ReconcileCompleteMsg)
	OnLegacyFormat(repo string)

	// Connect lifecycle
	OnConnectDuplicate(repo string)
	OnConnectSaved(repo string)
	OnConnectSyncing()
	OnConnectSyncWarning(repo string, err error)
	OnConnectAvailable(repo string, count int)
	OnKitsInstalled(repo string, kitNames []string)
	OnKitInstallWarning(kitName string, err error)
	OnKitConflict(kitName, existingSource string)

	// Package lifecycle
	OnPackageInstallPrompt(name, command, source string)
	OnPackageApproved(name string)
	OnPackageDenied(name string)
	OnPackageSkipped(name, reason string)
	OnPackageInstalling(name string)
	OnPackageInstalled(name string)
	OnPackageUpdating(name string)
	OnPackageUpdated(name string)
	OnPackageError(name string, err error, stderr string)
	OnPackageHashMismatch(name, oldCmd, newCmd, source string)

	// Adoption lifecycle
	OnAdoptionSkipped(reason string)
	OnAdoptionStarted(candidateCount int)
	OnAdopted(name string, targetTools []string)
	OnAdoptionError(name string, err error)
	OnAdoptionConflictsDeferred(names []string)
	OnAdoptionComplete(adopted, skipped, failed int)

	// Flush writes any buffered output (JSON mode). Text mode is a no-op.
	Flush() error
}

type ListLocalPackageJSON struct {
	Name        string   `json:"name"`
	Description string   `json:"description,omitempty"`
	Revision    int      `json:"revision,omitempty"`
	Path        string   `json:"path,omitempty"`
	InstallCmd  string   `json:"install_cmd,omitempty"`
	Sources     []string `json:"sources,omitempty"`
}

type ListLocalSkillJSON struct {
	Name        string   `json:"name"`
	Description string   `json:"description,omitempty"`
	Package     string   `json:"package,omitempty"`
	Revision    int      `json:"revision,omitempty"`
	ContentHash string   `json:"content_hash,omitempty"`
	Targets     []string `json:"targets"`
	Managed     bool     `json:"managed"`
	Origin      string   `json:"origin,omitempty"`
	Path        string   `json:"path,omitempty"`
}

type ListOutput map[string]any

type ListRegistryJSON struct {
	Registry string                `json:"registry"`
	Skills   []ListRemoteSkillJSON `json:"skills"`
}

type ListRemoteSkillJSON struct {
	Name       string   `json:"name"`
	Status     string   `json:"status"`
	Version    string   `json:"version,omitempty"`
	LoadoutRef string   `json:"loadout_ref,omitempty"`
	Maintainer string   `json:"maintainer,omitempty"`
	Agents     []string `json:"agents,omitempty"`
}

type ListRow struct {
	Name      string
	Group     string
	Status    sync.Status
	HasStatus bool
	Version   string
	Author    string
	Source    discovery.Source
	Targets   []string
	Local     *discovery.Skill
	Entry     *manifest.Entry
	LatestSHA string
	Excerpt   string
	Managed   bool
	Origin    state.Origin
	Kind      state.Kind
}

type RegistryJSON struct {
	Registry   string `json:"registry"`
	Visibility string `json:"visibility"`
	SkillCount int    `json:"skill_count"`
}

type RegistryListJSON struct {
	Registries []RegistryJSON `json:"registries"`
	LastSync   *string        `json:"last_sync"`
}

type RepositoryVisibilityClient interface {
	RepositoryIsPrivate(ctx context.Context, owner, repo string) (bool, error)
}

type Step struct {
	Name string
	Fn   func(ctx context.Context, b *Bag) error
}