v1alpha1

type Agent struct {
	TypeMeta `json:",inline" yaml:",inline"`
	Metadata ObjectMeta `json:"metadata" yaml:"metadata"`
	Spec     AgentSpec  `json:"spec" yaml:"spec"`
	Status   Status     `json:"status,omitzero" yaml:"status,omitempty"`
}

type AgentProtocol string

type AgentSource struct {
	// Image is the OCI container image reference that runs the agent.
	// Format: <registry>/<name>:<tag> (e.g. ghcr.io/owner/agent:1.0.0).
	Image string `json:"image,omitempty" yaml:"image,omitempty"`

	// Repository links to the source code the image was built from.
	Repository *Repository `json:"repository,omitempty" yaml:"repository,omitempty"`

	// Protocol is the application protocol spoken by every runnable form of the
	// agent, whether built from Repository or supplied as Image. When omitted,
	// A2A is inferred as the default.
	Protocol *AgentProtocol `json:"protocol,omitempty" yaml:"protocol,omitempty" enum:"A2A,HTTP"`
}

type AgentSpec struct {
	// Core fields.
	Title       string `json:"title,omitempty" yaml:"title,omitempty"`
	Description string `json:"description,omitempty" yaml:"description,omitempty"`

	// ModelProvider and ModelName are retained for one release so existing
	// Agent resources continue to decode and round-trip without data loss.
	//
	// Deprecated: these fields do not select or configure a runtime model.
	// New and migrated Deployments must use spec.modelRef; distributions may
	// temporarily preserve Deployment MODEL_PROVIDER / MODEL_NAME environment
	// values when modelRef is omitted.
	ModelProvider string `json:"modelProvider,omitempty" yaml:"modelProvider,omitempty" deprecated:"true"`
	ModelName     string `json:"modelName,omitempty" yaml:"modelName,omitempty" deprecated:"true"`

	// Source declares where the agent comes from — Image (the runtime
	// container) and/or Repository (the source code).
	Source *AgentSource `json:"source,omitempty" yaml:"source,omitempty"`

	// CompatibleHarnesses declares which coding harnesses this Agent can run
	// under. The Deployment selects the concrete harness type for a
	// rollout; Agent remains the portable compatibility contract.
	CompatibleHarnesses []HarnessCompatibility `json:"compatibleHarnesses,omitempty" yaml:"compatibleHarnesses,omitempty"`

	// Composition — top-level, harness-agnostic references to what the agent
	// is assembled from. The selected Deployment harness materializes what it
	// supports and drops-with-warning the rest (capability matrix). Plugins,
	// Skills, and Instructions require compatibleHarnesses because a prebuilt
	// Image cannot consume them by itself. MCPServers flow to harness runtimes
	// and remain available to any other runtime that supports MCP. Each ref's
	// Kind defaults to the field's resource kind; empty Tag means "resolve
	// latest at reference time".
	Plugins      []ResourceRef `json:"plugins,omitempty" yaml:"plugins,omitempty"`
	Skills       []ResourceRef `json:"skills,omitempty" yaml:"skills,omitempty"`
	Instructions *ResourceRef  `json:"instructions,omitempty" yaml:"instructions,omitempty"`
	MCPServers   []ResourceRef `json:"mcpServers,omitempty" yaml:"mcpServers,omitempty"`
}

type CommandEntry struct {
	Source       string   `json:"source,omitempty" yaml:"source,omitempty"`
	Content      string   `json:"content,omitempty" yaml:"content,omitempty"`
	Description  string   `json:"description,omitempty" yaml:"description,omitempty"`
	ArgumentHint string   `json:"argumentHint,omitempty" yaml:"argumentHint,omitempty"`
	Model        string   `json:"model,omitempty" yaml:"model,omitempty"`
	AllowedTools []string `json:"allowedTools,omitempty" yaml:"allowedTools,omitempty"`
}

type CommandsField struct {
	Paths *PathOrPaths
	Map   map[string]CommandEntry
}

type Condition struct {
	Type               string          `json:"type" yaml:"type"`
	Status             ConditionStatus `json:"status" yaml:"status"`
	Reason             string          `json:"reason,omitempty" yaml:"reason,omitempty"`
	Message            string          `json:"message,omitempty" yaml:"message,omitempty"`
	LastTransitionTime time.Time       `json:"lastTransitionTime,omitzero" yaml:"lastTransitionTime,omitempty"`
	ObservedGeneration int64           `json:"-" yaml:"-"`
}

type ConditionStatus string

