fix(docs): separate flag types into a column

[mbevc1]

Follow-up review fixes on top of the flag type column change:

• Regenerate the mintlify goldens instead of editing them by hand. They had
  lost the trailing blank line the generator emits; the test only passed
  because compareFileBytes normalises with strings.TrimSpace, so the goldens
  no longer reproduced generator output byte for byte.
• Drop cobra's alignment padding from the flag cell. Markdown strips leading
  whitespace inside a table cell, so the padding only added noise to the
  generated MDX; the maxlen pass that used to need it is gone.
• Build the rows with a single strings.Builder. The intermediate slice, the
  bytes.Buffer and the second loop existed only to support that alignment
  pass, and the bytes import goes with them.
• Move the table header into FlagTableHeader next to the row builder, so the
  column count cannot drift between the header and the rows, and cover that
  contract with a test.
• Assert whole rows in the default and deprecation tests. Both previously
  matched on a substring that would have passed had the text leaked into the
  type column, which is the behaviour the change is about.
• Pin where the NoOptDefVal syntax lands. No Kosli flag uses a non-bool
  NoOptDefVal today, so that path moved into the type column untested.

Verified by regenerating all 94 command docs and checking that every flag row
is a well formed three column row.

Obsoletes #1067

Closes#450

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 2m 43s —— View job

---

Review — PR #1068: separate flag types into a column

• Gathered context (diff, changed files, generator + test helpers)
• Static analysis: go build ./... ✅, go vet ./internal/docgen/... ✅ (compiles tests too)
• Reviewed code quality & correctness
• Reviewed tests
• Posted feedback

---

Verdict: ✅ Looks good — merge-ready

This is a clean, well-reasoned follow-up. Each commit maps to exactly one concern from the review thread, and the reasoning is captured in comments rather than lost.

On JonJagger's question (empty type cells) and @mbevc1's reply: the latest commit c108ce3e resolves it directly — the varname == "" fallback to flag.Value.Type() (helpers.go:62-64) now names booleans, so the previously-blank column reads bool. The regenerated goldens confirm it (-D, --dry-run | bool, -h, --help | bool). This is also pflag's own convention. 👍

What's done well:

• Header/row cohesion — moving the header into the exported FlagTableHeader const next to CommandsInTable, then pinning it with TestCommandsInTableColumnCount (counts unescaped | in every row vs. the header), is exactly the right way to stop the column count from drifting. MintlifyFormatter is the only Formatter implementation, so there's no second header to keep in sync.
• Ordering — computing the type fallback before the NoOptDefVal block so an optional value reads bool[=x] mirroring string[="x"], with TestCommandsInTableBoolOptionalValue / TestCommandsInTableOptionalValue pinning both paths.
• Whole-row assertions — the default and deprecation tests now match the full | flag | type | description | row, so leakage of a default/deprecation notice into the type column would fail. That's the exact regression the change guards against; substring matches would have missed it.
• Goldens regenerated, not hand-edited — restoring the trailing blank line the generator emits. Worth noting the tests wouldn't have caught the drift (normalize() in testHelpers.go:322 does strings.TrimSpace), so this keeps the goldens a byte-for-byte reproduction of generator output regardless. Good discipline.
• Dropping the alignment padding, the intermediate slice, the bytes.Buffer, and the bytes import in favor of a single strings.Builder — markdown strips leading cell whitespace anyway, so this is pure noise removal.

One conscious-decision note (inline on helpers.go:64, non-blocking): -h, --help now shows | bool | in every command's flag table — that's now in all 94 generated docs, not just the two sampled goldens in this PR. It's consistent with the "always name the type" rule, so no change needed; just flagging the blast radius.

Nit (optional):FlagTableHeader is exported but every consumer (mintlify.go, the test) is in-package, so it could be unexported. Harmless either way.

No correctness, security, or performance concerns. The per-flag defaultZero slice allocation is negligible for doc generation and was an intentional locality refactor.

Note: I couldn't execute go test ./internal/docgen/... in this environment (command approval), but go vet compiles the test files and the logic/goldens check out by inspection.

[JonJagger]

I notice that some flags have no entry in the type column.
Are these all boolean flags with a default?
Is it worth adding an entry for these?

[mbevc1]

Fair point and Pr is following #450 where it asked for the type (if there is one), which is also pflag's own convention. Happy to add that in so it's clear what are the types and don't leave it to reader to assume.