diff --git a/README.md b/README.md
index 5056c066..bb30670e 100644
--- a/README.md
+++ b/README.md
@@ -1,15 +1,19 @@
 # pulumi-go-provider
 
-[![Go Reference](https://pkg.go.dev/badge/github.com/pulumi/pulumi-go-provider.svg)](https://pkg.go.dev/github.com/pulumi/pulumi-go-provider)
 [![Go Report Card](https://goreportcard.com/badge/github.com/pulumi/pulumi-go-provider)](https://goreportcard.com/report/github.com/pulumi/pulumi-go-provider)
 
-A framework for building Go Providers for Pulumi
+A framework for building Go Providers for Pulumi.
 
-_Note_: This library is in active development, and not everthing is hooked up. You should
+**Library documentation can be found at** [![Go Reference](https://pkg.go.dev/badge/github.com/pulumi/pulumi-go-provider.svg)](https://pkg.go.dev/github.com/pulumi/pulumi-go-provider)
+
+_Note_: This library is in active development, and not everything is hooked up. You should
 expect breaking changes as we fine tune the exposed APIs. We definitely appreciate
 community feedback, but you should probably wait to port any existing providers over.
 
-For detailed instructions on building providers with `infer`, see [infer/README.md](./infer/README.md).
+The highest level of `pulumi-go-provider` is `infer`, which derives as much possible from
+your Go code. The "Hello, Pulumi" example below uses `infer`. For detailed instructions on
+building providers with `infer`, click
+[here](https://pkg.go.dev/github.com/pulumi/pulumi-go-provider).
 
 ## The "Hello, Pulumi" Provider
 
diff --git a/infer/component.go b/infer/component.go
index 44f6992e..449da4cc 100644
--- a/infer/component.go
+++ b/infer/component.go
@@ -38,8 +38,9 @@ type ComponentResource[I any, O pulumi.ComponentResource] interface {
 	Construct(ctx *pulumi.Context, name, typ string, inputs I, opts pulumi.ResourceOption) (O, error)
 }
 
-// A component resource inferred from code. To get an instance of an InferredComponent,
-// call the function Component.
+// A component resource inferred from code.
+//
+// To create an [InferredComponent], call the [Component] function.
 type InferredComponent interface {
 	t.ComponentResource
 	schema.Resource
diff --git a/infer/provider.go b/infer/provider.go
index 0006b3ac..b51cc7f4 100644
--- a/infer/provider.go
+++ b/infer/provider.go
@@ -33,11 +33,32 @@ var configKey configKeyType
 
 // Configure an inferred provider.
 type Options struct {
+	// Metadata describes provider level metadata for the schema.
+	//
+	// Look at [schema.Metadata] to see the set of configurable options.
+	//
+	// It does not contain runtime details for the provider.
 	schema.Metadata
-	Resources  []InferredResource  // Inferred resources served by the provider.
-	Components []InferredComponent // Inferred components served by the provider.
-	Functions  []InferredFunction  // Inferred functions served by the provider.
-	Config     InferredConfig
+
+	// The set of custom resources served by the provider.
+	//
+	// To create an [InferredResource], use [Resource].
+	Resources []InferredResource
+
+	// The set of component resources served by the provider.
+	//
+	// To create an [InferredComponent], use [Component].
+	Components []InferredComponent
+
+	// The set of functions served by the provider.
+	//
+	// To create an [InferredFunction], use [Function].
+	Functions []InferredFunction
+
+	// The config used by the provider, if any.
+	//
+	// To create an [InferredConfig], use [Config].
+	Config InferredConfig
 
 	// ModuleMap provides a mapping between go modules and pulumi modules.
 	//
@@ -101,11 +122,18 @@ func (o Options) schema() schema.Options {
 	}
 }
 
-// Create a new inferred provider from `opts`.
+// Provider creates a new inferred provider from `opts`.
+//
+// To customize the resulting provider, including setting resources, functions, config options and other
+// schema metadata, look at the [Options] struct.
 func Provider(opts Options) p.Provider {
 	return Wrap(p.Provider{}, opts)
 }
 
+// Wrap wraps a compatible underlying provider in an inferred provider (as described by options).
+//
+// The resulting provider will respond to resources and functions that are described in `opts`, delegating
+// unknown calls to the underlying provider.
 func Wrap(provider p.Provider, opts Options) p.Provider {
 	provider = dispatch.Wrap(provider, opts.dispatch())
 	provider = schema.Wrap(provider, opts.schema())
diff --git a/middleware/schema/schema.go b/middleware/schema/schema.go
index ad6d0aff..8f36f891 100644
--- a/middleware/schema/schema.go
+++ b/middleware/schema/schema.go
@@ -112,16 +112,60 @@ type Options struct {
 	ModuleMap map[tokens.ModuleName]tokens.ModuleName
 }
 
+// Metadata describes additional metadata to embed in the generated Pulumi Schema.
 type Metadata struct {
-	LanguageMap       map[string]any
-	Description       string
-	DisplayName       string
-	Keywords          []string
-	Homepage          string
-	Repository        string
-	Publisher         string
-	LogoURL           string
-	License           string
+	// LanguageMap corresponds to the [schema.PackageSpec.Language] section of the
+	// resulting schema.
+	//
+	// Example:
+	//
+	// 	import (
+	// 		goGen "github.com/pulumi/pulumi/pkg/v3/codegen/go"
+	// 		nodejsGen "github.com/pulumi/pulumi/pkg/v3/codegen/nodejs"
+	// 		pythonGen "github.com/pulumi/pulumi/pkg/v3/codegen/python"
+	// 		csharpGen "github.com/pulumi/pulumi/pkg/v3/codegen/dotnet"
+	// 		javaGen " github.com/pulumi/pulumi-java/pkg/codegen/java"
+	//	)
+	//
+	//	Metadata{
+	//		LanguageMap: map[string]any{
+	//			"go": goGen.GoPackageInfo{
+	//				RootPackageName: "go-specific",
+	//			},
+	//			"nodejs": nodejsGen.NodePackageInfo{
+	//				PackageName: "nodejs-specific",
+	//			},
+	//			"python": pythonGen.PackageInfo{
+	//				PackageName: "python-specific",
+	//			},
+	//			"csharp": csharpGen.CSharpPackageInfo{
+	//				RootNamespace: "csharp-specific",
+	//			},
+	//			"java": javaGen.PackageInfo{
+	//				BasePackage: "java-specific",
+	//			},
+	//		},
+	//	}
+	//
+	// Before embedding, each field is marshaled via [json.Marshal].
+	LanguageMap map[string]any
+	// Description sets the [schema.PackageSpec.Description] field.
+	Description string
+	// DisplayName sets the [schema.PackageSpec.DisplayName] field.
+	DisplayName string
+	// Keywords sets the [schema.PackageSpec.Keywords] field.
+	Keywords []string
+	// Homepage sets the [schema.PackageSpec.Homepage] field.
+	Homepage string
+	// Repository sets the [schema.PackageSpec.Repository] field.
+	Repository string
+	// Publisher sets the [schema.PackageSpec.Publisher] field.
+	Publisher string
+	// LogoURL sets the [schema.PackageSpec.LogoURL] field.
+	LogoURL string
+	// License sets the [schema.PackageSpec.License] field.
+	License string
+	// PluginDownloadURL sets the [schema.PackageSpec.PluginDownloadURL] field.
 	PluginDownloadURL string
 }