type Deployment struct {
	TypeMeta `json:",inline" yaml:",inline"`
	Metadata ObjectMeta     `json:"metadata" yaml:"metadata"`
	Spec     DeploymentSpec `json:"spec" yaml:"spec"`
	Status   Status         `json:"status,omitzero" yaml:"status,omitempty"`
}

type DeploymentHarness struct {
	// Type is the selected harness family, e.g. "claude-code", "codex".
	Type string `json:"type" yaml:"type"`

	// PermissionMode controls the harness tool-permission posture, e.g.
	// "default", "acceptEdits", "bypassPermissions". Empty defaults to
	// "bypassPermissions" for headless harness runtimes (no interactive
	// approval is possible); subject to security review.
	PermissionMode string `json:"permissionMode,omitempty" yaml:"permissionMode,omitempty"`
}

type DeploymentRef struct {
	Namespace string `json:"namespace,omitempty" yaml:"namespace,omitempty"`
	Name      string `json:"name" yaml:"name"`
}

type DeploymentSpec struct {
	TargetRef  ResourceRef `json:"targetRef" yaml:"targetRef"`
	RuntimeRef ResourceRef `json:"runtimeRef" yaml:"runtimeRef"`
	// ModelRef selects the tagged Model for this Deployment. When omitted from
	// a harness Agent Deployment, it defaults to Model/default@latest in the
	// Deployment namespace. It remains optional with no implicit selection for
	// non-harness Agent and MCPServer Deployments. Provider, endpoint, and auth
	// configuration remain on the referenced Model.
	ModelRef     *ModelRef `json:"modelRef,omitempty" yaml:"modelRef,omitempty"`
	DesiredState string    `json:"desiredState,omitempty" yaml:"desiredState,omitempty"`
	// DeploymentRefs declaratively binds this Deployment to other
	// Deployments — e.g. an Agent Deployment binding to the MCPServer
	// Deployments whose status should feed its runtime config. Stored
	// and structurally validated; binding semantics are owned by the
	// kind's reconciler.
	DeploymentRefs []DeploymentRef   `json:"deploymentRefs,omitempty" yaml:"deploymentRefs,omitempty"`
	Env            map[string]string `json:"env,omitempty" yaml:"env,omitempty"`
	// EnvFrom sources environment variables for the deployed workload from
	// references the runtime resolves. Only Secret references are supported
	// for MCPServer deployments. Explicit Env entries win over keys sourced
	// via EnvFrom.
	EnvFrom       []EnvFromSource `json:"envFrom,omitempty" yaml:"envFrom,omitempty"`
	RuntimeConfig map[string]any  `json:"runtimeConfig,omitempty" yaml:"runtimeConfig,omitempty"`
	// Harness selects a compatible harness for Agent deployments and configures
	// rollout-specific harness policy. Omitted for BYO image/source Agent
	// deployments and MCPServer deployments.
	Harness *DeploymentHarness `json:"harness,omitempty" yaml:"harness,omitempty"`
}

type EnvFromSource struct {
	// SecretRef names a Secret whose keys become environment variables in
	// the deployed workload. The Secret is runtime-local (e.g. for Kubernetes,
	// a Secret in the runtime's namespace), not a registry Secret.
	SecretRef *SecretEnvSource `json:"secretRef,omitempty" yaml:"secretRef,omitempty"`
}

type FieldError struct {
	Path  string
	Cause error
}

type FieldErrors []FieldError

type GetterFunc func(ctx context.Context, ref ResourceRef) (Object, error)

type HTTPHeader struct {
	Name  string `json:"name" yaml:"name"`
	Value string `json:"value,omitempty" yaml:"value,omitempty"`
}

type HarnessCompatibility struct {
	// Type is the harness family, e.g. "claude-code", "codex", "opencode".
	Type string `json:"type" yaml:"type"`
}

type HookEntry struct {
	Type string `json:"type" yaml:"type"`

	Command string `json:"command,omitempty" yaml:"command,omitempty"`
	Shell   string `json:"shell,omitempty" yaml:"shell,omitempty"`

	Prompt string `json:"prompt,omitempty" yaml:"prompt,omitempty"`
	Model  string `json:"model,omitempty" yaml:"model,omitempty"`

	URL            string            `json:"url,omitempty" yaml:"url,omitempty"`
	Headers        map[string]string `json:"headers,omitempty" yaml:"headers,omitempty"`
	AllowedEnvVars []string          `json:"allowedEnvVars,omitempty" yaml:"allowedEnvVars,omitempty"`

	Server string          `json:"server,omitempty" yaml:"server,omitempty"`
	Tool   string          `json:"tool,omitempty" yaml:"tool,omitempty"`
	Input  json.RawMessage `json:"input,omitempty" yaml:"input,omitempty"`

	If string `json:"if,omitempty" yaml:"if,omitempty"`
	// Timeout is a pointer so an explicit "timeout": 0 (disable) round-trips
	// losslessly — a float64 with omitempty would silently drop the zero.
	Timeout       *float64 `json:"timeout,omitempty" yaml:"timeout,omitempty"`
	StatusMessage string   `json:"statusMessage,omitempty" yaml:"statusMessage,omitempty"`
	Once          *bool    `json:"once,omitempty" yaml:"once,omitempty"`
	Async         *bool    `json:"async,omitempty" yaml:"async,omitempty"`
	AsyncRewake   *bool    `json:"asyncRewake,omitempty" yaml:"asyncRewake,omitempty"`
}

