surface

type Dialect interface {
	// Key returns the wire identifier for this surface ("mcp", "cli").
	Key() string

	// ExecuteRef returns an inline reference to the Python execution
	// entrypoint, e.g. "`execute_python`" or "`panda execute`".
	ExecuteRef() string

	// PythonBlock renders python source as a runnable fenced block in
	// this surface's dialect.
	PythonBlock(code string) string

	// PythonBlockInSession renders python source as a runnable fenced
	// block that resumes an existing sandbox session.
	PythonBlockInSession(code string) string

	// SessionHint says how a reader on this surface reuses a sandbox
	// session between executions.
	SessionHint() string

	// SearchExamples returns an inline examples-search invocation scoped
	// to a dataset.
	SearchExamples(dataset, topic string) string

	// ResourceRef returns an inline reference for reading the given
	// resource URI on this surface.
	ResourceRef(uri string) string

	// PythonDocsRef returns a reference to the Python API docs for the
	// given topic.
	PythonDocsRef(topic string) string

	// GettingStartedIntro returns the surface's onboarding workflow
	// section for the getting-started guide.
	GettingStartedIntro() string

	// DiscoveryGuide renders how readers on this surface discover
	// capabilities, given the currently registered tools and resources.
	DiscoveryGuide(d Discovery) string
}

type Discovery struct {
	Tools     []Item
	Resources []Item
	Templates []Item
}

type Item struct {
	Name        string
	Description string
}