feat(docs): emit Mintlify lifecycle metadata and snippet notices for beta/deprecated commands

[dangrondahl]

Teaches the CLI doc generator to emit Mintlify lifecycle front matter (tag: "BETA" / tag: "DEPRECATED", hidden: true) and to render beta/deprecated notices via reusable docs snippets (<CliBetaNotice />, <CliDeprecatedNotice />) instead of inline prose.

Adds a docHidden annotation so hidden-but-documented commands still get a generated page. Wires the evaluate tree (beta) and attest decision (beta + docHidden) to the real annotations and removes the [BETA] text prefixes. Dedupes the generic deprecation string into one constant and suppresses that boilerplate from generated pages (the snippet conveys it), while preserving real per-command migration hints.

The explanatory wording now lives in the docs repo snippets, not in Go.

Draft until kosli-dev/docs#280 lands — the generated MDX imports /snippets/cli-*-notice.mdx, which only exist after that PR merges. Mark ready for review once #280 is on docs main.

[claude]

Claude finished @dangrondahl's task in 2m 22s —— View job

---

Claude PR Review

• Gather context (read changed files)
• Static analysis (go build, go vet, go mod tidy)
• Code review (quality, bugs, edge cases, tests)
• Post review feedback

---

Summary

Clean, well-tested change. The doc generator now emits Mintlify lifecycle front matter (tag: "BETA"/tag: "DEPRECATED", hidden: true), renders notices via reusable snippets, and the docHidden annotation lets hidden-but-documented commands (attest decision) still produce a page. The generic deprecation string is deduped into deprecatedCommandMsg and suppressed from generated prose while custom migration hints are preserved.

Static analysis ✅

• go build ./... — clean
• go vet ./... — clean
• go mod tidy + git diff --exit-code go.mod go.sum — clean (MOD_CLEAN)

⚠️ I could not run the test suites (go test requires approval in this environment, and cmd/kosli tests need the local Kosli server). Build/vet confirm compilation; the new tests read as correct but were not executed here.

Both earlier review comments are resolved 👍

1. MDX-escaping the migration hint — DeprecatedWarning now routes message through escapeMintlifyProse (internal/docgen/mintlify.go:54), with a comment explaining why.
2. Body/tag precedence consistency — genMarkdownCustom now emits the beta notice only if meta.Beta && !meta.Deprecated (internal/docgen/generate.go:66), matching lifecycleTag's deprecated-wins rule. TestMintlifyFrontMatterDeprecatedWinsOverBeta covers the front-matter side.

Strengths

• Good single-source-of-truth refactor: deprecatedCommandMsg + betaCLIAnnotation constants replace scattered string literals; deprecationHint cleanly separates generic boilerplate (suppressed, snippet conveys it) from real per-command hints.
• Thorough, focused unit tests in mintlify_test.go, generate_test.go, and the new lifecycle_test.go — including the doc-hidden, deprecated-included, and "no [BETA] prefix" cases. Golden files (artifact.md, snyk.md) updated to match.
• The DocHiddenAnnotation abstraction is well-placed in docgen with a clear doc comment, and the tree walker correctly extends the skip condition (generate.go:19-20).

Minor observations (non-blocking)

• Untested body branch. The meta.Beta && !meta.Deprecated precedence in the body (generate.go:66) has no direct test — only the front-matter equivalent does. Since no command is currently both, this is low priority, but a small genMarkdownCustom-level test asserting a both-flags command renders only the deprecated snippet (and a single import) would lock the invariant in. Fix this →
• Exact-match suppression. deprecationHint suppresses the generic text via exact string equality with deprecatedCommandMsg (root.go:605). That's the right mechanism now that all generic uses share the constant, but it's worth keeping in mind that any future divergent wording (extra whitespace/punctuation) would silently leak the boilerplate into the page. The dedup makes this safe today.

Note on draft status

As the description says, this stays draft until kosli-dev/docs#280 lands — the generated MDX imports /snippets/cli-*-notice.mdx, which don't exist until that PR merges. Worth confirming #280 is on docs main before marking ready.

Overall this is a solid, reviewable slice that follows the repo's conventions well. ✅