docs: add CLI lifecycle notice snippets and render lifecycle tags in nav

[dangrondahl]

Adds the reusable Mintlify snippets the CLI doc generator imports for beta and deprecated commands (snippets/cli-beta-notice.mdx, snippets/cli-deprecated-notice.mdx).

Updates scripts/update-cli-nav.py so the sidebar pill comes from each page's tag front matter (rendered by Mintlify): the separate "Deprecated" group is removed and hidden: true pages are excluded from navigation (still reachable by direct URL).

Adds a fixture-based test (scripts/test_update_cli_nav.py) verifying hidden pages are skipped, deprecated pages stay in their family group, and no Deprecated group is emitted.

Deploy ordering: merge this first, then release the CLI with the generator changes (kosli-dev/cli companion PR); the release workflow regenerates client_reference/ with the tag/hidden front matter and resolves the snippet imports.

[claude]

Claude finished @dangrondahl's task in 1m 7s —— View job

---

PR Review: CLI lifecycle notice snippets and nav tags

• Read changed files and gather context
• Review snippet files (.mdx)
• Review script changes (update-cli-nav.py)
• Review test file (test_update_cli_nav.py)
• Post findings

---

This is a clean, well-scoped PR. The changes are logically consistent: deprecated commands stay in their family group with a sidebar pill instead of being segregated, hidden commands are excluded from nav, and the snippet files are ready for the companion CLI release.

snippets/cli-beta-notice.mdx / snippets/cli-deprecated-notice.mdx

No issues. Both snippets are concise, use the <Warning> component appropriately, and follow the CLAUDE.md rule that snippets should only exist when reused in 2+ pages (these will be imported by the CLI doc generator across many pages).

scripts/update-cli-nav.py

No issues. The refactor cleanly replaces the old deprecated detection (which had a fragile body-text regex fallback) with the simpler hidden front-matter field. The tag front matter is intentionally not read by this script — Mintlify renders it as a sidebar pill automatically. The setdefault simplification and removal of the separate active/deprecated split are nice cleanup.

Suggestion: Minor — the tag field isn't used by this script, but it's mentioned in the docstring and the test fixture. Consider adding a brief comment near get_command_info noting that tag is intentionally ignored (Mintlify handles it). This would help future readers who see tag in the front matter and wonder why the script doesn't read it.

This is entirely optional — the docstring on build_nav_groups already covers it well.

scripts/test_update_cli_nav.py

No issues. The fixture-based test covers the three key behaviors well:

1. Hidden pages are excluded from navigation
2. Deprecated pages remain in their family group (not segregated)
3. No separate "Deprecated" group is emitted

The test exercises the script as a subprocess, which validates the full CLI path including argument parsing.

Suggestion: Consider adding a test case for a beta (non-hidden) page to verify it appears normally in navigation — the current fixture has beta+hidden combined on one page, so the beta-only path isn't exercised independently.

Low priority since the script doesn't treat tag: "BETA" specially (it's a Mintlify concern), but it would document that intent.

Deploy ordering

The PR description correctly notes this should merge before the CLI release. The snippets exist ahead of the pages that will import them, and the nav script is ready to handle the new hidden front matter the CLI generator will produce. No ordering risk.

Overall: Looks good to merge. No critical or blocking issues found.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
kosli	🟢 Ready	View Preview	Jun 19, 2026, 3:40 PM