type HookMatcherGroup struct {
	Matcher string      `json:"matcher,omitempty" yaml:"matcher,omitempty"`
	Hooks   []HookEntry `json:"hooks" yaml:"hooks"`
}

type HooksField struct {
	Path   string
	Events map[string][]HookMatcherGroup
	Raw    json.RawMessage
}

type KindDescriptor struct {
	Kind       string
	SpecSample any
	NewObject  func() any
	Plural     string
	Table      string
	Storage    KindStorage
}

type KindOption func(*KindDescriptor)

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

type KindStorage string

type LSPServerEntry struct {
	Command               string            `json:"command" yaml:"command"`
	Args                  []string          `json:"args,omitempty" yaml:"args,omitempty"`
	ExtensionToLanguage   map[string]string `json:"extensionToLanguage" yaml:"extensionToLanguage"`
	Transport             string            `json:"transport,omitempty" yaml:"transport,omitempty"`
	Env                   map[string]string `json:"env,omitempty" yaml:"env,omitempty"`
	InitializationOptions json.RawMessage   `json:"initializationOptions,omitempty" yaml:"initializationOptions,omitempty"`
	Settings              json.RawMessage   `json:"settings,omitempty" yaml:"settings,omitempty"`
	WorkspaceFolder       string            `json:"workspaceFolder,omitempty" yaml:"workspaceFolder,omitempty"`
	StartupTimeout        *int              `json:"startupTimeout,omitempty" yaml:"startupTimeout,omitempty"`
	MaxRestarts           *int              `json:"maxRestarts,omitempty" yaml:"maxRestarts,omitempty"`
}

type LSPServersField struct {
	Path    string
	Servers map[string]LSPServerEntry
	Raw     json.RawMessage
}

type MCPArgument struct {
	Type  MCPArgumentType `json:"type" yaml:"type"`
	Name  string          `json:"name,omitempty" yaml:"name,omitempty"`
	Value string          `json:"value,omitempty" yaml:"value,omitempty"`
}

type MCPArgumentType string

type MCPKeyValueInput struct {
	Name       string `json:"name" yaml:"name"`
	Value      string `json:"value,omitempty" yaml:"value,omitempty"`
	IsRequired bool   `json:"isRequired,omitempty" yaml:"isRequired,omitempty"`
}

type MCPPackage struct {
	Origin    MCPPackageOrigin  `json:"origin" yaml:"origin"`
	Launch    *MCPPackageLaunch `json:"launch,omitempty" yaml:"launch,omitempty"`
	Transport MCPTransport      `json:"transport" yaml:"transport"`
}

type MCPPackageLaunch struct {
	Command string             `json:"command,omitempty" yaml:"command,omitempty"`
	Args    []MCPArgument      `json:"args,omitempty" yaml:"args,omitempty"`
	Env     []MCPKeyValueInput `json:"env,omitempty" yaml:"env,omitempty"`
}

type MCPPackageOrigin struct {
	Type       MCPPackageOriginType `json:"type" yaml:"type"`
	Identifier string               `json:"identifier" yaml:"identifier"`

	NPM  *MCPPackageOriginNPM  `json:"npm,omitempty"  yaml:"npm,omitempty"`
	PyPI *MCPPackageOriginPyPI `json:"pypi,omitempty" yaml:"pypi,omitempty"`
	OCI  *MCPPackageOriginOCI  `json:"oci,omitempty"  yaml:"oci,omitempty"`
}

type MCPPackageOriginNPM struct {
	Version    string `json:"version" yaml:"version"`
	Mirror     string `json:"mirror,omitempty" yaml:"mirror,omitempty"`
	ServerName string `json:"serverName" yaml:"serverName"`
}

type MCPPackageOriginOCI struct {
	ServerName string `json:"serverName" yaml:"serverName"`
}

