docent

type Command struct {
	// Name is the command's short name (the last path segment).
	Name string `json:"name"`

	// Path is the space-separated sequence of names from the root to this
	// command, e.g. "issue create".
	Path string `json:"path"`

	// Description is the short, one-line description of the command.
	Description string `json:"description,omitempty"`

	// Aliases lists alternative names the command answers to, sorted for
	// determinism. An agent that reads documentation mentioning an alias can
	// recognize it as this command.
	Aliases []string `json:"aliases,omitempty"`

	// Deprecated carries the framework's deprecation message when the
	// command is deprecated, empty otherwise. Agents should prefer the
	// replacement the message names instead of invoking this command.
	Deprecated string `json:"deprecated,omitempty"`

	// ReadOnly indicates the command performs no writes. Adapters set this
	// from framework-specific metadata; when unavailable it defaults to false.
	ReadOnly bool `json:"read_only,omitempty"`

	// Hidden indicates the command is not shown in help output.
	Hidden bool `json:"hidden,omitempty"`

	// Flags contains all flags available on this command, sorted by Name.
	Flags []Flag `json:"flags,omitempty"`

	// FlagGroups contains mutual-exclusion and required-together relations
	// among the command's flags, sorted for determinism.
	FlagGroups []FlagGroup `json:"flag_groups,omitempty"`

	// Extensions carries host-owned structured metadata — the slot for
	// everything the neutral IR deliberately does not model: auth
	// requirements, environment variables, exit codes, output contracts,
	// per-command examples. On the root command it describes the tool; on
	// any other node, that command. One documented exception to host
	// ownership: when Config.ContractVersion is set, the cobra adapter's
	// schema command stamps a "contract_version" entry onto the emitted
	// root at emission time, overwriting a host entry of that name — the
	// stored tree is never touched. Values must be JSON-marshalable;
	// emission sorts keys, and every API boundary deep-copies the map like
	// the schema fields.
	Extensions map[string]any `json:"extensions,omitempty"`

	// InputSchema is an optional JSON Schema object describing the command's
	// structured input. Nil when the framework does not supply schema metadata.
	InputSchema map[string]any `json:"input_schema,omitempty"`

	// HasInputSchema marks that an input schema exists for this command
	// when the embedded body has been omitted from the emission. Set by
	// StripShapes, never by adapters or hosts directly: a full-tree reader
	// is routing and needs only the fact that a shape exists; the body is
	// one --path call away.
	HasInputSchema bool `json:"has_input_schema,omitempty"`

	// OutputSchema is an optional JSON Schema object describing the command's
	// structured output. Nil when the framework does not supply schema metadata.
	OutputSchema map[string]any `json:"output_schema,omitempty"`

	// HasOutputSchema is the output-side counterpart of HasInputSchema.
	HasOutputSchema bool `json:"has_output_schema,omitempty"`

	// Children contains this command's direct subcommands, sorted by Name.
	Children []Command `json:"children,omitempty"`

	// Defs holds shared JSON Schema bodies hoisted out of the tree's
	// input/output schemas, keyed by definition name. Populated by
	// PoolShapes on the emitted root — the bodies it replaces become
	// {"$ref": "#/$defs/<name>"} objects, and the pointer form resolves
	// against the emission document, so the key is emitted as "$defs" per
	// JSON Schema convention. Meaningful only on the root of an emission.
	Defs map[string]any `json:"$defs,omitempty"`
}

type CommandSchemas struct {
	// Input is the JSON Schema object describing the command's structured input.
	// Nil when no input schema is registered for this command path.
	Input map[string]any

	// Output is the JSON Schema object describing the command's structured output.
	// Nil when no output schema is registered for this command path.
	Output map[string]any
}

type Config struct {
	// Guides is the guide set to serve. Nil means no guides are available.
	Guides *GuideSet

	// Command is the framework-neutral schema IR for the host's command tree.
	// Hosts build this from an adapter (e.g. cobra.Tree(root)) before mounting
	// the agent command group, so the schema represents the host CLI without
	// the agent commands themselves.
	Command Command

	// Out is the host-supplied destination for all emitted output. When nil,
	// adapter commands write to their framework's output channel (e.g.
	// cobra's cmd.OutOrStdout()). docent itself never writes to stdout.
	Out io.Writer

	// ContractVersion is the host's own agent-contract version — the number
	// a host bumps when its envelope, exit codes, or output shapes change,
	// distinct from docent's guide StandardVersion. When set, adapters stamp
	// it on discovery surfaces: the schema root gains a "contract_version"
	// extensions entry and the guide index gains a contract_version line, so
	// an agent can pin behavior to the contract it read. Empty omits the
	// stamp everywhere. The value is emitted verbatim into a single
	// "key: value" index line — keep it one line with no colons; a plain
	// semver string always qualifies. A value containing a newline,
	// carriage return, or colon fails index emission with an error
	// (export.ErrInvalidContractVersion) rather than corrupting the
	// line-oriented shape.
	ContractVersion string
}

