module

type Document struct {
	Scope string
	Path  string
	Body  []byte
}

type Documented interface {
	Documents() []Document
}

type Module interface {
	Name() string
	Short() string
	Command(rt *Runtime) (*cobra.Command, error)
	Describe() ModuleInfo

	// Reference returns the module's AI-agent reference document —
	// every command it owns, with usage, flags and worked examples.
	// `pgedge llms <name>` prints it.
	//
	// It is on the interface rather than in a map somewhere because the
	// reference used to be one 163 KB llms-full.txt covering every
	// module, which cost an agent roughly 40k tokens to look up a
	// single flag and made module scope something the doc gates had to
	// INFER, from "## Module:" headings and a hardcoded path
	// special-case. Splitting it per module makes the file the scope,
	// and putting it here makes a module self-contained: its command
	// tree and its documentation arrive together, and a new module
	// cannot be registered while quietly forgetting to document
	// itself. A central map would work today and would recreate the
	// monolith by degrees.
	//
	// Return nil if the module ships no reference, and report
	// ProvidesLLMS false from Describe() to match.
	Reference() []byte
}

type ModuleInfo struct {
	Name            string
	Short           string
	Version         string
	ContractVersion string // RESERVED — empty in-process, no enforcement

	// ProvidesLLMS reports whether Reference() returns a reference
	// document. `pgedge llms` uses it to build its routing table, so a
	// module that ships no reference is simply not offered rather than
	// offered and empty.
	ProvidesLLMS bool
}

type Runtime struct {
	Config  *config.Config
	Profile string

	// ProfileExplicit reports that the operator named a profile on
	// this invocation — cobra parsed a --profile token AND it carried
	// a value. internal/cli.setupRuntime sets it from the executing
	// command's own flag set; the pre-cobra argv peek it once used is
	// long gone (#120, #153).
	//
	// An empty --profile never reaches this field: setupRuntime rejects
	// it as a usage error first (#246). The value test in that
	// assignment is therefore unreachable today, and is kept only so
	// this field stays correct if the rejection is ever narrowed —
	// exempting the repair commands is the obvious candidate. An empty
	// value names no profile, so Profile would come from
	// current_profile, and calling that explicit would shut the #150
	// repair carve-out in cli.GuardProfile, this field's only reader:
	// `profile use` repairs a broken current_profile, and it would have
	// been refused in the name of a value the operator never typed.
	ProfileExplicit bool

	Output  *output.Renderer
	Stdin   io.Reader
	Stdout  io.Writer
	Stderr  io.Writer
	Verbose bool
	Debug   bool

	// DryRun is non-nil when --dry-run is active, and is where a
	// stopped write and the checks that passed before it are recorded.
	//
	// One field rather than a bool beside a recorder, so there is no
	// "enabled with nowhere to record" state to get wrong. Every method
	// on it tolerates a nil receiver, which is what lets check sites
	// call rt.DryRun.Pass unconditionally instead of each guarding on a
	// mode flag.
	DryRun *dryrun.Run

	// Keychain is the OS credential store. nil means unavailable, which
	// is what every test Runtime gets, so no test reaches the real one.
	Keychain keychain.Store
}