type MCPPackageOriginPyPI struct {
	Version    string `json:"version" yaml:"version"`
	Mirror     string `json:"mirror,omitempty" yaml:"mirror,omitempty"`
	ServerName string `json:"serverName" yaml:"serverName"`
}

type MCPPackageOriginType string

type MCPRemote struct {
	Type    string       `json:"type" yaml:"type"`
	URL     string       `json:"url" yaml:"url"`
	Headers []HTTPHeader `json:"headers,omitempty" yaml:"headers,omitempty"`
}

type MCPServer struct {
	TypeMeta `json:",inline" yaml:",inline"`
	Metadata ObjectMeta    `json:"metadata" yaml:"metadata"`
	Spec     MCPServerSpec `json:"spec" yaml:"spec"`
	Status   Status        `json:"status,omitzero" yaml:"status,omitempty"`
}

type MCPServerEntry struct {
	Type    string            `json:"type,omitempty" yaml:"type,omitempty"`
	Command string            `json:"command,omitempty" yaml:"command,omitempty"`
	Args    []string          `json:"args,omitempty" yaml:"args,omitempty"`
	Env     map[string]string `json:"env,omitempty" yaml:"env,omitempty"`

	URL           string            `json:"url,omitempty" yaml:"url,omitempty"`
	Headers       map[string]string `json:"headers,omitempty" yaml:"headers,omitempty"`
	HeadersHelper string            `json:"headersHelper,omitempty" yaml:"headersHelper,omitempty"`
	OAuth         *MCPServerOAuth   `json:"oauth,omitempty" yaml:"oauth,omitempty"`
}

type MCPServerOAuth struct {
	ClientID string `json:"clientId,omitempty" yaml:"clientId,omitempty"`
	// Pointer so an explicit callbackPort:0 round-trips (omitempty would drop it).
	CallbackPort          *int     `json:"callbackPort,omitempty" yaml:"callbackPort,omitempty"`
	AuthServerMetadataURL string   `json:"authServerMetadataUrl,omitempty" yaml:"authServerMetadataUrl,omitempty"`
	Scopes                []string `json:"scopes,omitempty" yaml:"scopes,omitempty"`
}

type MCPServerSource struct {
	// Package is the runnable distribution (stdio binary, container image,
	// npm package, etc.) of this MCP server.
	Package *MCPPackage `json:"package,omitempty" yaml:"package,omitempty"`

	// Repository links to the source code the package was built from.
	Repository *Repository `json:"repository,omitempty" yaml:"repository,omitempty"`
}

type MCPServerSpec struct {
	Title       string `json:"title,omitempty" yaml:"title,omitempty"`
	Description string `json:"description,omitempty" yaml:"description,omitempty"`

	// Source declares where the bundled MCP server comes from — Package (the
	// runnable distribution) and/or Repository (the source code).
	Source *MCPServerSource `json:"source,omitempty" yaml:"source,omitempty"`

	// Remote declares a remote MCP server instead of a bundled one. These are pre-existing
	// MCP servers that the registry does not deploy but can be referenced by Agents.
	Remote *MCPRemote `json:"remote,omitempty" yaml:"remote,omitempty"`
}

type MCPServersField struct {
	Path    string
	Servers map[string]MCPServerEntry
	Raw     json.RawMessage
}

type MCPTransport struct {
	Type string `json:"type" yaml:"type"`                     // "http" | "stdio"
	Port uint16 `json:"port,omitempty" yaml:"port,omitempty"` // http listen port 1-65535 (ignored for stdio)
	Path string `json:"path,omitempty" yaml:"path,omitempty"` // http endpoint path, e.g. "/mcp" (ignored for stdio)
}

type Model struct {
	TypeMeta `json:",inline" yaml:",inline"`
	Metadata ObjectMeta `json:"metadata" yaml:"metadata"`
	Spec     ModelSpec  `json:"spec" yaml:"spec"`
	Status   Status     `json:"status,omitzero" yaml:"status,omitempty"`
}

type ModelAuthConfig struct {
	// Strategy is "runtime" (ambient cloud identity), "secretRef" (key
	// material from a registry Secret), or "passthrough" (inbound bearer
	// token forwarded as the provider key).
	Strategy string `json:"strategy" yaml:"strategy" enum:"runtime,secretRef,passthrough"`
	// SecretRef is required iff Strategy == "secretRef".
	SecretRef *SecretKeyRef `json:"secretRef,omitempty" yaml:"secretRef,omitempty"`
}

