refactor: replace positional params with OrganizationUpdateOpts struct

Replace 8 positional parameters on OrganizationRepo.Update and
OrganizationUseCase.Update with an OrganizationUpdateOpts struct
for better readability and extensibility. Also regenerate CLI docs
and add CLI documentation instruction to CLAUDE.md.

Signed-off-by: Jose I. Paris <jiparis@chainloop.dev>

Author: jiparis

CLAUDE.md

@@ -240,6 +240,7 @@ Workflow Contracts define the structure and requirements for CI/CD attestations.
 - **Actions**: Implement business logic in `internal/action/`
 - **Policy Development**: Use `internal/policydevel/` for local policy testing
 - **Default Endpoints**: Override with `-ldflags` at build time using `defaultCASAPI` and `defaultCPAPI` variables
+- **Documentation**: After adding or modifying CLI commands, regenerate docs with `make generate` (runs `go generate ./...` which includes CLI docs)
 
 ### Artifact CAS Development
 - **Storage Backends**: Implement new backends in `pkg/blobmanager/` with Provider interface

app/cli/documentation/cli-reference.mdx

@@ -2824,6 +2824,7 @@ Options
 ```
 --api-token-max-days-inactive string   maximum days of inactivity before API tokens are auto-revoked (e.g. '90', '0' to disable)
 --block                                set the default policy violation blocking strategy
+--enable-ai-agent-collector            enable automatic AI agent config collection during attestation init
 -h, --help                                 help for update
 --name string                          organization name
 --policies-allowed-hostnames strings   set the allowed hostnames for the policy engine

app/controlplane/internal/service/organization.go

@@ -102,7 +102,14 @@ func (s *OrganizationService) Update(ctx context.Context, req *pb.OrganizationSe
 		apiTokenMaxDaysInactive = &days
 	}
 
-	org, err := s.orgUC.Update(ctx, currentUser.ID, req.Name, req.BlockOnPolicyViolation, policiesAllowedHostnames, req.PreventImplicitWorkflowCreation, req.RestrictContractCreationToOrgAdmins, apiTokenMaxDaysInactive, req.EnableAiAgentCollector)
+	org, err := s.orgUC.Update(ctx, currentUser.ID, req.Name, &biz.OrganizationUpdateOpts{
+		BlockOnPolicyViolation:              req.BlockOnPolicyViolation,
+		PoliciesAllowedHostnames:            policiesAllowedHostnames,
+		PreventImplicitWorkflowCreation:     req.PreventImplicitWorkflowCreation,
+		RestrictContractCreationToOrgAdmins: req.RestrictContractCreationToOrgAdmins,
+		APITokenInactivityThresholdDays:     apiTokenMaxDaysInactive,
+		EnableAIAgentCollector:              req.EnableAiAgentCollector,
+	})
 	if err != nil {
 		return nil, handleUseCaseErr(err, s.log)
 	}

app/controlplane/pkg/biz/apitoken_stale_revoker_integration_test.go

@@ -199,7 +199,9 @@ func (s *staleRevokerTestSuite) createOrgWithThreshold(ctx context.Context, days
 	_, err = s.Membership.Create(ctx, org.ID, s.user.ID, biz.WithCurrentMembership())
 	require.NoError(s.T(), err)
 
-	org, err = s.Organization.Update(ctx, s.user.ID, org.Name, nil, nil, nil, nil, &days, nil)
+	org, err = s.Organization.Update(ctx, s.user.ID, org.Name, &biz.OrganizationUpdateOpts{
+		APITokenInactivityThresholdDays: &days,
+	})
 	require.NoError(s.T(), err)
 	require.NotNil(s.T(), org.APITokenInactivityThresholdDays)
 	assert.Equal(s.T(), days, *org.APITokenInactivityThresholdDays)

app/controlplane/pkg/biz/mocks/OrganizationRepo.go

@@ -50,11 +50,23 @@ type Organization struct {
 	EnableAIAgentCollector bool
 }
 
+// OrganizationUpdateOpts holds optional fields for updating an organization.
+// Pointer fields use nil to indicate "no change". For PoliciesAllowedHostnames,
+// nil means "no change" while an empty slice means "clear the list".
+type OrganizationUpdateOpts struct {
+	BlockOnPolicyViolation              *bool
+	PoliciesAllowedHostnames            []string
+	PreventImplicitWorkflowCreation     *bool
+	RestrictContractCreationToOrgAdmins *bool
+	APITokenInactivityThresholdDays     *int
+	EnableAIAgentCollector              *bool
+}
+
 type OrganizationRepo interface {
 	FindByID(ctx context.Context, orgID uuid.UUID) (*Organization, error)
 	FindByName(ctx context.Context, name string) (*Organization, error)
 	Create(ctx context.Context, name string) (*Organization, error)
-	Update(ctx context.Context, id uuid.UUID, blockOnPolicyViolation *bool, policiesAllowedHostnames []string, preventImplicitWorkflowCreation *bool, restrictContractCreationToOrgAdmins *bool, apiTokenInactivityThresholdDays *int, enableAIAgentCollector *bool) (*Organization, error)
+	Update(ctx context.Context, id uuid.UUID, opts *OrganizationUpdateOpts) (*Organization, error)
 	Delete(ctx context.Context, ID uuid.UUID) error
 	// FindWithTokenInactivityThreshold returns orgs that have api_token_inactivity_threshold_days set (non-nil).
 	FindWithTokenInactivityThreshold(ctx context.Context) ([]*Organization, error)
@@ -196,7 +208,7 @@ func (uc *OrganizationUseCase) doCreate(ctx context.Context, name string, opts .
 	return org, nil
 }
 
-func (uc *OrganizationUseCase) Update(ctx context.Context, userID, orgName string, blockOnPolicyViolation *bool, policiesAllowedHostnames []string, preventImplicitWorkflowCreation *bool, restrictContractCreationToOrgAdmins *bool, apiTokenInactivityThresholdDays *int, enableAIAgentCollector *bool) (*Organization, error) {
+func (uc *OrganizationUseCase) Update(ctx context.Context, userID, orgName string, opts *OrganizationUpdateOpts) (*Organization, error) {
 	userUUID, err := uuid.Parse(userID)
 	if err != nil {
 		return nil, NewErrInvalidUUID(err)
@@ -216,7 +228,7 @@ func (uc *OrganizationUseCase) Update(ctx context.Context, userID, orgName strin
 	}
 
 	// Perform the update
-	org, err := uc.orgRepo.Update(ctx, orgUUID, blockOnPolicyViolation, policiesAllowedHostnames, preventImplicitWorkflowCreation, restrictContractCreationToOrgAdmins, apiTokenInactivityThresholdDays, enableAIAgentCollector)
+	org, err := uc.orgRepo.Update(ctx, orgUUID, opts)
 	if err != nil {
 		return nil, fmt.Errorf("failed to update organization: %w", err)
 	} else if org == nil {

app/controlplane/pkg/biz/organization.go

@@ -118,53 +118,65 @@ func (s *OrgIntegrationTestSuite) TestUpdate() {
 
 	s.Run("org non existent", func() {
 		// org not found
-		_, err := s.Organization.Update(ctx, s.user.ID, uuid.NewString(), nil, nil, nil, nil, nil, nil)
+		_, err := s.Organization.Update(ctx, s.user.ID, uuid.NewString(), &biz.OrganizationUpdateOpts{})
 		s.Error(err)
 		s.True(biz.IsNotFound(err))
 	})
 
 	s.Run("org not accessible to user", func() {
 		org2, err := s.Organization.CreateWithRandomName(ctx)
 		require.NoError(s.T(), err)
-		_, err = s.Organization.Update(ctx, s.user.ID, org2.Name, nil, nil, nil, nil, nil, nil)
+		_, err = s.Organization.Update(ctx, s.user.ID, org2.Name, &biz.OrganizationUpdateOpts{})
 		s.Error(err)
 		s.True(biz.IsNotFound(err))
 	})
 
 	s.Run("valid block on policy violation update", func() {
-		got, err := s.Organization.Update(ctx, s.user.ID, s.org.Name, toPtrBool(true), nil, nil, nil, nil, nil)
+		got, err := s.Organization.Update(ctx, s.user.ID, s.org.Name, &biz.OrganizationUpdateOpts{
+			BlockOnPolicyViolation: toPtrBool(true),
+		})
 		s.NoError(err)
 		s.True(got.BlockOnPolicyViolation)
 	})
 
 	s.Run("valid policy allowed hostnames update", func() {
-		got, err := s.Organization.Update(ctx, s.user.ID, s.org.Name, nil, []string{"foo.com", "bar.com"}, nil, nil, nil, nil)
+		got, err := s.Organization.Update(ctx, s.user.ID, s.org.Name, &biz.OrganizationUpdateOpts{
+			PoliciesAllowedHostnames: []string{"foo.com", "bar.com"},
+		})
 		s.NoError(err)
 		s.Equal([]string{"foo.com", "bar.com"}, got.PoliciesAllowedHostnames)
 	})
 
 	s.Run("clear policy allowed hostnames", func() {
-		got, err := s.Organization.Update(ctx, s.user.ID, s.org.Name, nil, []string{}, nil, nil, nil, nil)
+		got, err := s.Organization.Update(ctx, s.user.ID, s.org.Name, &biz.OrganizationUpdateOpts{
+			PoliciesAllowedHostnames: []string{},
+		})
 		s.NoError(err)
 		s.Equal([]string{}, got.PoliciesAllowedHostnames)
 	})
 
 	s.Run("valid enable AI agent collector update", func() {
-		got, err := s.Organization.Update(ctx, s.user.ID, s.org.Name, nil, nil, nil, nil, nil, toPtrBool(true))
+		got, err := s.Organization.Update(ctx, s.user.ID, s.org.Name, &biz.OrganizationUpdateOpts{
+			EnableAIAgentCollector: toPtrBool(true),
+		})
 		s.NoError(err)
 		s.True(got.EnableAIAgentCollector)
 
-		got, err = s.Organization.Update(ctx, s.user.ID, s.org.Name, nil, nil, nil, nil, nil, toPtrBool(false))
+		got, err = s.Organization.Update(ctx, s.user.ID, s.org.Name, &biz.OrganizationUpdateOpts{
+			EnableAIAgentCollector: toPtrBool(false),
+		})
 		s.NoError(err)
 		s.False(got.EnableAIAgentCollector)
 	})
 
 	s.Run("but not passing a value doesn't clear the hostnames value", func() {
-		got, err := s.Organization.Update(ctx, s.user.ID, s.org.Name, nil, []string{"foo.com", "bar.com"}, nil, nil, nil, nil)
+		got, err := s.Organization.Update(ctx, s.user.ID, s.org.Name, &biz.OrganizationUpdateOpts{
+			PoliciesAllowedHostnames: []string{"foo.com", "bar.com"},
+		})
 		s.NoError(err)
 		s.Equal([]string{"foo.com", "bar.com"}, got.PoliciesAllowedHostnames)
 
-		got, err = s.Organization.Update(ctx, s.user.ID, s.org.Name, nil, nil, nil, nil, nil, nil)
+		got, err = s.Organization.Update(ctx, s.user.ID, s.org.Name, &biz.OrganizationUpdateOpts{})
 		s.NoError(err)
 		s.Equal([]string{"foo.com", "bar.com"}, got.PoliciesAllowedHostnames)
 	})

app/controlplane/pkg/biz/organization_integration_test.go

@@ -187,7 +187,9 @@ func (s *workflowIntegrationTestSuite) TestCreate() {
 
 	// Enable implicit workflow creation prevention for testing
 	orgID, _ := uuid.Parse(s.org.ID)
-	_, err = s.Repos.OrganizationRepo.Update(ctx, orgID, nil, nil, toPtrBool(true), nil, nil, nil)
+	_, err = s.Repos.OrganizationRepo.Update(ctx, orgID, &biz.OrganizationUpdateOpts{
+		PreventImplicitWorkflowCreation: toPtrBool(true),
+	})
 	s.Require().NoError(err)
 
 	for _, tc := range testCases {

app/controlplane/pkg/biz/workflow_integration_test.go

@@ -77,28 +77,28 @@ func (r *OrganizationRepo) FindByName(ctx context.Context, name string) (*biz.Or
 	return entOrgToBizOrg(org), nil
 }
 
-func (r *OrganizationRepo) Update(ctx context.Context, id uuid.UUID, blockOnPolicyViolation *bool, policiesAllowedHostnames []string, preventImplicitWorkflowCreation *bool, restrictContractCreationToOrgAdmins *bool, apiTokenInactivityThresholdDays *int, enableAIAgentCollector *bool) (*biz.Organization, error) {
-	opts := r.data.DB.Organization.UpdateOneID(id).
+func (r *OrganizationRepo) Update(ctx context.Context, id uuid.UUID, updateOpts *biz.OrganizationUpdateOpts) (*biz.Organization, error) {
+	query := r.data.DB.Organization.UpdateOneID(id).
 		Where(organization.DeletedAtIsNil()).
-		SetNillableBlockOnPolicyViolation(blockOnPolicyViolation).
-		SetNillablePreventImplicitWorkflowCreation(preventImplicitWorkflowCreation).
-		SetNillableRestrictContractCreationToOrgAdmins(restrictContractCreationToOrgAdmins).
-		SetNillableEnableAiAgentCollector(enableAIAgentCollector).
+		SetNillableBlockOnPolicyViolation(updateOpts.BlockOnPolicyViolation).
+		SetNillablePreventImplicitWorkflowCreation(updateOpts.PreventImplicitWorkflowCreation).
+		SetNillableRestrictContractCreationToOrgAdmins(updateOpts.RestrictContractCreationToOrgAdmins).
+		SetNillableEnableAiAgentCollector(updateOpts.EnableAIAgentCollector).
 		SetUpdatedAt(time.Now())
 
-	if policiesAllowedHostnames != nil {
-		opts.SetPoliciesAllowedHostnames(policiesAllowedHostnames)
+	if updateOpts.PoliciesAllowedHostnames != nil {
+		query.SetPoliciesAllowedHostnames(updateOpts.PoliciesAllowedHostnames)
 	}
 
-	if apiTokenInactivityThresholdDays != nil {
-		if *apiTokenInactivityThresholdDays == 0 {
-			opts.ClearAPITokenInactivityThresholdDays()
+	if updateOpts.APITokenInactivityThresholdDays != nil {
+		if *updateOpts.APITokenInactivityThresholdDays == 0 {
+			query.ClearAPITokenInactivityThresholdDays()
 		} else {
-			opts.SetAPITokenInactivityThresholdDays(*apiTokenInactivityThresholdDays)
+			query.SetAPITokenInactivityThresholdDays(*updateOpts.APITokenInactivityThresholdDays)
 		}
 	}
 
-	org, err := opts.Save(ctx)
+	org, err := query.Save(ctx)
 	if err != nil {
 		return nil, fmt.Errorf("failed to update organization: %w", err)
 	}