docs(api-key): correct the --expires-at help text

[dangrondahl]

kosli create api-key --help told users that --expires-at "Defaults to no expiry", which is no longer true — the API does not issue non-expiring keys. Omitting expires_at gives the key the maximum allowed lifetime, and a date beyond that maximum is capped to it.

The empty flag default is unchanged and correct: not sending the field is what lets the API own the expiry policy, the same way --grace-period-hours already works. Duplicating the maximum client-side would only drift when the API changes it.

• Split the shared apiKeyExpiresAtFlag constant in two — create and rotate genuinely default differently: create falls back to the maximum lifetime, rotate keeps the rotated key's current expiry.
• Added a paragraph to the create api-key long description covering expiry and capping.
• Dropped "server-side"/"server-managed" from the grace-period help text, which described where the value comes from rather than what the user gets.

No behaviour change — help text only.

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 @dangrondahl's task in 3m 9s —— View job

---

Review: docs(api-key): correct the --expires-at help text

• Read PR diff
• Static analysis (go build ./..., go vet ./..., go mod tidy + git diff --exit-code go.mod go.sum) — all clean
• Review changed files, check for stale golden/doc artifacts
• Post review (4 inline comments)

Static analysis

Check	Result
go build ./...	✅
go vet ./...	✅
go mod tidy (no go.mod/go.sum drift)	✅

No golden files or committed docs reference the old strings — make docs writes to client_reference/ (not committed), and cmd/kosli/testdata/empty-flag-audit-coverage.json records flag types only, so nothing needs regenerating. Grep confirms no remaining Defaults to no expiry / server-side value / server-managed occurrences.

I couldn't run ./kosli create api-key --help or the integration suite in this sandbox (command execution restricted / tests need the docker-compose server), so the rendered ^…^ → backtick output is unverified — though it follows the same convention as every other long description in the package.

Findings

1. createApiKey.go:19-20 — the new claim contradicts this package's own rendering layer. "Every API key expires" sits next to optionalTimestamp, which maps expires_at == 0 to N/A and documents it as "a zero value meaning 'never'/'not set'" (cmd/kosli/apiKey.go:133-134), plus two tests asserting // expires_at of 0 means "no expiry" (cmd/kosli/apiKey_test.go:40, :73). If the API can't return 0 any more those comments are stale; if it still can (legacy keys), the help overstates. Either way it belongs in this docs pass. Details inline.

2. root.go:158 — one unverifiable claim replaced by another. The CLI just omits expires_at on rotate (rotateApiKey.go:100-106), so "Defaults to the rotated key's current expiry" is purely a statement about server behaviour. Worth confirming against the OpenAPI spec that rotation carries the old expiry forward rather than granting a fresh maximum — nothing in this repo will catch it if it drifts.

3. root.go:157 — wording nit (suggestion inline): which also caps later dates has a distant antecedent, and capping isn't actually conditional on the flag being unset.

4. rotateApiKey.go:20 — non-blocking: "has a standard length" is vaguer than the "server-managed" it replaced; it names neither the length nor where to find it.

What's good

• Splitting apiKeyExpiresAtFlag into per-command constants is the right fix, not a workaround — the two commands genuinely have different defaults, and the shared constant was structurally incapable of being accurate for both.
• Resisting the urge to hardcode the maximum lifetime client-side is the correct call, and consistent with how --grace-period-hours already defers to the API.
• Keeping the empty flag default unchanged means zero behaviour risk; the PR description is explicit about that and about the reasoning.
• The long description carries the detail that doesn't fit in a flag usage line — right split between the two surfaces.

Nothing here blocks merge; #1 is the one I'd resolve before shipping, since it's the same class of drift this PR exists to fix.
• branch docs/api-key-expiry-help