type ModelEndpointConfig struct {
	BaseURL string `json:"baseUrl,omitempty" yaml:"baseUrl,omitempty"`
	// Region overrides the model-endpoint region (bedrock); empty means the
	// provider default.
	Region string          `json:"region,omitempty" yaml:"region,omitempty"`
	TLS    *ModelTLSConfig `json:"tls,omitempty" yaml:"tls,omitempty"`
}

type ModelRef struct {
	Namespace string `json:"namespace,omitempty" yaml:"namespace,omitempty"`
	Name      string `json:"name" yaml:"name"`
	Tag       string `json:"tag,omitempty" yaml:"tag,omitempty"`
}

type ModelSpec struct {
	// Catalog display metadata.
	Title       string `json:"title,omitempty" yaml:"title,omitempty"`
	Description string `json:"description,omitempty" yaml:"description,omitempty"`

	// Provider family. Currently only "bedrock" is supported.
	Provider string `json:"provider" yaml:"provider" enum:"bedrock"`

	// Model is the provider-scoped model identifier, e.g.
	// "us.anthropic.claude-opus-4-8".
	Model string `json:"model" yaml:"model"`

	// Auth is how the platform authenticates to the provider. Omitted means
	// the provider default: ambient runtime identity for Bedrock.
	Auth *ModelAuthConfig `json:"auth,omitempty" yaml:"auth,omitempty"`

	// Endpoint overrides how the provider is reached. Omitted means
	// provider defaults.
	Endpoint *ModelEndpointConfig `json:"endpoint,omitempty" yaml:"endpoint,omitempty"`
}

type ModelTLSConfig struct {
	// CACertSecretRef names CA material for private gateways.
	CACertSecretRef *SecretKeyRef `json:"caCertSecretRef,omitempty" yaml:"caCertSecretRef,omitempty"`
	// DisableVerify is for dev/test only.
	DisableVerify bool `json:"disableVerify,omitempty" yaml:"disableVerify,omitempty"`
}

type MonitorEntry struct {
	Name        string `json:"name" yaml:"name"`
	Command     string `json:"command" yaml:"command"`
	Description string `json:"description" yaml:"description"`
	When        string `json:"when,omitempty" yaml:"when,omitempty"`
}

type MonitorsField struct {
	Path    string
	Entries []MonitorEntry
}

type Object interface {
	GetAPIVersion() string
	GetKind() string
	SetTypeMeta(TypeMeta)
	GetMetadata() *ObjectMeta
	SetMetadata(ObjectMeta)
	// MarshalSpec returns the JSON encoding of this object's Spec field.
	MarshalSpec() (json.RawMessage, error)
	// UnmarshalSpec decodes the given JSON bytes into this object's Spec field.
	UnmarshalSpec(data json.RawMessage) error
	// MarshalStatus returns the JSON encoding of this object's Status field.
	// Empty-status objects return `nil, nil`.
	MarshalStatus() (json.RawMessage, error)
	// UnmarshalStatus decodes the given JSON bytes into this object's Status
	// field. Empty/nil input resets the status to its zero value.
	UnmarshalStatus(data json.RawMessage) error
}

type ObjectMeta struct {
	Namespace   string            `json:"namespace,omitempty" yaml:"namespace,omitempty"`
	Name        string            `json:"name" yaml:"name"`
	UID         string            `json:"uid,omitempty" yaml:"uid,omitempty"`
	Labels      map[string]string `json:"labels,omitempty" yaml:"labels,omitempty"`
	Annotations map[string]string `json:"annotations,omitempty" yaml:"annotations,omitempty"`

	// Tag is the user-visible identity for content-registry kinds
	// (Agent, MCPServer, Model, Plugin, Skill, Prompt).
	Tag string `json:"tag,omitempty" yaml:"tag,omitempty"`

	// Generation is server-managed and internal. Populated from the DB row for
	// internal Go consumers (coordinators, status reconcilers); hidden from the
	// wire.
	Generation int64     `json:"-" yaml:"-"`
	CreatedAt  time.Time `json:"createdAt,omitzero" yaml:"createdAt,omitempty"`
	UpdatedAt  time.Time `json:"updatedAt,omitzero" yaml:"updatedAt,omitempty"`

	// DeletionTimestamp is set by the Store when Delete is called. A non-nil
	// DeletionTimestamp means the object is terminating; the row stays
	// observable via Get until the GC pass purges it. Clients MUST NOT
	// set this on apply.
	DeletionTimestamp *time.Time `json:"deletionTimestamp,omitempty" yaml:"deletionTimestamp,omitempty"`
}

type PathOrPaths struct {
	Values   []string
	WasArray bool
}

