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 index page, which
	// `pgedge llms <name>` prints; per-resource pages come from
	// Documents(). It is on the interface rather than in a central map
	// so a module's command tree and its documentation arrive together,
	// and each module's file is its own scope for the doc gates.
	//
	// 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 document, so
	// `pgedge llms` leaves a module without one out of its routing
	// table rather than offering an empty page.
	ProvidesLLMS bool
}

type Runtime struct {
	Config  *config.Config
	Profile string

	// ProfileExplicit reports that --profile was given a non-empty
	// value on this invocation. cli.GuardProfile's `profile use` repair
	// carve-out and starfleet's env-credential conflict check read it;
	// cli.setupRuntime sets it and says why the value test stays.
	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. One field rather than
	// a bool beside a recorder, so "enabled with nowhere to record"
	// cannot happen.
	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
}