docs: refresh controls tutorial for flow templates, coverage, and CLI

[pbeckham]

Closes #6005.

Refreshes the Working with controls tutorial to match released behavior.

What changed

• Flow templates — new "Requiring decisions in flow templates" section documenting type: decision attestations, and how that differs from for_control in environment policies.
• Coverage — new Coverage tab section: what "covered" means (an active policy whose latest version references the control via for_control, regardless of pass/fail), the coverage %, the Status filter, and the GET /api/v2/controls/{org}/{identifier}/coverage API.
• Archiving — new "Archiving a control" section (archive/unarchive, history preserved, Archived view, Versions-tab events), plus an explicit note that archived environments and inactive policies are excluded from coverage totals.
• CLI commands — references the newly released kosli create / update / list / get / archive / unarchive / tag control commands, with examples.
• Screenshots — replaced controls-list, controls-decisions, controls-decision-detail and added controls-coverage, all cropped to app content.

⚠️ Hold for CLI release

The kosli *control* commands are merged to the CLI main but not yet in a released binary, so the auto-generated client_reference/ pages don't exist yet — the commands are referenced as inline code (not links) to avoid broken links. Please merge this only after the CLI is tagged; a follow-up can convert the inline references to links once the reference pages regenerate.

🤖 Generated with Claude Code

[mintlify]

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

Project	Status	Preview	Updated (UTC)
kosli	🟢 Ready	View Preview	Jul 1, 2026, 5:25 PM

[claude]

Claude finished @pbeckham's task in 2m 48s —— View job

---

PR Review: Refresh controls tutorial

• Read CLAUDE.md and doc-review skill
• Read changed tutorial file and verify screenshots
• Check navigation config (no new pages — existing page modified)
• Verify all internal links resolve
• Post review findings

---

Overall assessment

This is a solid tutorial update. The new sections (flow templates, coverage, archiving, CLI commands) are well-written, follow Diátaxis tutorial conventions, and integrate naturally into the existing page structure. Writing style is consistent with CLAUDE.md conventions: active voice, imperative mood, correct product terminology, American spelling. All internal links resolve to existing pages or configured redirects.

The screenshots are clear, match the UI descriptions in the text, and show relevant features (coverage progress bar, Status filter, Decisions/Coverage/Versions tabs).

Findings

No Critical issues found.

Improvement

1. tutorials/working_with_controls.mdx:282–285 — Decision detail screenshot shows a different control than the Decisions tab screenshot. The Decisions tab screenshot shows SDLC-CTRL-0022 (vulnerability scanning), but the decision detail screenshot shows SDLC-CTRL-0002 (binary provenance) with a non-compliant outcome. While neither screenshot is "wrong" — the text describes them generically — using the same control in both would give the reader a more cohesive walkthrough. Minor, and the text's use of "Select a decision" is general enough that it works either way.

Suggestions

2. tutorials/working_with_controls.mdx:100 — Long sentence in the Archiving section. The sentence starting "Archive or unarchive a control from its detail page..." packs four methods (UI, two CLI commands, two API endpoints) plus a Versions-tab note into one sentence. Consider splitting after the API reference: "Both actions appear as events…" could start its own sentence — which it already does, so this is fine structurally. Just a readability note; no change needed.

3. tutorials/working_with_controls.mdx:7 — Beta notice scope. The updated beta notice now says "the controls CLI commands (kosli create control, kosli attest decision, and related)" — since the PR description notes the new kosli * control commands aren't in a released binary yet, you may want to be more explicit here about which commands are in beta vs. generally available (e.g., kosli attest decision has been available for a while). This is a judgment call depending on how you want to present it.

Merge note

The PR description clearly flags the CLI-release dependency — CLI commands are referenced as inline code (not links) to avoid broken links until the client_reference/ pages are generated. This is the right approach. Once the CLI is tagged and reference pages regenerate, a follow-up PR can convert backtick references like `kosli create control` to links.

Summary

Clean, well-structured update. No broken links, no relative links, no navigation gaps. The new coverage section and flow-template section are particularly useful additions that explain the distinction between trail-scoped and environment-scoped requirements clearly. Ready to merge once the CLI is released.