type Plugin struct {
	TypeMeta `json:",inline" yaml:",inline"`
	Metadata ObjectMeta   `json:"metadata" yaml:"metadata"`
	Spec     PluginSpec   `json:"spec" yaml:"spec"`
	Status   PluginStatus `json:"status,omitzero" yaml:"status,omitempty"`
}

type PluginAuthor struct {
	Name  string `json:"name" yaml:"name"`
	Email string `json:"email,omitempty" yaml:"email,omitempty"`
	URL   string `json:"url,omitempty" yaml:"url,omitempty"`
}

type PluginChannel struct {
	Server      string                           `json:"server" yaml:"server"`
	DisplayName string                           `json:"displayName,omitempty" yaml:"displayName,omitempty"`
	UserConfig  map[string]PluginUserConfigField `json:"userConfig,omitempty" yaml:"userConfig,omitempty"`
}

type PluginDependency struct {
	Ref         string `json:"-" yaml:"-"`
	Name        string `json:"name,omitempty" yaml:"name,omitempty"`
	Marketplace string `json:"marketplace,omitempty" yaml:"marketplace,omitempty"`
	Version     string `json:"version,omitempty" yaml:"version,omitempty"`
}

type PluginExperimental struct {
	Themes   *PathOrPaths   `json:"themes,omitempty" yaml:"themes,omitempty"`
	Monitors *MonitorsField `json:"monitors,omitempty" yaml:"monitors,omitempty"`
}

type PluginHook struct {
	// Event is the lifecycle event, e.g. "PreToolUse", "PostToolUse",
	// "SessionStart".
	Event string `json:"event" yaml:"event"`
	// Type is the handler kind: command|http|mcp_tool|prompt|agent.
	Type string `json:"type,omitempty" yaml:"type,omitempty"`
}

type PluginInventory struct {
	Skills   []PluginSkill `json:"skills,omitempty" yaml:"skills,omitempty"`
	Commands []string      `json:"commands,omitempty" yaml:"commands,omitempty"`
	// Agents are sub-agent names; sub-agents are markdown prompt files in the
	// bundle, not manifest entries.
	Agents []string `json:"agents,omitempty" yaml:"agents,omitempty"`
	// Hooks are lifecycle hooks the bundle registers (arbitrary code).
	Hooks      []PluginHook `json:"hooks,omitempty" yaml:"hooks,omitempty"`
	MCPServers []string     `json:"mcpServers,omitempty" yaml:"mcpServers,omitempty"`
	// Executables are bin/ entries the bundle ships (arbitrary code).
	Executables []string `json:"executables,omitempty" yaml:"executables,omitempty"`
}

type PluginManifest struct {
	Schema      string   `json:"$schema,omitempty" yaml:"$schema,omitempty"`
	Name        string   `json:"name" yaml:"name"`
	Version     string   `json:"version,omitempty" yaml:"version,omitempty"`
	Description string   `json:"description,omitempty" yaml:"description,omitempty"`
	Homepage    string   `json:"homepage,omitempty" yaml:"homepage,omitempty"`
	Repository  string   `json:"repository,omitempty" yaml:"repository,omitempty"`
	License     string   `json:"license,omitempty" yaml:"license,omitempty"`
	Keywords    []string `json:"keywords,omitempty" yaml:"keywords,omitempty"`

	Author *PluginAuthor `json:"author,omitempty" yaml:"author,omitempty"`

	// Settings is an opaque allowlisted settings-merge object (schema models it
	// as open additionalProperties), held raw to round-trip losslessly.
	Settings json.RawMessage `json:"settings,omitempty" yaml:"settings,omitempty"`

	Dependencies []PluginDependency `json:"dependencies,omitempty" yaml:"dependencies,omitempty"`

	// Component path overrides — string|array|object unions (see types below).
	Commands     *CommandsField   `json:"commands,omitempty" yaml:"commands,omitempty"`
	Agents       *PathOrPaths     `json:"agents,omitempty" yaml:"agents,omitempty"`
	Skills       *PathOrPaths     `json:"skills,omitempty" yaml:"skills,omitempty"`
	OutputStyles *PathOrPaths     `json:"outputStyles,omitempty" yaml:"outputStyles,omitempty"`
	Hooks        *HooksField      `json:"hooks,omitempty" yaml:"hooks,omitempty"`
	MCPServers   *MCPServersField `json:"mcpServers,omitempty" yaml:"mcpServers,omitempty"`
	LSPServers   *LSPServersField `json:"lspServers,omitempty" yaml:"lspServers,omitempty"`

	UserConfig map[string]PluginUserConfigField `json:"userConfig,omitempty" yaml:"userConfig,omitempty"`
	Channels   []PluginChannel                  `json:"channels,omitempty" yaml:"channels,omitempty"`

	// Themes/Monitors are the schemastore top-level placement; Experimental is
	// the docs-preferred nesting. Both are modeled so we re-emit whichever the
	// source used.
	Themes       *PathOrPaths        `json:"themes,omitempty" yaml:"themes,omitempty"`
	Monitors     *MonitorsField      `json:"monitors,omitempty" yaml:"monitors,omitempty"`
	Experimental *PluginExperimental `json:"experimental,omitempty" yaml:"experimental,omitempty"`

	// DisplayName / DefaultEnabled are docs-only (not in the schemastore schema)
	// but Claude loads them; modeled so real data isn't dropped.
	DisplayName    string `json:"displayName,omitempty" yaml:"displayName,omitempty"`
	DefaultEnabled *bool  `json:"defaultEnabled,omitempty" yaml:"defaultEnabled,omitempty"`

	// Extras captures any top-level key not modeled above (Codex interface/apps,
	// forward-compat keys) so the manifest is a true cross-harness superset.
	// Spliced in/out by (Un)MarshalJSON; never carries a known key.
	Extras map[string]json.RawMessage `json:"-" yaml:"-"`
}

