diff --git a/pkg/mining/container.go b/pkg/mining/container.go
index 116e94e..4991156 100644
--- a/pkg/mining/container.go
+++ b/pkg/mining/container.go
@@ -63,7 +63,8 @@ type Container struct {
 	shutdownCh       chan struct{}
 }
 
-// NewContainer creates a new service container with the given configuration.
+// container := NewContainer(DefaultContainerConfig())
+// container.Initialize(ctx)
 func NewContainer(config ContainerConfig) *Container {
 	return &Container{
 		config:     config,
@@ -127,7 +128,7 @@ func (c *Container) Initialize(ctx context.Context) error {
 	return nil
 }
 
-// Start begins all background services.
+// if err := container.Start(ctx); err != nil { return err }
 func (c *Container) Start(ctx context.Context) error {
 	c.mu.RLock()
 	defer c.mu.RUnlock()
@@ -152,7 +153,7 @@ func (c *Container) Start(ctx context.Context) error {
 	return nil
 }
 
-// Shutdown gracefully stops all services in reverse order.
+// defer container.Shutdown(ctx) // safe to call multiple times
 func (c *Container) Shutdown(ctx context.Context) error {
 	c.mu.Lock()
 	defer c.mu.Unlock()