chore(docs): add and refine package-level comments across modules

- Added detailed package-level comments to improve documentation coverage.
- Clarified parameter descriptions, return types, and functionality of exported methods across packages.
- Enhanced overall code readability and API documentation consistency.

sdk/cliproxy/builder.go

@@ -1,3 +1,6 @@
+// Package cliproxy provides the core service implementation for the CLI Proxy API.
+// It includes service lifecycle management, authentication handling, file watching,
+// and integration with various AI service providers through a unified interface.
 package cliproxy
 
 import (
@@ -11,37 +14,81 @@ import (
 )
 
 // Builder constructs a Service instance with customizable providers.
+// It provides a fluent interface for configuring all aspects of the service
+// including authentication, file watching, HTTP server options, and lifecycle hooks.
 type Builder struct {
-	cfg            *config.Config
-	configPath     string
-	tokenProvider  TokenClientProvider
+	// cfg holds the application configuration.
+	cfg *config.Config
+
+	// configPath is the path to the configuration file.
+	configPath string
+
+	// tokenProvider handles loading token-based clients.
+	tokenProvider TokenClientProvider
+
+	// apiKeyProvider handles loading API key-based clients.
 	apiKeyProvider APIKeyClientProvider
+
+	// watcherFactory creates file watcher instances.
 	watcherFactory WatcherFactory
-	hooks          Hooks
-	authManager    *sdkAuth.Manager
-	accessManager  *sdkaccess.Manager
-	coreManager    *coreauth.Manager
-	serverOptions  []api.ServerOption
+
+	// hooks provides lifecycle callbacks.
+	hooks Hooks
+
+	// authManager handles legacy authentication operations.
+	authManager *sdkAuth.Manager
+
+	// accessManager handles request authentication providers.
+	accessManager *sdkaccess.Manager
+
+	// coreManager handles core authentication and execution.
+	coreManager *coreauth.Manager
+
+	// serverOptions contains additional server configuration options.
+	serverOptions []api.ServerOption
 }
 
 // Hooks allows callers to plug into service lifecycle stages.
+// These callbacks provide opportunities to perform custom initialization
+// and cleanup operations during service startup and shutdown.
 type Hooks struct {
+	// OnBeforeStart is called before the service starts, allowing configuration
+	// modifications or additional setup.
 	OnBeforeStart func(*config.Config)
-	OnAfterStart  func(*Service)
+
+	// OnAfterStart is called after the service has started successfully,
+	// providing access to the service instance for additional operations.
+	OnAfterStart func(*Service)
 }
 
 // NewBuilder creates a Builder with default dependencies left unset.
+// Use the fluent interface methods to configure the service before calling Build().
+//
+// Returns:
+//   - *Builder: A new builder instance ready for configuration
 func NewBuilder() *Builder {
 	return &Builder{}
 }
 
 // WithConfig sets the configuration instance used by the service.
+//
+// Parameters:
+//   - cfg: The application configuration
+//
+// Returns:
+//   - *Builder: The builder instance for method chaining
 func (b *Builder) WithConfig(cfg *config.Config) *Builder {
 	b.cfg = cfg
 	return b
 }
 
 // WithConfigPath sets the absolute configuration file path used for reload watching.
+//
+// Parameters:
+//   - path: The absolute path to the configuration file
+//
+// Returns:
+//   - *Builder: The builder instance for method chaining
 func (b *Builder) WithConfigPath(path string) *Builder {
 	b.configPath = path
 	return b

sdk/cliproxy/service.go

@@ -1,3 +1,6 @@
+// Package cliproxy provides the core service implementation for the CLI Proxy API.
+// It includes service lifecycle management, authentication handling, file watching,
+// and integration with various AI service providers through a unified interface.
 package cliproxy
 
 import (
@@ -26,38 +29,74 @@ import (
 )
 
 // Service wraps the proxy server lifecycle so external programs can embed the CLI proxy.
+// It manages the complete lifecycle including authentication, file watching, HTTP server,
+// and integration with various AI service providers.
 type Service struct {
-	cfg        *config.Config
-	cfgMu      sync.RWMutex
+	// cfg holds the current application configuration.
+	cfg *config.Config
+
+	// cfgMu protects concurrent access to the configuration.
+	cfgMu sync.RWMutex
+
+	// configPath is the path to the configuration file.
 	configPath string
 
-	tokenProvider  TokenClientProvider
-	apiKeyProvider APIKeyClientProvider
-	watcherFactory WatcherFactory
-	hooks          Hooks
-	serverOptions  []api.ServerOption
+	// tokenProvider handles loading token-based clients.
+	tokenProvider TokenClientProvider
 
-	server    *api.Server
+	// apiKeyProvider handles loading API key-based clients.
+	apiKeyProvider APIKeyClientProvider
+
+	// watcherFactory creates file watcher instances.
+	watcherFactory WatcherFactory
+
+	// hooks provides lifecycle callbacks.
+	hooks Hooks
+
+	// serverOptions contains additional server configuration options.
+	serverOptions []api.ServerOption
+
+	// server is the HTTP API server instance.
+	server *api.Server
+
+	// serverErr channel for server startup/shutdown errors.
 	serverErr chan error
 
-	watcher       *WatcherWrapper
+	// watcher handles file system monitoring.
+	watcher *WatcherWrapper
+
+	// watcherCancel cancels the watcher context.
 	watcherCancel context.CancelFunc
-	authUpdates   chan watcher.AuthUpdate
+
+	// authUpdates channel for authentication updates.
+	authUpdates chan watcher.AuthUpdate
+
+	// authQueueStop cancels the auth update queue processing.
 	authQueueStop context.CancelFunc
 
-	// legacy client caches removed
-	authManager   *sdkAuth.Manager
-	accessManager *sdkaccess.Manager
-	coreManager   *coreauth.Manager
+	// authManager handles legacy authentication operations.
+	authManager *sdkAuth.Manager
 
+	// accessManager handles request authentication providers.
+	accessManager *sdkaccess.Manager
+
+	// coreManager handles core authentication and execution.
+	coreManager *coreauth.Manager
+
+	// shutdownOnce ensures shutdown is called only once.
 	shutdownOnce sync.Once
 }
 
 // RegisterUsagePlugin registers a usage plugin on the global usage manager.
+// This allows external code to monitor API usage and token consumption.
+//
+// Parameters:
+//   - plugin: The usage plugin to register
 func (s *Service) RegisterUsagePlugin(plugin usage.Plugin) {
 	usage.RegisterPlugin(plugin)
 }
 
+// newDefaultAuthManager creates a default authentication manager with all supported providers.
 func newDefaultAuthManager() *sdkAuth.Manager {
 	return sdkAuth.NewManager(
 		sdkAuth.NewFileTokenStore(),
@@ -216,6 +255,14 @@ func (s *Service) ensureExecutorsForAuth(a *coreauth.Auth) {
 }
 
 // Run starts the service and blocks until the context is cancelled or the server stops.
+// It initializes all components including authentication, file watching, HTTP server,
+// and starts processing requests. The method blocks until the context is cancelled.
+//
+// Parameters:
+//   - ctx: The context for controlling the service lifecycle
+//
+// Returns:
+//   - error: An error if the service fails to start or run
 func (s *Service) Run(ctx context.Context) error {
 	if s == nil {
 		return fmt.Errorf("cliproxy: service is nil")
@@ -356,6 +403,14 @@ func (s *Service) Run(ctx context.Context) error {
 }
 
 // Shutdown gracefully stops background workers and the HTTP server.
+// It ensures all resources are properly cleaned up and connections are closed.
+// The shutdown is idempotent and can be called multiple times safely.
+//
+// Parameters:
+//   - ctx: The context for controlling the shutdown timeout
+//
+// Returns:
+//   - error: An error if shutdown fails
 func (s *Service) Shutdown(ctx context.Context) error {
 	if s == nil {
 		return nil

sdk/cliproxy/types.go

@@ -1,3 +1,6 @@
+// Package cliproxy provides the core service implementation for the CLI Proxy API.
+// It includes service lifecycle management, authentication handling, file watching,
+// and integration with various AI service providers through a unified interface.
 package cliproxy
 
 import (
@@ -9,30 +12,70 @@ import (
 )
 
 // TokenClientProvider loads clients backed by stored authentication tokens.
+// It provides an interface for loading authentication tokens from various sources
+// and creating clients for AI service providers.
 type TokenClientProvider interface {
+	// Load loads token-based clients from the configured source.
+	//
+	// Parameters:
+	//   - ctx: The context for the loading operation
+	//   - cfg: The application configuration
+	//
+	// Returns:
+	//   - *TokenClientResult: The result containing loaded clients
+	//   - error: An error if loading fails
 	Load(ctx context.Context, cfg *config.Config) (*TokenClientResult, error)
 }
 
 // TokenClientResult represents clients generated from persisted tokens.
+// It contains metadata about the loading operation and the number of successful authentications.
 type TokenClientResult struct {
+	// SuccessfulAuthed is the number of successfully authenticated clients.
 	SuccessfulAuthed int
 }
 
 // APIKeyClientProvider loads clients backed directly by configured API keys.
+// It provides an interface for loading API key-based clients for various AI service providers.
 type APIKeyClientProvider interface {
+	// Load loads API key-based clients from the configuration.
+	//
+	// Parameters:
+	//   - ctx: The context for the loading operation
+	//   - cfg: The application configuration
+	//
+	// Returns:
+	//   - *APIKeyClientResult: The result containing loaded clients
+	//   - error: An error if loading fails
 	Load(ctx context.Context, cfg *config.Config) (*APIKeyClientResult, error)
 }
 
 // APIKeyClientResult contains API key based clients along with type counts.
+// It provides metadata about the number of clients loaded for each provider type.
 type APIKeyClientResult struct {
-	GeminiKeyCount    int
-	ClaudeKeyCount    int
-	CodexKeyCount     int
+	// GeminiKeyCount is the number of Gemini API key clients loaded.
+	GeminiKeyCount int
+
+	// ClaudeKeyCount is the number of Claude API key clients loaded.
+	ClaudeKeyCount int
+
+	// CodexKeyCount is the number of Codex API key clients loaded.
+	CodexKeyCount int
+
+	// OpenAICompatCount is the number of OpenAI-compatible API key clients loaded.
 	OpenAICompatCount int
 }
 
 // WatcherFactory creates a watcher for configuration and token changes.
-// The reload callback now only receives the updated configuration.
+// The reload callback receives the updated configuration when changes are detected.
+//
+// Parameters:
+//   - configPath: The path to the configuration file to watch
+//   - authDir: The directory containing authentication tokens to watch
+//   - reload: The callback function to call when changes are detected
+//
+// Returns:
+//   - *WatcherWrapper: A watcher wrapper instance
+//   - error: An error if watcher creation fails
 type WatcherFactory func(configPath, authDir string, reload func(*config.Config)) (*WatcherWrapper, error)
 
 // WatcherWrapper exposes the subset of watcher methods required by the SDK.