reference

type API struct {
	BasePath string  `json:"base_path"`
	Auth     []Auth  `json:"auth"`
	Routes   []Route `json:"routes"`
}

type AdapterCategory struct {
	Category api.Category   `json:"category"`
	Kinds    []api.KindInfo `json:"kinds"`
}

type AdaptersData struct {
	Categories []AdapterCategory `json:"categories"`
}

type Auth struct {
	Name        string `json:"name"`
	How         string `json:"how"`
	Description string `json:"description"`
}

type CLICommand struct {
	Path           string    `json:"path"`
	Use            string    `json:"use"`
	Short          string    `json:"short"`
	Long           string    `json:"long"`
	Example        string    `json:"example"`
	Aliases        []string  `json:"aliases"`
	Hidden         bool      `json:"hidden"`
	Deprecated     string    `json:"deprecated"`
	Flags          []CLIFlag `json:"flags"`
	InheritedFlags []CLIFlag `json:"inherited_flags"`
	Subcommands    []string  `json:"subcommands"`
}

type CLIData struct {
	Commands []CLICommand `json:"commands"`
}

type CLIFlag struct {
	Name      string `json:"name"`
	Shorthand string `json:"shorthand"`
	Type      string `json:"type"`
	Default   string `json:"default"`
	Usage     string `json:"usage"`
	Required  bool   `json:"required"`
}

type CodeExample struct {
	Language string `json:"language"`
	Code     string `json:"code"`
}

type Command struct {
	Name     string    `json:"name"`
	Use      string    `json:"use"`
	Summary  string    `json:"summary"`
	Details  string    `json:"details,omitempty"`
	Flags    []Flag    `json:"flags,omitempty"`
	Children []Command `json:"children,omitempty"`
}

type ConfigData struct {
	Settings []config.SettingDoc `json:"settings"`
}

type Connect struct {
	ServerEnv string `json:"server_env"`
	TokenEnv  string `json:"token_env"`
	LoginCmd  string `json:"login_cmd"`
	MCPCmd    string `json:"mcp_cmd"`

	// MCPPath is where Pando serves MCP itself (R-413).
	MCPPath string `json:"mcp_path"`
}

type Document struct {
	API     API            `json:"api"`
	CLI     []Command      `json:"cli"`
	MCP     []mcp.ToolDoc  `json:"mcp"`
	Errors  []errs.CodeDoc `json:"errors"`
	Events  []events.Def   `json:"events"`
	Connect Connect        `json:"connect"`
	Install Install        `json:"install"`
}

type ErrorDoc struct {
	Code    errs.Code `json:"code"`
	Status  int       `json:"status,omitempty"`
	Meaning string    `json:"meaning"`
}

type ErrorsData struct {
	Errors []ErrorDoc `json:"errors"`
}

type EventDoc struct {
	Type        string         `json:"type"`
	Description string         `json:"description"`
	Scope       events.Scope   `json:"scope"`
	Source      events.Source  `json:"source"`
	Fields      []events.Field `json:"fields"`
}

type EventsData struct {
	EventsGuide
	Events []EventDoc `json:"events"`
}

type EventsGuide struct {
	Subscribing string       `json:"subscribing"`
	Matching    string       `json:"matching"`
	Webhook     WebhookGuide `json:"webhook"`

	// DataNote is what every audit-sourced event's data also carries.
	DataNote string `json:"data_note"`
}

type Flag struct {
	Name        string `json:"name"`
	Shorthand   string `json:"shorthand,omitempty"`
	Description string `json:"description"`
	Default     string `json:"default,omitempty"`
}

type Install struct {
	// Repo is where releases are published.
	Repo string `json:"repo"`
	// Module is the `go install` path.
	Module string `json:"module"`
	// Homebrew is the cask, tap included.
	Homebrew string `json:"homebrew"`
	// Packages are the Linux package formats each release attaches.
	Packages []string `json:"packages"`
	// Archive is how a tarball is named, with the parts a person substitutes.
	Archive string `json:"archive"`
	// WindowsArchive is how Windows's zip is named. A zip rather than a
	// tarball, holding pando.exe.
	WindowsArchive string `json:"windows_archive"`
	// Package is how a Linux package is named. Same shape as Archive, so one
	// download line covers every format.
	Package string `json:"package"`
	// Download is where a release's files are, with the version substituted.
	Download string `json:"download"`
	// Platforms are the os/arch pairs built.
	Platforms []string `json:"platforms"`
	// InContainer runs the copy already inside a Compose installation, for
	// somebody who would rather install nothing.
	InContainer string `json:"in_container"`
}

type MCPData struct {
	Tools []MCPTool `json:"tools"`
}

type MCPTool struct {
	Name        string         `json:"name"`
	Description string         `json:"description"`
	InputSchema map[string]any `json:"input_schema"`
}

type Route struct {
	Method  string `json:"method"`
	Path    string `json:"path"`
	Group   string `json:"group"`
	Title   string `json:"title"`
	Summary string `json:"summary"`
	Verb    string `json:"verb,omitempty"`
	Public  bool   `json:"public,omitempty"`
}

type WebhookGuide struct {
	Intro            string          `json:"intro"`
	BodyExample      json.RawMessage `json:"body_example"`
	Notes            string          `json:"notes"`
	Headers          []WebhookHeader `json:"headers"`
	Verifying        string          `json:"verifying"`
	Examples         []CodeExample   `json:"examples"`
	Retries          string          `json:"retries"`
	PrivateAddresses string          `json:"private_addresses"`
	Shaping          string          `json:"shaping"`
	TemplateExample  string          `json:"template_example"`
	TemplateNotes    string          `json:"template_notes"`
}

type WebhookHeader struct {
	Name    string `json:"name"`
	Meaning string `json:"meaning"`
}