fix: deprecated flags are missing from the reference docs

[dangrondahl]

Problem

Deprecated flags do not appear anywhere in our reference docs. For example
https://docs.kosli.com/client_reference/kosli_snapshot_ecs documents --clusters and
--services but not the deprecated --cluster or --service-name, and
https://docs.kosli.com/client_reference/kosli_create_environment omits
--require-provenance. Across all 80+ generated pages the string DEPRECATED never
appears, for any of the 9 currently-deprecated flag registrations.

The cause is pflag's MarkDeprecated, which does two things
(pflag@v1.0.10/flag.go:442-443):

flag.Deprecated = usageMessage
flag.Hidden     = true

The flag keeps working and prints a warning to stderr when passed, but the
Hidden side effect removes it from the generated docs via the early return at
internal/docgen/helpers.go:22.

Side effects

1. Users cannot discover the replacement. Someone with --cluster in a running
   ECS pipeline searches the docs, finds only --clusters, and has no way to tell
   whether their flag is deprecated, removed, or a typo they got away with. The only
   signal is a stderr warning, which in CI is precisely where nobody reads it.
2. Migration advice we have already written is stranded. The messages carry the
   answer - --cluster says "use --clusters instead", --require-provenance says
   "use policies instead", --function-name says "use --function-names instead" -
   and none of it reaches a docs reader.
3. There is no inventory of what is deprecated. You cannot find out without
   grepping Go source. That makes deprecations invisible to anyone outside the CLI
   codebase, including whoever eventually has to plan their removal (breaking: remove deprecated flags in v3 #1059).
4. The rendering code exists but is unreachable. docgen/helpers.go:69 already
   renders (DEPRECATED: <message>) into the flags table. It has never executed,
   because line 22 returns first and MarkDeprecated always sets Hidden. That
   strongly suggests visible-but-labelled was the original intent and the
   MarkDeprecated shortcut quietly defeated it.

Proposed fix

One condition at internal/docgen/helpers.go:22:

if flag.Hidden && flag.Deprecated == "" {
    return
}

This is deliberately narrower than unhiding everything. There is exactly one flag
hidden on purpose without being deprecated - --attachments on attest override
(attestOverride.go:115, via MarkHidden) - and it must stay out of the docs. The
condition preserves MarkHidden's intent while making MarkDeprecated's flags
visible, and it makes line 69 reachable for the first time. No new rendering code is
needed.

Nice property: the flags table is alphabetical, so deprecated rows land next to their
replacements - --cluster beside --clusters, --e beside --exclude.

Scope note: this fixes docs, not --help

pflag has its own Hidden check in FlagUsagesWrapped (flag.go:714), separate
from docgen's. So this change makes deprecated flags visible in the published
reference only; kosli <cmd> --help will still omit them. Making them visible in
--help too would mean not relying on MarkDeprecated's hiding at all (set
flag.Deprecated directly and leave Hidden false), which is a larger and more
invasive change. Worth deciding whether docs-only is enough.

Work

• The one-line condition above.
• TestCommandsInTableHiddenFlags (internal/docgen/helpers_test.go:30) needs a
  sibling case for hidden-and-deprecated, asserting the row renders with the
  (DEPRECATED: ...) suffix, plus a case asserting hidden-and-not-deprecated is still
  skipped.
• No manual docs step: client_reference is regenerated from the released binary by
  kosli-dev/docs on the cli-release dispatch (release.yml:261), so the new rows
  appear on the next release.

Alternative considered

Keep the primary flags table strictly prescriptive and add a separate "Deprecated
flags" section at the foot of each command page. That serves people migrating without
adding noise for new users, who are most of the readership. It needs real work though

• a second table, a template change, and coordination with the Mintlify page layout -
  versus a one-line condition. Suggest starting with the simple version and revisiting
  if the tables look cluttered.

One cosmetic cost of the simple version: --e renders as a row reading
--e strings ... (DEPRECATED: use -x instead) on both fingerprint and
snapshot server. Slightly odd-looking, since --e was always an odd flag name.

Note

Related issue #1059