diff --git a/cmd/core-lint/main.go b/cmd/core-lint/main.go
index 7affa95..e032c6a 100644
--- a/cmd/core-lint/main.go
+++ b/cmd/core-lint/main.go
@@ -47,9 +47,28 @@ func addRFCCommands(parent *cli.Command) {
 }
 
 func newRunCommand(use string, short string, defaults lintpkg.RunInput) *cli.Command {
-	input := defaults
+	var (
+		output   string
+		config   string
+		failOn   string
+		category string
+		lang     string
+		hook     bool
+		ci       bool
+		sbom     bool
+	)
 
 	cmd := cli.NewCommand(use, short, "", func(cmd *cli.Command, args []string) error {
+		input := defaults
+		input.Output = output
+		input.Config = config
+		input.FailOn = failOn
+		input.Category = category
+		input.Lang = lang
+		input.Hook = hook
+		input.CI = ci
+		input.SBOM = sbom
+
 		if len(args) > 0 {
 			input.Path = args[0]
 		}
@@ -78,14 +97,14 @@ func newRunCommand(use string, short string, defaults lintpkg.RunInput) *cli.Com
 		return nil
 	})
 
-	cli.StringFlag(cmd, &input.Output, "output", "o", defaults.Output, "Output format: json, text, github, sarif")
-	cli.StringFlag(cmd, &input.Config, "config", "c", defaults.Config, "Config path (default: .core/lint.yaml)")
-	cli.StringFlag(cmd, &input.FailOn, "fail-on", "", defaults.FailOn, "Fail threshold: error, warning, info")
-	cli.StringFlag(cmd, &input.Category, "category", "", defaults.Category, "Restrict to one category")
-	cli.StringFlag(cmd, &input.Lang, "lang", "l", defaults.Lang, "Restrict to one language")
-	cli.BoolFlag(cmd, &input.Hook, "hook", "", defaults.Hook, "Run in pre-commit mode against staged files")
-	cli.BoolFlag(cmd, &input.CI, "ci", "", defaults.CI, "GitHub Actions mode (github annotations)")
-	cli.BoolFlag(cmd, &input.SBOM, "sbom", "", defaults.SBOM, "Enable compliance/SBOM tools")
+	cli.StringFlag(cmd, &output, "output", "o", defaults.Output, "Output format: json, text, github, sarif")
+	cli.StringFlag(cmd, &config, "config", "c", defaults.Config, "Config path (default: .core/lint.yaml)")
+	cli.StringFlag(cmd, &failOn, "fail-on", "", defaults.FailOn, "Fail threshold: error, warning, info")
+	cli.StringFlag(cmd, &category, "category", "", defaults.Category, "Restrict to one category")
+	cli.StringFlag(cmd, &lang, "lang", "l", defaults.Lang, "Restrict to one language")
+	cli.BoolFlag(cmd, &hook, "hook", "", defaults.Hook, "Run in pre-commit mode against staged files")
+	cli.BoolFlag(cmd, &ci, "ci", "", defaults.CI, "GitHub Actions mode (github annotations)")
+	cli.BoolFlag(cmd, &sbom, "sbom", "", defaults.SBOM, "Enable compliance/SBOM tools")
 
 	return cmd
 }
diff --git a/pkg/lint/service.go b/pkg/lint/service.go
index 434d1ef..54a56e2 100644
--- a/pkg/lint/service.go
+++ b/pkg/lint/service.go
@@ -71,11 +71,15 @@ type Service struct {
 }
 
 // NewService constructs a lint orchestrator with the built-in adapter registry.
+//
+//	svc := lint.NewService()
 func NewService() *Service {
 	return &Service{adapters: defaultAdapters()}
 }
 
 // Run executes the selected adapters and returns the merged report.
+//
+//	report, err := lint.NewService().Run(ctx, lint.RunInput{Path: ".", Output: "json"})
 func (s *Service) Run(ctx context.Context, input RunInput) (Report, error) {
 	startedAt := time.Now().UTC()
 	input = normaliseRunInput(input)
@@ -137,6 +141,8 @@ func (s *Service) Run(ctx context.Context, input RunInput) (Report, error) {
 }
 
 // Tools returns the current adapter inventory for display in the CLI.
+//
+//	tools := lint.NewService().Tools([]string{"go"})
 func (s *Service) Tools(languages []string) []ToolInfo {
 	var tools []ToolInfo
 	for _, adapter := range s.adapters {
@@ -188,6 +194,8 @@ func (s *Service) WriteDefaultConfig(projectPath string, force bool) (string, er
 }
 
 // InstallHook adds a git pre-commit hook that runs `core-lint run --hook`.
+//
+//	_ = lint.NewService().InstallHook(".")
 func (s *Service) InstallHook(projectPath string) error {
 	hookPath, err := hookFilePath(projectPath)
 	if err != nil {
@@ -225,6 +233,8 @@ func (s *Service) InstallHook(projectPath string) error {
 }
 
 // RemoveHook removes the block previously installed by InstallHook.
+//
+//	_ = lint.NewService().RemoveHook(".")
 func (s *Service) RemoveHook(projectPath string) error {
 	hookPath, err := hookFilePath(projectPath)
 	if err != nil {