diff --git a/cmd/kosli/testdata/output/docs/mintlify/artifact.md b/cmd/kosli/testdata/output/docs/mintlify/artifact.md
index 2fbcbe070..8e4281853 100644
--- a/cmd/kosli/testdata/output/docs/mintlify/artifact.md
+++ b/cmd/kosli/testdata/output/docs/mintlify/artifact.md
@@ -59,6 +59,7 @@ is set), registry credentials are resolved as follows:
 |    `-h`, `--help`  |  help for artifact  |
 |    `-n`, `--name` string  |  [optional] Artifact display name, if different from file, image or directory name.  |
 |        `--registry-password` string  |  [conditional] The container registry password or access token. Only required if you want to read container image SHA256 digest from a remote container registry and it is not already accessible via Docker/Podman auth files or a credential helper.  |
+|        `--registry-provider` string  |  [deprecated] The docker registry provider or url. Only required if you want to read docker image SHA256 digest from a remote docker registry. (DEPRECATED: no longer used)  |
 |        `--registry-username` string  |  [conditional] The container registry username. Only required if you want to read container image SHA256 digest from a remote container registry and it is not already accessible via Docker/Podman auth files or a credential helper.  |
 |        `--repo-root` string  |  [defaulted] The directory where the source git repository is available. (default ".")  |
 
diff --git a/cmd/kosli/testdata/output/docs/mintlify/snyk.md b/cmd/kosli/testdata/output/docs/mintlify/snyk.md
index 99112d8d1..acefdf5d8 100644
--- a/cmd/kosli/testdata/output/docs/mintlify/snyk.md
+++ b/cmd/kosli/testdata/output/docs/mintlify/snyk.md
@@ -51,6 +51,7 @@ In other CI systems, set them explicitly to capture repository metadata.
 |    `-o`, `--origin-url` string  |  [optional] The url pointing to where the attestation came from or is related. (defaulted to the CI url in some CIs: [docs](/integrations/ci_cd/#defaulted-kosli-command-flags-from-ci-variables) ).  |
 |        `--redact-commit-info` strings  |  [optional] The list of commit info to be redacted before sending to Kosli. Allowed values are one or more of [author, message, branch].  |
 |        `--registry-password` string  |  [conditional] The container registry password or access token. Only required if you want to read container image SHA256 digest from a remote container registry and it is not already accessible via Docker/Podman auth files or a credential helper.  |
+|        `--registry-provider` string  |  [deprecated] The docker registry provider or url. Only required if you want to read docker image SHA256 digest from a remote docker registry. (DEPRECATED: no longer used)  |
 |        `--registry-username` string  |  [conditional] The container registry username. Only required if you want to read container image SHA256 digest from a remote container registry and it is not already accessible via Docker/Podman auth files or a credential helper.  |
 |        `--repo-id` string  |  [conditional] The stable, unique identifier for the repository in your VCS provider (e.g. a numeric ID). Do not use the repository name as it can change if the repo is renamed. All three of `--repo-id`, `--repo-url` and `--repository` must be set to record repository information (defaulted in some CIs: [docs](/integrations/ci_cd) ).  |
 |        `--repo-provider` string  |  [optional] The source code hosting provider. One of: github, gitlab, bitbucket, bitbucket_cloud, bitbucket_dc, azure-devops, azure_devops_services, azure_devops_server, git, subversion (defaulted in some CIs: [docs](/integrations/ci_cd) ).  |
diff --git a/internal/docgen/helpers.go b/internal/docgen/helpers.go
index ffdaf8d23..32f1c2e87 100644
--- a/internal/docgen/helpers.go
+++ b/internal/docgen/helpers.go
@@ -19,7 +19,12 @@ func CommandsInTable(f *pflag.FlagSet) string {
 
 	maxlen := 0
 	f.VisitAll(func(flag *pflag.Flag) {
-		if flag.Hidden {
+		// pflag.MarkDeprecated sets Hidden as a side effect, which would keep
+		// deprecated-but-working flags out of the reference docs along with
+		// their migration message. Only flags hidden on purpose (MarkHidden,
+		// e.g. internal aliases) are skipped; deprecated ones are documented
+		// below with a (DEPRECATED: ...) suffix.
+		if flag.Hidden && flag.Deprecated == "" {
 			return
 		}
 
diff --git a/internal/docgen/helpers_test.go b/internal/docgen/helpers_test.go
index a2fb8ef90..20f4d34a8 100644
--- a/internal/docgen/helpers_test.go
+++ b/internal/docgen/helpers_test.go
@@ -27,6 +27,9 @@ func TestCommandsInTable(t *testing.T) {
 	}
 }
 
+// TestCommandsInTableHiddenFlags and TestCommandsInTableDeprecatedFlags are a
+// pair: a flag hidden via MarkHidden stays out of the docs, while a flag hidden
+// as a side effect of MarkDeprecated is documented with its migration message.
 func TestCommandsInTableHiddenFlags(t *testing.T) {
 	fs := pflag.NewFlagSet("test", pflag.ContinueOnError)
 	fs.String("visible", "", "Visible flag")
@@ -42,6 +45,25 @@ func TestCommandsInTableHiddenFlags(t *testing.T) {
 	}
 }
 
+func TestCommandsInTableDeprecatedFlags(t *testing.T) {
+	fs := pflag.NewFlagSet("test", pflag.ContinueOnError)
+	fs.String("new", "", "The replacement flag")
+	fs.String("old", "", "The superseded flag")
+	// MarkDeprecated also sets Hidden, which used to keep the flag out of the docs.
+	_ = fs.MarkDeprecated("old", "use --new instead")
+
+	got := CommandsInTable(fs)
+	if !strings.Contains(got, "--old") {
+		t.Errorf("expected deprecated flag to be documented, got:\n%s", got)
+	}
+	if !strings.Contains(got, "(DEPRECATED: use --new instead)") {
+		t.Errorf("expected deprecation message, got:\n%s", got)
+	}
+	if !strings.Contains(got, "--new") {
+		t.Errorf("expected replacement flag, got:\n%s", got)
+	}
+}
+
 func TestCommandsInTableDefaultValues(t *testing.T) {
 	fs := pflag.NewFlagSet("test", pflag.ContinueOnError)
 	fs.String("dir", "/tmp", "The directory")