type PluginResolvedSource struct {
	Type PluginSourceType `json:"type" yaml:"type"`
	// Commit is the resolved full git commit SHA (Type=git).
	Commit string `json:"commit,omitempty" yaml:"commit,omitempty"`
	// Digest is the resolved OCI digest, e.g. "sha256:…" (Type=oci; future).
	Digest string `json:"digest,omitempty" yaml:"digest,omitempty"`
}

type PluginSkill struct {
	Name        string `json:"name" yaml:"name"`
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
}

type PluginSource struct {
	Type PluginSourceType `json:"type" yaml:"type"`
	Git  *PluginSourceGit `json:"git,omitempty" yaml:"git,omitempty"`
	OCI  *PluginSourceOCI `json:"oci,omitempty" yaml:"oci,omitempty"`
}

type PluginSourceGit struct {
	Repository *Repository `json:"repository" yaml:"repository"`
}

type PluginSourceOCI struct {
	Reference string `json:"reference" yaml:"reference"`
}

type PluginSourceType string

type PluginSpec struct {
	Title       string `json:"title,omitempty" yaml:"title,omitempty"`
	Description string `json:"description,omitempty" yaml:"description,omitempty"`

	// Harnesses lists the harness formats this bundle carries native manifests
	// for (e.g. "claude-code", "codex"). It is informational in this phase;
	// deploy-time adapters decide which harnesses they can consume.
	Harnesses []string `json:"harnesses,omitempty" yaml:"harnesses,omitempty"`

	// Source is where the bundle is ingested from, pinned (git commit / OCI
	// digest) so a published tag is reproducible.
	Source *PluginSource `json:"source,omitempty" yaml:"source,omitempty"`
}

type PluginStatus struct {
	Status `json:",inline" yaml:",inline"`

	// ResolvedSource is the controller's immutable pin of the user's source
	// pointer (the concrete commit/digest the source resolved to).
	ResolvedSource *PluginResolvedSource `json:"resolvedSource,omitempty" yaml:"resolvedSource,omitempty"`
	// Manifest is the canonical typed plugin.json parsed from the source.
	Manifest *PluginManifest `json:"manifest,omitempty" yaml:"manifest,omitempty"`
	// Inventory is the server-derived risk surface / search index.
	Inventory *PluginInventory `json:"inventory,omitempty" yaml:"inventory,omitempty"`
}

type PluginUserConfigField struct {
	Type        string          `json:"type" yaml:"type"`
	Title       string          `json:"title" yaml:"title"`
	Description string          `json:"description" yaml:"description"`
	Required    *bool           `json:"required,omitempty" yaml:"required,omitempty"`
	Default     json.RawMessage `json:"default,omitempty" yaml:"default,omitempty"`
	Multiple    *bool           `json:"multiple,omitempty" yaml:"multiple,omitempty"`
	Sensitive   *bool           `json:"sensitive,omitempty" yaml:"sensitive,omitempty"`
	Min         *float64        `json:"min,omitempty" yaml:"min,omitempty"`
	Max         *float64        `json:"max,omitempty" yaml:"max,omitempty"`
}

type Prompt struct {
	TypeMeta `json:",inline" yaml:",inline"`
	Metadata ObjectMeta `json:"metadata" yaml:"metadata"`
	Spec     PromptSpec `json:"spec" yaml:"spec"`
	Status   Status     `json:"status,omitzero" yaml:"status,omitempty"`
}