type Flag struct {
	// Name is the long flag name without leading dashes.
	Name string `json:"name"`

	// Shorthand is the single-character flag alias, or empty if none.
	Shorthand string `json:"shorthand,omitempty"`

	// Description is the flag's usage string.
	Description string `json:"description,omitempty"`

	// Type is the value type as reported by the flag framework (e.g. "string",
	// "bool", "int", "stringSlice").
	Type string `json:"type"`

	// Default is the default value as a string. Empty means no default or the
	// zero value for the type.
	Default string `json:"default,omitempty"`

	// Enum lists the allowed values when the flag type restricts to a finite
	// set. Nil when the flag accepts arbitrary values.
	Enum []string `json:"enum,omitempty"`

	// Required is true when the flag must be set on every invocation.
	Required bool `json:"required,omitempty"`

	// Persistent is true when the flag is defined on this command and
	// available to every descendant. Each flag appears exactly once in the
	// tree — on the command that defines it — so inherited flags are not
	// repeated per command; a consumer resolves a command's full flag
	// surface by walking its ancestors' persistent flags. When a command's
	// local flag shares a name with an ancestor's persistent flag, the
	// nearest definition wins for that command.
	Persistent bool `json:"persistent,omitempty"`

	// Extensions carries structured per-flag metadata the neutral IR does
	// not model — placeholders, value hints, display grouping. Like
	// Command.Extensions the slot is host-owned, but adapters may contribute
	// documented, namespaced entries: the cobra adapter surfaces a gechr/clib
	// extras annotation under the "clib" key (with its enum field omitted —
	// that is hoisted to Enum). Values must be JSON-marshalable; emission
	// sorts keys, and every API boundary deep-copies the map.
	Extensions map[string]any `json:"extensions,omitempty"`
}

type FlagGroup struct {
	// Kind is the relation type: mutually_exclusive, required_together, or
	// one_required.
	Kind FlagGroupKind `json:"kind"`

	// Flags is the sorted list of flag names in the group.
	Flags []string `json:"flags"`
}

type FlagGroupKind string

type Guide struct {
	// Slug is the unique identifier derived from the filename.
	Slug string

	// Title is the human-readable name of the guide.
	Title string

	// Description is a short summary for index views.
	Description string

	// WhenToUse describes the conditions under which an agent should consult this guide.
	WhenToUse string

	// Commands lists the CLI command paths relevant to this guide.
	Commands []string

	// License names the license applied to exported skills built from this
	// guide, or references a bundled license file. Optional; emitted in
	// skill frontmatter when present.
	License string

	// Compatibility states environment requirements for exported skills
	// (intended product, system packages, network access). Optional; the
	// Agent Skills spec caps it at MaxSkillCompatibility characters.
	Compatibility string

	// Metadata carries additional string key-value properties for exported
	// skill frontmatter — the spec's slot for anything it does not define.
	// Optional; emitted with sorted keys for determinism.
	Metadata map[string]string

	// AllowedTools lists tools pre-approved for exported skills (the spec's
	// experimental allowed-tools field). Optional; emitted space-separated.
	AllowedTools []string

	// Aliases lists alternative names Get resolves to this guide — typically
	// the names a guide carried before a rename, so agents and scripts that
	// memorized them keep working. Aliases are not held to the slug charset
	// (legacy names are the point) but must be unique across the set and
	// must not shadow any slug.
	Aliases []string

	// Order is the optional sparse-integer for canonical ordering. Nil means
	// the guide has no explicit order and sorts alphabetically after ordered guides.
	Order *int

	// Sections contains the guide body in its required six-section shape,
	// in the order they appear in the file.
	Sections []Section

	// Raw holds the complete original file bytes, including frontmatter.
	Raw []byte
}

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

type SchemaRegistry map[string]CommandSchemas

type Section struct {
	// Heading is the bare heading text without the leading "## ".
	Heading string

	// Body is the content that follows the heading, up to the next heading
	// or end of file, with trailing newlines stripped. Leading blank lines
	// and other trailing whitespace (spaces, tabs) are preserved verbatim.
	// Empty bodies are valid per the standard.
	Body string
}

type ValidationError struct {
	// File is the guide filename or identifier where the violation was found.
	File string

	// Message describes the specific violation in human-readable form.
	Message string

	// Err is the sentinel that classifies the failure class.
	Err error
}