docs(cli): reference --oidc-group-mapping flag name instead of 'legacy'

Issue: Used internal nomenclature instead of user-facing flag name The previous fix referenced 'legacy group name mapping' but users don't know what that means - it's an internal implementation detail. Users configure this via the --oidc-group-mapping flag. Changed to: 'This filter is applied after the oidc-group-mapping.' This directly references the flag name users would actually use, making the relationship clear and actionable. Users can now understand: - The regex filter applies to group names - Group names may have been transformed by --oidc-group-mapping first - They need to write regex patterns that match the mapped names Example: If --oidc-group-mapping transforms 'developers' to 'dev-team', the regex in --oidc-group-regex-filter will match against 'dev-team'.
docs(cli): fix help text for --oidc-group-regex-filter (clarify mapping order)
2026-02-09 16:14:00 -05:00 · 2026-02-09 16:13:59 -05:00 · 2026-02-09 16:13:59 -05:00 · 2026-02-09 16:13:59 -05:00 · 2026-02-09 16:13:59 -05:00 · 2026-02-09 16:13:58 -05:00
1 changed files with 48 additions and 48 deletions
@@ -1431,7 +1431,7 @@ func (c *DeploymentValues) Options() serpent.OptionSet {
 	}
 	emailHello := serpent.Option{
 		Name:        "Email: Hello",
-		Description: "The hostname identifying the SMTP server.",
+		Description: "The hostname identifying this client to the SMTP server.",
 		Flag:        "email-hello",
 		Env:         "CODER_EMAIL_HELLO",
 		Default:     "localhost",
@@ -1523,7 +1523,7 @@ func (c *DeploymentValues) Options() serpent.OptionSet {
 	}
 	emailTLSCertFile := serpent.Option{
 		Name:        "Email TLS: Certificate File",
-		Description: "Certificate file to use.",
+		Description: "Client certificate file for mutual TLS authentication.",
 		Flag:        "email-tls-cert-file",
 		Env:         "CODER_EMAIL_TLS_CERTFILE",
 		Value:       &c.Notifications.SMTP.TLS.CertFile,
@@ -1532,7 +1532,7 @@ func (c *DeploymentValues) Options() serpent.OptionSet {
 	}
 	emailTLSCertKeyFile := serpent.Option{
 		Name:        "Email TLS: Certificate Key File",
-		Description: "Certificate key file to use.",
+		Description: "Private key file for the client certificate.",
 		Flag:        "email-tls-cert-key-file",
 		Env:         "CODER_EMAIL_TLS_CERTKEYFILE",
 		Value:       &c.Notifications.SMTP.TLS.KeyFile,
@@ -1551,7 +1551,7 @@ func (c *DeploymentValues) Options() serpent.OptionSet {
 	}
 	workspaceHostnameSuffix := serpent.Option{
 		Name:        "Workspace Hostname Suffix",
-		Description: "Workspace hostnames use this suffix in SSH config and Coder Connect on Coder Desktop. By default it is coder, resulting in names like myworkspace.coder.",
+		Description: "Workspace hostnames use this suffix for SSH connections and Coder Connect. By default it is coder, resulting in hostnames like agent.workspace.owner.coder.",
 		Flag:        "workspace-hostname-suffix",
 		Env:         "CODER_WORKSPACE_HOSTNAME_SUFFIX",
 		YAML:        "workspaceHostnameSuffix",
@@ -1680,7 +1680,7 @@ func (c *DeploymentValues) Options() serpent.OptionSet {
 		},
 		{
 			Name:        "TLS Client CA Files",
-			Description: "PEM-encoded Certificate Authority file used for checking the authenticity of client.",
+			Description: "PEM-encoded Certificate Authority file used for checking the authenticity of the client.",
 			Flag:        "tls-client-ca-file",
 			Env:         "CODER_TLS_CLIENT_CA_FILE",
 			Value:       &c.TLS.ClientCAFile,
@@ -1742,7 +1742,7 @@ func (c *DeploymentValues) Options() serpent.OptionSet {
 		},
 		{
 			Name:        "TLS Ciphers",
-			Description: "Specify specific TLS ciphers that allowed to be used. See https://github.com/golang/go/blob/master/src/crypto/tls/cipher_suites.go#L53-L75.",
+			Description: "Specify specific TLS ciphers that are allowed to be used. See https://github.com/golang/go/blob/master/src/crypto/tls/cipher_suites.go#L53-L75.",
 			Flag:        "tls-ciphers",
 			Env:         "CODER_TLS_CIPHERS",
 			Default:     "",
@@ -1800,7 +1800,7 @@ func (c *DeploymentValues) Options() serpent.OptionSet {
 		},
 		{
 			Name:        "DERP Server Region Name",
-			Description: "Region name that for the embedded DERP server.",
+			Description: "Region name to use for the embedded DERP server.",
 			Flag:        "derp-server-region-name",
 			Env:         "CODER_DERP_SERVER_REGION_NAME",
 			Default:     "Coder Embedded Relay",
@@ -1811,7 +1811,7 @@ func (c *DeploymentValues) Options() serpent.OptionSet {
 		},
 		{
 			Name:        "DERP Server STUN Addresses",
-			Description: "Addresses for STUN servers to establish P2P connections. It's recommended to have at least two STUN servers to give users the best chance of connecting P2P to workspaces. Each STUN server will get it's own DERP region, with region IDs starting at `--derp-server-region-id + 1`. Use special value 'disable' to turn off STUN completely.",
+			Description: "Addresses for STUN servers to establish P2P connections. It's recommended to have at least two STUN servers to give users the best chance of connecting P2P to workspaces. Each STUN server will get its own DERP region, with region IDs starting at `--derp-server-region-id + 1`. Use special value 'disable' to turn off STUN completely.",
 			Flag:        "derp-server-stun-addresses",
 			Env:         "CODER_DERP_SERVER_STUN_ADDRESSES",
 			Default:     "stun.l.google.com:19302,stun1.l.google.com:19302,stun2.l.google.com:19302,stun3.l.google.com:19302,stun4.l.google.com:19302",
@@ -1833,7 +1833,7 @@ func (c *DeploymentValues) Options() serpent.OptionSet {
 		},
 		{
 			Name:        "Block Direct Connections",
-			Description: "Block peer-to-peer (aka. direct) workspace connections. All workspace connections from the CLI will be proxied through Coder (or custom configured DERP servers) and will never be peer-to-peer when enabled. Workspaces may still reach out to STUN servers to get their address until they are restarted after this change has been made, but new connections will still be proxied regardless.",
+			Description: "Block peer-to-peer (aka. direct) workspace connections. All workspace connections from the CLI will be proxied through Coder (or custom configured DERP servers) and will never be peer-to-peer when enabled. Workspace agents may still reach out to STUN servers to discover their address until they are restarted, but all new connections will be proxied regardless.",
 			// This cannot be called `disable-direct-connections` because that's
 			// already a global CLI flag for CLI connections. This is a
 			// deployment-wide flag.
@@ -1884,7 +1884,7 @@ func (c *DeploymentValues) Options() serpent.OptionSet {
 		// Prometheus settings
 		{
 			Name:        "Prometheus Enable",
-			Description: "Serve prometheus metrics on the address defined by prometheus address.",
+			Description: "Serve Prometheus metrics on the address defined by prometheus address.",
 			Flag:        "prometheus-enable",
 			Env:         "CODER_PROMETHEUS_ENABLE",
 			Value:       &c.Prometheus.Enable,
@@ -1894,7 +1894,7 @@ func (c *DeploymentValues) Options() serpent.OptionSet {
 		},
 		{
 			Name:        "Prometheus Address",
-			Description: "The bind address to serve prometheus metrics.",
+			Description: "The bind address to serve Prometheus metrics.",
 			Flag:        "prometheus-address",
 			Env:         "CODER_PROMETHEUS_ADDRESS",
 			Default:     "127.0.0.1:2112",
@@ -1945,7 +1945,7 @@ func (c *DeploymentValues) Options() serpent.OptionSet {
 		// Pprof settings
 		{
 			Name:        "pprof Enable",
-			Description: "Serve pprof metrics on the address defined by pprof address.",
+			Description: "Serve pprof profiling endpoints on the address defined by pprof address.",
 			Flag:        "pprof-enable",
 			Env:         "CODER_PPROF_ENABLE",
 			Value:       &c.Pprof.Enable,
@@ -2032,7 +2032,7 @@ func (c *DeploymentValues) Options() serpent.OptionSet {
 		},
 		{
 			Name:        "OAuth2 GitHub Allow Everyone",
-			Description: "Allow all logins, setting this option means allowed orgs and teams must be empty.",
+			Description: "Allow all GitHub users to authenticate. When enabled, allowed orgs and teams must be empty.",
 			Flag:        "oauth2-github-allow-everyone",
 			Env:         "CODER_OAUTH2_GITHUB_ALLOW_EVERYONE",
 			Value:       &c.OAuth2.Github.AllowEveryone,
@@ -2079,8 +2079,8 @@ func (c *DeploymentValues) Options() serpent.OptionSet {
 		},
 		{
 			Name: "OIDC Client Key File",
-			Description: "Pem encoded RSA private key to use for oauth2 PKI/JWT authorization. " +
-				"This can be used instead of oidc-client-secret if your IDP supports it.",
+			Description: "PEM encoded RSA private key to use for OAuth2 PKI/JWT authorization. " +
+				"This can be used instead of oidc-client-secret if your IdP supports it.",
 			Flag:  "oidc-client-key-file",
 			Env:   "CODER_OIDC_CLIENT_KEY_FILE",
 			YAML:  "oidcClientKeyFile",
@@ -2089,8 +2089,8 @@ func (c *DeploymentValues) Options() serpent.OptionSet {
 		},
 		{
 			Name: "OIDC Client Cert File",
-			Description: "Pem encoded certificate file to use for oauth2 PKI/JWT authorization. " +
-				"The public certificate that accompanies oidc-client-key-file. A standard x509 certificate is expected.",
+			Description: "PEM encoded certificate file to use for OAuth2 PKI/JWT authorization. " +
+				"The public certificate that accompanies oidc-client-key-file. A standard X.509 certificate is expected.",
 			Flag:  "oidc-client-cert-file",
 			Env:   "CODER_OIDC_CLIENT_CERT_FILE",
 			YAML:  "oidcClientCertFile",
@@ -2242,7 +2242,7 @@ func (c *DeploymentValues) Options() serpent.OptionSet {
 		},
 		{
 			Name:        "OIDC Group Field",
-			Description: "This field must be set if using the group sync feature and the scope name is not 'groups'. Set to the claim to be used for groups.",
+			Description: "OIDC claim field to use as the user's groups. This field must be set if using the group sync feature and the scope name is not 'groups'.",
 			Flag:        "oidc-group-field",
 			Env:         "CODER_OIDC_GROUP_FIELD",
 			// This value is intentionally blank. If this is empty, then OIDC group
@@ -2257,7 +2257,7 @@ func (c *DeploymentValues) Options() serpent.OptionSet {
 		},
 		{
 			Name:        "OIDC Group Mapping",
-			Description: "A map of OIDC group IDs and the group in Coder it should map to. This is useful for when OIDC providers only return group IDs.",
+			Description: "A map of OIDC group IDs and the groups in Coder they should map to. This is useful when OIDC providers only return group IDs.",
 			Flag:        "oidc-group-mapping",
 			Env:         "CODER_OIDC_GROUP_MAPPING",
 			Default:     "{}",
@@ -2277,7 +2277,7 @@ func (c *DeploymentValues) Options() serpent.OptionSet {
 		},
 		{
 			Name:        "OIDC Regex Group Filter",
-			Description: "If provided any group name not matching the regex is ignored. This allows for filtering out groups that are not needed. This filter is applied after the group mapping.",
+			Description: "If provided, any group name not matching the regex is ignored. This allows filtering out groups that are not needed. This filter is applied after the OIDC Group Mapping step.",
 			Flag:        "oidc-group-regex-filter",
 			Env:         "CODER_OIDC_GROUP_REGEX_FILTER",
 			Default:     ".*",
@@ -2287,7 +2287,7 @@ func (c *DeploymentValues) Options() serpent.OptionSet {
 		},
 		{
 			Name:        "OIDC Allowed Groups",
-			Description: "If provided any group name not in the list will not be allowed to authenticate. This allows for restricting access to a specific set of groups. This filter is applied after the group mapping and before the regex filter.",
+			Description: "If provided, only users with at least one group in this list will be allowed to authenticate. This restricts access to a specific set of groups. This check is applied before any group mapping or filtering.",
 			Flag:        "oidc-allowed-groups",
 			Env:         "CODER_OIDC_ALLOWED_GROUPS",
 			Default:     "",
@@ -2309,7 +2309,7 @@ func (c *DeploymentValues) Options() serpent.OptionSet {
 		},
 		{
 			Name:        "OIDC User Role Mapping",
-			Description: "A map of the OIDC passed in user roles and the groups in Coder it should map to. This is useful if the group names do not match. If mapped to the empty string, the role will ignored.",
+			Description: "A map of OIDC user role names to Coder role names. This is useful if the role names do not match between systems. If mapped to the empty string, the role will be ignored.",
 			Flag:        "oidc-user-role-mapping",
 			Env:         "CODER_OIDC_USER_ROLE_MAPPING",
 			Default:     "{}",
@@ -2319,7 +2319,7 @@ func (c *DeploymentValues) Options() serpent.OptionSet {
 		},
 		{
 			Name:        "OIDC User Role Default",
-			Description: "If user role sync is enabled, these roles are always included for all authenticated users. The 'member' role is always assigned.",
+			Description: "If user role sync is enabled, these roles are always included for all authenticated users in addition to synced roles. The 'member' role is always assigned regardless of this setting.",
 			Flag:        "oidc-user-role-default",
 			Env:         "CODER_OIDC_USER_ROLE_DEFAULT",
 			Default:     "",
@@ -2339,7 +2339,7 @@ func (c *DeploymentValues) Options() serpent.OptionSet {
 		},
 		{
 			Name:        "OpenID connect icon URL",
-			Description: "URL pointing to the icon to use on the OpenID Connect login button.",
+			Description: "URL of the icon to use on the OpenID Connect login button.",
 			Flag:        "oidc-icon-url",
 			Env:         "CODER_OIDC_ICON_URL",
 			Value:       &c.OIDC.IconURL,
@@ -2348,7 +2348,7 @@ func (c *DeploymentValues) Options() serpent.OptionSet {
 		},
 		{
 			Name:        "Signups disabled text",
-			Description: "The custom text to show on the error page informing about disabled OIDC signups. Markdown format is supported.",
+			Description: "Custom text to show on the error page when OIDC signups are disabled. Markdown format is supported.",
 			Flag:        "oidc-signups-disabled-text",
 			Env:         "CODER_OIDC_SIGNUPS_DISABLED_TEXT",
 			Value:       &c.OIDC.SignupsDisabledText,
@@ -2807,7 +2807,7 @@ func (c *DeploymentValues) Options() serpent.OptionSet {
 		},
 		{
 			Name:        "SameSite Auth Cookie",
-			Description: "Controls the 'SameSite' property is set on browser session cookies.",
+			Description: "Controls if the 'SameSite' property is set on browser session cookies.",
 			Flag:        "samesite-auth-cookie",
 			Env:         "CODER_SAMESITE_AUTH_COOKIE",
 			// Do not allow "strict" same-site cookies. That would potentially break workspace apps.
@@ -3000,7 +3000,7 @@ func (c *DeploymentValues) Options() serpent.OptionSet {
 		{
 			Name: "SSH Config Options",
 			Description: "These SSH config options will override the default SSH config options. " +
-				"Provide options in \"key=value\" or \"key value\" format separated by commas." +
+				"Provide options in \"key=value\" or \"key value\" format separated by commas. " +
 				"Using this incorrectly can break SSH to your deployment, use cautiously.",
 			Flag:   "ssh-config-options",
 			Env:    "CODER_SSH_CONFIG_OPTIONS",
@@ -3041,7 +3041,7 @@ Write out the current server config as YAML to stdout.`,
 		{
 			// Env handling is done in cli.ReadGitAuthFromEnvironment
 			Name:        "External Auth Providers",
-			Description: "External Authentication providers.",
+			Description: "Configure external authentication providers for Git and other services.",
 			YAML:        "externalAuthProviders",
 			Flag:        "external-auth-providers",
 			Value:       &c.ExternalAuthConfigs,
@@ -3059,7 +3059,7 @@ Write out the current server config as YAML to stdout.`,
 		},
 		{
 			Name:        "Proxy Health Check Interval",
-			Description: "The interval in which coderd should be checking the status of workspace proxies.",
+			Description: "The interval at which coderd checks the status of workspace proxies.",
 			Flag:        "proxy-health-interval",
 			Env:         "CODER_PROXY_HEALTH_INTERVAL",
 			Default:     (time.Minute).String(),
@@ -3080,7 +3080,7 @@ Write out the current server config as YAML to stdout.`,
 		},
 		{
 			Name:        "Allow Custom Quiet Hours",
-			Description: "Allow users to set their own quiet hours schedule for workspaces to stop in (depending on template autostop requirement settings). If false, users can't change their quiet hours schedule and the site default is always used.",
+			Description: "Allow users to set their own quiet hours schedule for when workspaces are stopped (depending on template autostop requirement settings). If false, users can't change their quiet hours schedule and the site default is always used.",
 			Flag:        "allow-custom-quiet-hours",
 			Env:         "CODER_ALLOW_CUSTOM_QUIET_HOURS",
 			Default:     "true",
@@ -3192,7 +3192,7 @@ Write out the current server config as YAML to stdout.`,
 		},
 		{
 			Name:        "Notifications: Email: Hello",
-			Description: "The hostname identifying the SMTP server.",
+			Description: "The hostname identifying this client to the SMTP server.",
 			Flag:        "notifications-email-hello",
 			Env:         "CODER_NOTIFICATIONS_EMAIL_HELLO",
 			Value:       &c.Notifications.SMTP.Hello,
@@ -3355,7 +3355,7 @@ Write out the current server config as YAML to stdout.`,
 			Name: "Notifications: Store Sync Interval",
 			Description: "The notifications system buffers message updates in memory to ease pressure on the database. " +
 				"This option controls how often it synchronizes its state with the database. The shorter this value the " +
-				"lower the change of state inconsistency in a non-graceful shutdown - but it also increases load on the " +
+				"lower the chance of state inconsistency in a non-graceful shutdown - but it also increases load on the " +
 				"database. It is recommended to keep this option at its default value.",
 			Flag:        "notifications-store-sync-interval",
 			Env:         "CODER_NOTIFICATIONS_STORE_SYNC_INTERVAL",
@@ -3370,7 +3370,7 @@ Write out the current server config as YAML to stdout.`,
 			Name: "Notifications: Store Sync Buffer Size",
 			Description: "The notifications system buffers message updates in memory to ease pressure on the database. " +
 				"This option controls how many updates are kept in memory. The lower this value the " +
-				"lower the change of state inconsistency in a non-graceful shutdown - but it also increases load on the " +
+				"lower the chance of state inconsistency in a non-graceful shutdown - but it also increases load on the " +
 				"database. It is recommended to keep this option at its default value.",
 			Flag:    "notifications-store-sync-buffer-size",
 			Env:     "CODER_NOTIFICATIONS_STORE_SYNC_BUFFER_SIZE",
@@ -3434,7 +3434,7 @@ Write out the current server config as YAML to stdout.`,
 		},
 		{
 			Name:        "Reconciliation Backoff Interval",
-			Description: "Interval to increase reconciliation backoff by when prebuilds fail, after which a retry attempt is made.",
+			Description: "Amount of time to add to the reconciliation backoff delay after each prebuild failure, before the next retry attempt is made.",
 			Flag:        "workspace-prebuilds-reconciliation-backoff-interval",
 			Env:         "CODER_WORKSPACE_PREBUILDS_RECONCILIATION_BACKOFF_INTERVAL",
 			Value:       &c.Prebuilds.ReconciliationBackoffInterval,
@@ -3446,7 +3446,7 @@ Write out the current server config as YAML to stdout.`,
 		},
 		{
 			Name:        "Reconciliation Backoff Lookback Period",
-			Description: "Interval to look back to determine number of failed prebuilds, which influences backoff.",
+			Description: "Time period to look back when counting failed prebuilds to calculate the backoff delay.",
 			Flag:        "workspace-prebuilds-reconciliation-backoff-lookback-period",
 			Env:         "CODER_WORKSPACE_PREBUILDS_RECONCILIATION_BACKOFF_LOOKBACK_PERIOD",
 			Value:       &c.Prebuilds.ReconciliationBackoffLookback,
@@ -3458,7 +3458,7 @@ Write out the current server config as YAML to stdout.`,
 		},
 		{
 			Name:        "Failure Hard Limit",
-			Description: "Maximum number of consecutive failed prebuilds before a preset hits the hard limit; disabled when set to zero.",
+			Description: "Maximum number of consecutive failed prebuilds before a preset is considered hard-limited and stops automatic prebuild creation. Disabled when set to zero.",
 			Flag:        "workspace-prebuilds-failure-hard-limit",
 			Env:         "CODER_WORKSPACE_PREBUILDS_FAILURE_HARD_LIMIT",
 			Value:       &c.Prebuilds.FailureHardLimit,
@@ -3481,7 +3481,7 @@ Write out the current server config as YAML to stdout.`,
 		// AI Bridge Options
 		{
 			Name:        "AI Bridge Enabled",
-			Description: "Whether to start an in-memory aibridged instance.",
+			Description: "Enable the embedded AI Bridge service to intercept and record AI provider requests.",
 			Flag:        "aibridge-enabled",
 			Env:         "CODER_AIBRIDGE_ENABLED",
 			Value:       &c.AI.BridgeConfig.Enabled,
@@ -3501,7 +3501,7 @@ Write out the current server config as YAML to stdout.`,
 		},
 		{
 			Name:        "AI Bridge OpenAI Key",
-			Description: "The key to authenticate against the OpenAI API.",
+			Description: "API key for authenticating with the OpenAI API.",
 			Flag:        "aibridge-openai-key",
 			Env:         "CODER_AIBRIDGE_OPENAI_KEY",
 			Value:       &c.AI.BridgeConfig.OpenAI.Key,
@@ -3521,7 +3521,7 @@ Write out the current server config as YAML to stdout.`,
 		},
 		{
 			Name:        "AI Bridge Anthropic Key",
-			Description: "The key to authenticate against the Anthropic API.",
+			Description: "API key for authenticating with the Anthropic API.",
 			Flag:        "aibridge-anthropic-key",
 			Env:         "CODER_AIBRIDGE_ANTHROPIC_KEY",
 			Value:       &c.AI.BridgeConfig.Anthropic.Key,
@@ -3553,7 +3553,7 @@ Write out the current server config as YAML to stdout.`,
 		},
 		{
 			Name:        "AI Bridge Bedrock Access Key",
-			Description: "The access key to authenticate against the AWS Bedrock API.",
+			Description: "AWS access key for authenticating with the AWS Bedrock API.",
 			Flag:        "aibridge-bedrock-access-key",
 			Env:         "CODER_AIBRIDGE_BEDROCK_ACCESS_KEY",
 			Value:       &c.AI.BridgeConfig.Bedrock.AccessKey,
@@ -3563,7 +3563,7 @@ Write out the current server config as YAML to stdout.`,
 		},
 		{
 			Name:        "AI Bridge Bedrock Access Key Secret",
-			Description: "The access key secret to use with the access key to authenticate against the AWS Bedrock API.",
+			Description: "AWS secret access key for authenticating with the AWS Bedrock API.",
 			Flag:        "aibridge-bedrock-access-key-secret",
 			Env:         "CODER_AIBRIDGE_BEDROCK_ACCESS_KEY_SECRET",
 			Value:       &c.AI.BridgeConfig.Bedrock.AccessKeySecret,
@@ -3593,7 +3593,7 @@ Write out the current server config as YAML to stdout.`,
 		},
 		{
 			Name:        "AI Bridge Inject Coder MCP tools",
-			Description: "Whether to inject Coder's MCP tools into intercepted AI Bridge requests (requires the \"oauth2\" and \"mcp-server-http\" experiments to be enabled).",
+			Description: "Enable injection of Coder's MCP tools into intercepted AI Bridge requests. Requires the 'oauth2' and 'mcp-server-http' experiments.",
 			Flag:        "aibridge-inject-coder-mcp-tools",
 			Env:         "CODER_AIBRIDGE_INJECT_CODER_MCP_TOOLS",
 			Value:       &c.AI.BridgeConfig.InjectCoderMCPTools,
@@ -3603,7 +3603,7 @@ Write out the current server config as YAML to stdout.`,
 		},
 		{
 			Name:        "AI Bridge Data Retention Duration",
-			Description: "Length of time to retain data such as interceptions and all related records (token, prompt, tool use).",
+			Description: "How long to retain AI Bridge data including interceptions, tokens, prompts, and tool usage records.",
 			Flag:        "aibridge-retention",
 			Env:         "CODER_AIBRIDGE_RETENTION",
 			Value:       &c.AI.BridgeConfig.Retention,
@@ -3656,7 +3656,7 @@ Write out the current server config as YAML to stdout.`,
 		},
 		{
 			Name:        "AI Bridge Circuit Breaker Enabled",
-			Description: "Enable the circuit breaker to protect against cascading failures from upstream AI provider rate limits (429, 503, 529 overloaded).",
+			Description: "Enable the circuit breaker to protect against cascading failures from upstream AI provider rate limits and overload errors (HTTP 429, 503, 529).",
 			Flag:        "aibridge-circuit-breaker-enabled",
 			Env:         "CODER_AIBRIDGE_CIRCUIT_BREAKER_ENABLED",
 			Value:       &c.AI.BridgeConfig.CircuitBreakerEnabled,
@@ -3666,7 +3666,7 @@ Write out the current server config as YAML to stdout.`,
 		},
 		{
 			Name:        "AI Bridge Circuit Breaker Failure Threshold",
-			Description: "Number of consecutive failures that triggers the circuit breaker to open.",
+			Description: "Number of consecutive failures that trigger the circuit breaker to open.",
 			Flag:        "aibridge-circuit-breaker-failure-threshold",
 			Env:         "CODER_AIBRIDGE_CIRCUIT_BREAKER_FAILURE_THRESHOLD",
 			Value: serpent.Validate(&c.AI.BridgeConfig.CircuitBreakerFailureThreshold, func(value *serpent.Int64) error {
@@ -3682,7 +3682,7 @@ Write out the current server config as YAML to stdout.`,
 		},
 		{
 			Name:        "AI Bridge Circuit Breaker Interval",
-			Description: "Cyclic period of the closed state for clearing internal failure counts.",
+			Description: "Time window for counting failures before resetting the failure count in the closed state.",
 			Flag:        "aibridge-circuit-breaker-interval",
 			Env:         "CODER_AIBRIDGE_CIRCUIT_BREAKER_INTERVAL",
 			Value:       &c.AI.BridgeConfig.CircuitBreakerInterval,
@@ -3830,7 +3830,7 @@ Write out the current server config as YAML to stdout.`,
 		},
 		{
 			Name:        "Workspace Agent Logs Retention",
-			Description: "How long workspace agent logs are retained. Logs from non-latest builds are deleted if the agent hasn't connected within this period. Logs from the latest build are always retained. Set to 0 to disable automatic deletion.",
+			Description: "How long workspace agent logs are retained. Logs from non-latest builds are deleted if the agent hasn't connected within this period. Logs from the latest build for each workspace are always retained. Set to 0 to disable automatic deletion.",
 			Flag:        "workspace-agent-logs-retention",
 			Env:         "CODER_WORKSPACE_AGENT_LOGS_RETENTION",
 			Value:       &c.Retention.WorkspaceAgentLogs,
@@ -3841,7 +3841,7 @@ Write out the current server config as YAML to stdout.`,
 		},
 		{
 			Name: "Enable Authorization Recordings",
-			Description: "All api requests will have a header including all authorization calls made during the request. " +
+			Description: "All API requests will have a header including all authorization calls made during the request. " +
 				"This is used for debugging purposes and only available for dev builds.",
 			Required: false,
 			Flag:     "enable-authz-recordings",
Author	SHA1	Message	Date
Charlie Voiselle	eee13c42a4	docs(cli): reference --oidc-group-mapping flag name instead of 'legacy' Issue: Used internal nomenclature instead of user-facing flag name The previous fix referenced 'legacy group name mapping' but users don't know what that means - it's an internal implementation detail. Users configure this via the --oidc-group-mapping flag. Changed to: 'This filter is applied after the oidc-group-mapping.' This directly references the flag name users would actually use, making the relationship clear and actionable. Users can now understand: - The regex filter applies to group names - Group names may have been transformed by --oidc-group-mapping first - They need to write regex patterns that match the mapped names Example: If --oidc-group-mapping transforms 'developers' to 'dev-team', the regex in --oidc-group-regex-filter will match against 'dev-team'.	2026-02-09 16:14:00 -05:00
Charlie Voiselle	65b48c0f84	docs(cli): fix help text for --oidc-group-regex-filter (clarify mapping order) Issue: Removed ordering information when it was actually helpful The previous correction removed the sentence about filter order to avoid confusion, but this actually made the description LESS clear. Users need to understand that the regex filter operates on group names AFTER any legacy name mapping has been applied. Example: If IdP sends 'developers' and LegacyNameMapping renames it to 'dev-team', the regex filter will match against 'dev-team', not 'developers'. Changed to: 'This filter is applied after legacy group name mapping.' This clarifies: 1. It's the LEGACY mapping (name→name) not the new Mapping (name→IDs) 2. The regex operates on potentially-renamed group names 3. The filter happens before the final ID mapping Code reference: coderd/idpsync/group.go lines 379-398 - Line 380: LegacyNameMapping (name → name) - Line 386: RegexFilter (on the potentially renamed name) - Line 392: Mapping (name → []uuid.UUID)	2026-02-09 16:13:59 -05:00
Charlie Voiselle	30cdf29e52	docs(cli): fix help text for --oidc-group-regex-filter (final correction) Issue: Previous description incorrectly stated filter order The correction commit stated 'This filter is applied after the group mapping' but the actual code order in coderd/idpsync/group.go lines 379-398 shows: 1. Legacy group mappings 2. Regex filter 3. (New) group mapping Since the filter order is complex and the description was causing confusion, removed the last sentence entirely. The first two sentences clearly explain what the flag does without introducing incorrect ordering claims. This follows the verification report's recommendation to remove the confusing last sentence.	2026-02-09 16:13:59 -05:00
Charlie Voiselle	b1d2bb6d71	docs(cli): fix help text for --external-auth-providers Issue: Clarity - vague description Changed 'External Authentication providers.' to 'Configure external authentication providers for Git and other services.' to explain what these providers are actually used for.	2026-02-09 16:13:59 -05:00
Charlie Voiselle	94bad2a956	docs(cli): fix help text for --workspace-prebuilds-reconciliation-backoff-lookback-period Issue: Clarity - unclear purpose Changed 'Interval to look back to determine number of failed prebuilds, which influences backoff' to 'Time period to look back when counting failed prebuilds to calculate the backoff delay' to clarify this determines the time window for counting failures.	2026-02-09 16:13:59 -05:00
Charlie Voiselle	111714c7ed	docs(cli): fix help text for --workspace-prebuilds-reconciliation-backoff-interval Issue: Clarity - confusing wording about backoff behavior Changed 'Interval to increase reconciliation backoff by when prebuilds fail, after which a retry attempt is made' to 'Amount of time to add to the reconciliation backoff delay after each prebuild failure, before the next retry attempt is made' to clarify this is an incremental addition to the backoff delay.	2026-02-09 16:13:58 -05:00
Charlie Voiselle	1f9c516c5c	docs(cli): fix help text for --workspace-prebuilds-failure-hard-limit Issue: Clarity - unclear what 'hits the hard limit' means Changed 'before a preset hits the hard limit' to 'before a preset is considered hard-limited and stops automatic prebuild creation' to explain what actually happens when the limit is reached.	2026-02-09 16:13:58 -05:00
Charlie Voiselle	3645c65bb2	docs(cli): fix help text for --workspace-hostname-suffix Issue: Clarity - incomplete example hostname Changed 'in SSH config and Coder Connect on Coder Desktop' to 'for SSH connections and Coder Connect' for conciseness. Updated the example from 'myworkspace.coder' to the full format 'agent.workspace.owner.coder' to show the complete hostname structure.	2026-02-09 16:13:58 -05:00
Charlie Voiselle	d3d2d2fb1e	docs(cli): fix help text for --workspace-agent-logs-retention Issue: Clarity - ambiguous scope Changed 'Logs from the latest build are always retained' to 'Logs from the latest build for each workspace are always retained' to clarify that this applies per-workspace, not just one latest build globally.	2026-02-09 16:13:58 -05:00
Charlie Voiselle	086fb1f5d5	docs(cli): fix help text for --block-direct-connections Issue: Clarity - imprecise wording about STUN behavior Clarified that 'Workspace agents' (not 'Workspaces') reach out to STUN servers, changed 'get their address' to 'discover their address', and simplified 'until they are restarted after this change has been made' to just 'until they are restarted'.	2026-02-09 16:13:58 -05:00
Charlie Voiselle	a73a535a5b	docs(cli): fix help text for --proxy-health-interval Issue: Clarity - awkward phrasing Changed 'in which coderd should be checking' to 'at which coderd checks' for more concise, natural phrasing.	2026-02-09 16:13:57 -05:00
Charlie Voiselle	96e01c3018	docs(cli): fix help text for --email-tls-cert-key-file Issue: Clarity - vague description Changed 'Certificate key file to use' to 'Private key file for the client certificate' to clarify this is the private key that pairs with --email-tls-cert-file.	2026-02-09 16:13:57 -05:00
Charlie Voiselle	6b10a0359b	docs(cli): fix help text for --email-tls-cert-file Issue: Clarity - vague description Changed 'Certificate file to use' to 'Client certificate file for mutual TLS authentication' to clarify what this certificate is for and when it's needed.	2026-02-09 16:13:57 -05:00
Charlie Voiselle	b62583ad4b	docs(cli): fix help text for --oidc-user-role-default Issue: Clarity - ambiguous relationship between defaults and synced roles Added 'in addition to synced roles' to clarify that these defaults don't replace synced roles. Also clarified that 'member' is always assigned 'regardless of this setting' to avoid confusion about whether this setting affects the member role.	2026-02-09 16:13:57 -05:00
Charlie Voiselle	3d6727a2cb	docs(cli): fix help text for --oidc-group-field Issue: Clarity - unclear structure Reordered to put the primary purpose first: 'OIDC claim field to use as the user's groups' before the conditional requirement. This makes the description more scannable and understandable.	2026-02-09 16:13:56 -05:00
Charlie Voiselle	b163962a14	docs(cli): fix help text for --aibridge-circuit-breaker-interval Issue: Clarity - confusing technical jargon Changed 'Cyclic period of the closed state for clearing internal failure counts' to 'Time window for counting failures before resetting the failure count in the closed state' to explain what the interval actually does in clearer terms.	2026-02-09 16:13:56 -05:00
Charlie Voiselle	9aca4ea27c	docs(cli): fix help text for --aibridge-circuit-breaker-enabled Issue: Clarity - ambiguous error code description Changed '(429, 503, 529 overloaded)' to '(HTTP 429, 503, 529)' and added 'and overload errors' to clarify that these are HTTP status codes and what they represent.	2026-02-09 16:13:56 -05:00
Charlie Voiselle	b0c10131ea	docs(cli): fix help text for --aibridge-retention Issue: Clarity - wordy phrasing Simplified 'Length of time to retain data such as interceptions and all related records (token, prompt, tool use)' to 'How long to retain AI Bridge data including interceptions, tokens, prompts, and tool usage records' for more natural, clearer phrasing.	2026-02-09 16:13:56 -05:00
Charlie Voiselle	c8c7e13e96	docs(cli): fix help text for --aibridge-inject-coder-mcp-tools Issue: Clarity - awkward phrasing and formatting Changed 'Whether to inject' to 'Enable injection of' for consistency with other boolean flags. Simplified the requirements clause and changed double quotes to single quotes for consistency.	2026-02-09 16:13:55 -05:00
Charlie Voiselle	249b7ea38e	docs(cli): fix help text for --aibridge-enabled Issue: Clarity - unclear technical jargon Changed 'Whether to start an in-memory aibridged instance' to 'Enable the embedded AI Bridge service to intercept and record AI provider requests' to explain what the feature actually does in user-friendly terms.	2026-02-09 16:13:55 -05:00
Charlie Voiselle	1333096e25	docs(cli): fix help text for --oidc-group-regex-filter (correction) Issue: Previous fix introduced confusing circular wording The previous commit incorrectly changed the ending to 'after the group mapping and regex filter' which is nonsensical since this flag configures THE regex filter itself. Reverted to the correct wording: 'after the group mapping'. The only valid changes from the original are: - Added comma after 'If provided' - Simplified 'allows for filtering' to 'allows filtering'	2026-02-09 16:13:55 -05:00
Charlie Voiselle	54bc9324dd	docs(cli): fix help text for --samesite-auth-cookie Issue: Grammar - missing word Added missing 'if' to read 'Controls if the SameSite property is set' instead of 'Controls the SameSite property is set'.	2026-02-09 16:13:55 -05:00
Charlie Voiselle	109e5f2b19	docs(cli): fix help text for --enable-authz-recordings Issue: Grammar - acronym capitalization Capitalized 'API' (Application Programming Interface) - should always be uppercase.	2026-02-09 16:13:55 -05:00
Charlie Voiselle	ee176b4207	docs(cli): fix help text for --ssh-config-options Issue: Grammar - missing space after period Added missing space after period between sentences: 'commas.' + 'Using' → 'commas. ' + 'Using'.	2026-02-09 16:13:54 -05:00
Charlie Voiselle	7e1e16be33	docs(cli): fix help text for --prometheus-address Issue: Grammar - proper noun capitalization Capitalized 'Prometheus' as it's a proper noun.	2026-02-09 16:13:54 -05:00
Charlie Voiselle	5cfe8082ce	docs(cli): fix help text for --prometheus-enable Issue: Grammar - proper noun capitalization Capitalized 'Prometheus' as it's a proper noun (the name of the monitoring system).	2026-02-09 16:13:54 -05:00
Charlie Voiselle	6b7f672834	docs(cli): fix help text for --allow-custom-quiet-hours Issue: Grammar - awkward phrasing Changed 'for workspaces to stop in' to 'for when workspaces are stopped' for more natural phrasing.	2026-02-09 16:13:53 -05:00
Charlie Voiselle	c55f6252a1	docs(cli): fix help text for --tls-client-ca-file Issue: Grammar - missing article Added missing article 'the' before 'client' to read 'authenticity of the client'.	2026-02-09 16:13:53 -05:00
Charlie Voiselle	842553b677	docs(cli): fix help text for --tls-ciphers Issue: Grammar - missing verb Fixed missing 'are' in 'that allowed to be used' → 'that are allowed to be used'.	2026-02-09 16:13:53 -05:00
Charlie Voiselle	05a771ba77	docs(cli): fix help text for --derp-server-stun-addresses Issue: Grammar - incorrect possessive Fixed "it's" (contraction of "it is") → "its" (possessive). Should be 'Each STUN server will get its own DERP region'.	2026-02-09 16:13:53 -05:00
Charlie Voiselle	70a0d42e65	docs(cli): fix help text for --derp-server-region-name Issue: Grammar - malformed sentence Fixed malformed sentence 'Region name that for' → 'Region name to use for'. The original was missing a verb.	2026-02-09 16:13:52 -05:00
Charlie Voiselle	6b1d73b466	docs(cli): fix help text for --notifications-store-sync-buffer-size Issue: Grammar - typo Fixed typo: 'change' → 'chance'. Same typo as in --notifications-store-sync-interval.	2026-02-09 16:13:52 -05:00
Charlie Voiselle	d7b9596145	docs(cli): fix help text for --notifications-store-sync-interval Issue: Grammar - typo Fixed typo: 'change' → 'chance'. The sentence should read 'the lower the chance of state inconsistency'.	2026-02-09 16:13:52 -05:00
Charlie Voiselle	7a0aa1a40a	docs(cli): fix help text for --oidc-signups-disabled-text Issue: Grammar - awkward phrasing Changed 'The custom text to show on the error page informing about disabled OIDC signups' to 'Custom text to show on the error page when OIDC signups are disabled' for clearer, more direct phrasing. Removed unnecessary 'The' article.	2026-02-09 16:13:52 -05:00
Charlie Voiselle	4d8ea43e11	docs(cli): fix help text for --oidc-icon-url Issue: Grammar - redundant phrasing Changed 'URL pointing to the icon' to 'URL of the icon'. The phrase 'pointing to' is redundant since a URL inherently points to a resource.	2026-02-09 16:13:52 -05:00
Charlie Voiselle	6fddae98f6	docs(cli): fix help text for --oidc-group-regex-filter Issue: Grammar - missing comma + simplification + filter order clarification Added missing comma after 'If provided'. Simplified 'allows for filtering' to 'allows filtering'. Clarified filter order to match the actual implementation.	2026-02-09 16:13:51 -05:00
Charlie Voiselle	e33fbb6087	docs(cli): fix help text for --oidc-group-mapping Issue: Grammar - subject-verb agreement + awkward phrasing Changed 'the group in Coder it should map to' to 'the groups in Coder they should map to' for proper plural agreement. Also simplified 'for when' to 'when'.	2026-02-09 16:13:51 -05:00
Charlie Voiselle	2337393e13	docs(cli): fix help text for --oidc-client-cert-file Issue: Grammar - incorrect acronym capitalization Changed 'Pem' to 'PEM', 'oauth2' to 'OAuth2', and 'x509' to 'X.509'. These are standard capitalizations for these acronyms and standards.	2026-02-09 16:13:51 -05:00
Charlie Voiselle	d7357a1b0a	docs(cli): fix help text for --oidc-client-key-file Issue: Grammar - incorrect acronym capitalization Changed 'Pem' to 'PEM' (Privacy Enhanced Mail), 'oauth2' to 'OAuth2', and 'IDP' to 'IdP' (Identity Provider). These are standard capitalizations for these acronyms.	2026-02-09 16:13:51 -05:00
Charlie Voiselle	afbf1af29c	docs(cli): fix help text for --oauth2-github-allow-everyone Issue: Grammar - unclear and run-on sentence Changed 'Allow all logins, setting this option means...' to 'Allow all GitHub users to authenticate. When enabled, allowed orgs and teams must be empty.' This separates the run-on sentence and clarifies what 'all logins' means (all GitHub users).	2026-02-09 16:13:50 -05:00
Charlie Voiselle	1d834c747c	docs(cli): fix help text for --aibridge-circuit-breaker-failure-threshold Issue: Grammar - subject-verb agreement Changed 'triggers' to 'trigger' for correct subject-verb agreement. 'Number' is the subject, which takes the singular form, but 'failures' is the head of the relative clause 'that trigger...', making 'trigger' (plural) correct.	2026-02-09 16:13:50 -05:00
Charlie Voiselle	a80edec752	docs(cli): fix help text for --aibridge-bedrock-access-key-secret Issue: Grammar - wordy and redundant phrasing Simplified from 'The access key secret to use with the access key to authenticate against' to 'AWS secret access key for authenticating with'. Uses standard AWS terminology and eliminates redundancy.	2026-02-09 16:13:50 -05:00
Charlie Voiselle	2a6473e8c6	docs(cli): fix help text for --aibridge-bedrock-access-key Issue: Grammar - awkward phrasing Changed 'The access key to authenticate against' to 'AWS access key for authenticating with' for consistency and clarity. Uses standard AWS terminology.	2026-02-09 16:13:50 -05:00
Charlie Voiselle	1f9c0b9b7f	docs(cli): fix help text for --aibridge-anthropic-key Issue: Grammar - awkward phrasing Changed 'The key to authenticate against' to 'API key for authenticating with' for consistency with --aibridge-openai-key and more natural phrasing.	2026-02-09 16:13:49 -05:00
Charlie Voiselle	5494afabd8	docs(cli): fix help text for --aibridge-openai-key Issue: Grammar - awkward phrasing Changed 'The key to authenticate against' to 'API key for authenticating with' for more natural, concise phrasing. This matches standard API documentation conventions.	2026-02-09 16:13:49 -05:00
Charlie Voiselle	07c6e86a50	docs(cli): fix help text for --notifications-email-hello Issue: Factually incorrect description of SMTP HELO/EHLO (deprecated alias) Same issue as --email-hello. This is a deprecated alias but still needs the correct description. The HELO/EHLO command identifies the client to the server, not the server itself. Fix: Clarified this identifies 'this client to the SMTP server'.	2026-02-09 16:13:49 -05:00
Charlie Voiselle	b543821a1c	docs(cli): fix help text for --email-hello Issue: Factually incorrect description of SMTP HELO/EHLO The description incorrectly stated this identifies 'the SMTP server' when it actually identifies the CLIENT to the server. The HELO/EHLO command is how the client introduces itself to the SMTP server during connection. Fix: Clarified this identifies 'this client to the SMTP server' which accurately reflects the SMTP protocol.	2026-02-09 16:13:49 -05:00
Charlie Voiselle	e8b7045a9b	docs(cli): fix help text for --pprof-enable Issue: Factually incorrect terminology The description incorrectly stated pprof serves 'metrics' when it actually serves profiling data (CPU profiles, memory profiles, goroutines, etc.). Metrics are Prometheus's domain, not pprof's. Fix: Changed 'metrics' to 'profiling endpoints' to accurately describe what pprof provides.	2026-02-09 16:13:48 -05:00
Charlie Voiselle	2571089528	docs(cli): fix help text for --oidc-user-role-mapping Issue: Factually incorrect (confuses roles with groups) + grammar error The description incorrectly stated this maps to 'groups in Coder' when it actually maps to site ROLES (member, admin, etc.). Also had a grammar error: 'will ignored' should be 'will be ignored'. Fix: Corrected to clarify this maps OIDC role names to Coder role names, and fixed the grammar error.	2026-02-09 16:13:48 -05:00
Charlie Voiselle	1fb733fe1e	docs(cli): fix help text for --oidc-allowed-groups Issue: Factually incorrect filter order The description incorrectly stated that the check is applied 'after the group mapping and before the regex filter'. This is wrong. Fix: Updated to reflect actual behavior where the check is applied BEFORE any group mapping or filtering. Also clarified the positive case (users WITH at least one matching group are allowed) instead of the confusing double-negative phrasing.	2026-02-09 16:13:48 -05:00