type PromptSpec struct {
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
	Content     string `json:"content,omitempty" yaml:"content,omitempty"`
}

type RawObject struct {
	TypeMeta `json:",inline" yaml:",inline"`
	Metadata ObjectMeta      `json:"metadata" yaml:"metadata"`
	Spec     json.RawMessage `json:"spec,omitempty" yaml:"spec,omitempty"`
	Status   json.RawMessage `json:"status,omitempty" yaml:"status,omitempty"`
}

type RefResolver interface {
	ResolveRefs(ctx context.Context, resolver ResolverFunc) error
}

type RegistryValidatable interface {
	ValidateRegistries(ctx context.Context, v RegistryValidatorFunc) error
}

type RegistryValidatorFunc func(ctx context.Context, origin MCPPackageOrigin, expectedServerName string) error

type Repository struct {
	URL       string `json:"url,omitempty" yaml:"url,omitempty"`
	Branch    string `json:"branch,omitempty" yaml:"branch,omitempty"`
	Commit    string `json:"commit,omitempty" yaml:"commit,omitempty"`
	Subfolder string `json:"subfolder,omitempty" yaml:"subfolder,omitempty"`
}

type ResolverFunc func(ctx context.Context, ref ResourceRef) error

type ResourceRef struct {
	Kind      string `json:"kind" yaml:"kind"`
	Namespace string `json:"namespace,omitempty" yaml:"namespace,omitempty"`
	Name      string `json:"name" yaml:"name"`
	Tag       string `json:"tag,omitempty" yaml:"tag,omitempty"`
}

type Runtime struct {
	TypeMeta `json:",inline" yaml:",inline"`
	Metadata ObjectMeta  `json:"metadata" yaml:"metadata"`
	Spec     RuntimeSpec `json:"spec" yaml:"spec"`
	Status   Status      `json:"status,omitzero" yaml:"status,omitempty"`
}

type RuntimeSpec struct {
	Type              string         `json:"type" yaml:"type"`
	Config            map[string]any `json:"config,omitempty" yaml:"config,omitempty"`
	TelemetryEndpoint string         `json:"telemetryEndpoint,omitempty" yaml:"telemetryEndpoint,omitempty"`
}

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

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

type SecretKeyRef struct {
	Namespace string `json:"namespace,omitempty" yaml:"namespace,omitempty"`
	Name      string `json:"name" yaml:"name"`
	Key       string `json:"key,omitempty" yaml:"key,omitempty"`
}

type Skill struct {
	TypeMeta `json:",inline" yaml:",inline"`
	Metadata ObjectMeta  `json:"metadata" yaml:"metadata"`
	Spec     SkillSpec   `json:"spec" yaml:"spec"`
	Status   SkillStatus `json:"status,omitzero" yaml:"status,omitempty"`
}

type SkillResolvedSource struct {
	// Commit is the resolved full git commit SHA.
	Commit string `json:"commit,omitempty" yaml:"commit,omitempty"`
}

type SkillSource struct {
	Repository *Repository `json:"repository,omitempty" yaml:"repository,omitempty"`
}

type SkillSpec struct {
	Title       string       `json:"title,omitempty" yaml:"title,omitempty"`
	Description string       `json:"description,omitempty" yaml:"description,omitempty"`
	Source      *SkillSource `json:"source,omitempty" yaml:"source,omitempty"`
}

type SkillStatus struct {
	Status `json:",inline" yaml:",inline"`

	// ResolvedSource is the controller's immutable pin of the skill's git
	// source (the concrete commit the source ref resolved to).
	ResolvedSource *SkillResolvedSource `json:"resolvedSource,omitempty" yaml:"resolvedSource,omitempty"`
}

type Status struct {
	ObservedGeneration int64       `json:"-" yaml:"-"`
	Conditions         []Condition `json:"conditions,omitempty" yaml:"conditions,omitempty"`

	// Details is an opaque JSON object populated by controllers and runtime
	// adapters that need to surface structured state beyond what Conditions can
	// express. Each writer owns its own top-level key inside Details; consumers
	// parse only the keys they care about. Empty when no writer has stored
	// details.
	//
	// Use SetDetailsKey / GetDetailsKey to merge or read keys without clobbering
	// other adapters' state.
	Details json.RawMessage `json:"details,omitempty" yaml:"details,omitempty"`
}

type StructuralValidator interface {
	Validate() error
}

type TypeMeta struct {
	APIVersion string `json:"apiVersion" yaml:"apiVersion"`
	Kind       string `json:"kind" yaml:"kind"`
}