fix(docs): show deprecated flags in the generated reference tables

[mbevc1]

pflag's MarkDeprecated sets both Deprecated and Hidden, and CommandsInTable returned early on Hidden. Deprecated-but-working flags were therefore absent from every generated reference page, along with the migration advice their messages already carry -- the only signal was a stderr warning. The (DEPRECATED: ...) rendering further down the same function had never executed.

Skip a flag only when it is hidden without being deprecated, so MarkHidden's intent is preserved for internal aliases (--yes on the delete commands, --flow/--attestations on evaluate input, --attachments on attest override) while MarkDeprecated's flags are documented.

The flags table is alphabetical, so deprecated rows land next to their replacements: --cluster above --clusters, --function-name above --function-names, --service-name above --services.

Scope is the published reference only. pflag has its own Hidden check in FlagUsagesWrapped, so kosli <cmd> --help still omits these flags.

28 of 94 generated pages now carry a deprecated row. The two docs golden files gain one row each for --registry-provider, which comes from the shared addFingerprintFlags helper.

Closes #1060

Checklist

• Docs are autogenerated from CLI help — make sure the help text reflects your changes
• Helm chart (charts/k8s-reporter/) updated, if needed. Note: these changes live in a separate PR
• Terraform provider and related changes (terraform-provider-kosli, terraform-aws-evidence-reporter, terraform-aws-kosli-reporter) updated, if needed

[claude]

Claude finished @mbevc1's task in 1m 47s —— View job

---

PR Review — show deprecated flags in generated reference tables

• Gather context (read diff + files)
• Static analysis (build, vet)
• Review code quality, edge cases, bugs
• Review tests
• Post review

---

Verdict: LGTM. Small, well-scoped fix with a clear root cause and matching tests. I'd merge this.

What the change does

pflag.MarkDeprecated sets Hidden as a side effect, so CommandsInTable's early if flag.Hidden return was silently dropping deprecated-but-working flags — and the (DEPRECATED: ...) suffix at helpers.go:74 was dead code. Gating on flag.Hidden && flag.Deprecated == "" is exactly the right predicate.

Correctness ✅

I verified the two hiding mechanisms are correctly distinguished:

• Explicitly hidden flags set Hidden=true without a deprecation message and are still skipped — confirmed for the internal aliases the PR describes:
  • evaluateInput.go:99-100 (--flow, --attestations)
  • deleteApiKey.go:76, deleteServiceAccount.go:72 (--yes)
  • attestOverride.go:115 (--attachments via MarkHidden)
• Deprecated flags (snapshotAutoEnvironment.go:44, createFlow.go:95, cli_utils.go:298) now render with their migration message. 👍
• --help behaviour is untouched — pflag's own Hidden check in FlagUsagesWrapped still hides these, so scope really is published-reference-only as claimed.

Static analysis

• go build ./... ✅
• go vet ./internal/docgen/... ✅
• go test ./internal/docgen/... — could not run (command needs approval in this sandbox), but the new tests read correctly and the logic is straightforward. Worth confirming in CI.

Tests ✅

Nice touch pairing TestCommandsInTableHiddenFlags / TestCommandsInTableDeprecatedFlags with a comment explaining they're two sides of the same predicate. The deprecated test asserts on the flag, the (DEPRECATED: ...) suffix, and the replacement flag — good coverage of the actual regression.

Minor notes (non-blocking)

1. Hidden + deprecated can't be expressed. If a future flag is MarkDeprecated'd and the author wants it out of the docs, the predicate can't capture that — deprecation always wins. No such flag exists today, and the code comment documents the intent well, so this is just something to keep in mind. If it ever comes up, an explicit annotation would be cleaner than relying on Hidden.
2. Golden coverage. Only artifact.md and snyk.md are golden-tested (both correctly updated here for --registry-provider via addFingerprintFlags). The other ~26 affected pages the PR mentions aren't golden-tested — that's a pre-existing property of the test setup, not a regression, but it means those pages rely on the publish-time generation being re-run.
   • 20260730_deprecated_flags