feat: add interactive policy builder to docs

[dangrondahl]

Summary

Adds an interactive policy builder to the docs as a self-contained Mintlify React component, so users can assemble a valid environment policy YAML in the browser and copy it into their repo without installing the CLI.

• New page: policy-reference/policy_builder.mdx (wide mode, no right-hand TOC), added to navigation and cross-linked from environment_policy.mdx.
• New component: snippets/policy-builder.jsx.

It mirrors the kosli create policy-file CLI wizard (kosli-dev/cli internal/policywizard):

• Provenance and trail-compliance "required" toggles, each with repeatable exceptions.
• Repeatable attestation rules: built-in type dropdown + custom:<name>, optional name, optional condition. Enforces the "type and name can't both be *" rule with inline feedback.
• Expression builder: multiple terms combined with and/or, per-term negate; term kinds for flow name, flow tag, artifact name regex (matches), custom comparison (incl. matches/exists), and raw.
• Live, syntax-highlighted YAML preview with copy-to-clipboard.

Implementation notes

• No third-party packages: the YAML serializer, expression builders, and a small YAML highlighter are hand-rolled in plain JS, per the Mintlify sandbox constraints.
• All helpers, constants, styles, and sub-renderers live inside the exported component — the Mintlify MDX sandbox only exposes the exported component body plus the pre-injected hooks (useState/useMemo), and resolves capitalized <Tags> through its own registry rather than local scope.
• The attestation name field is omitted when it is the schema default (*), since name defaults to * in the v1 schema and only type is required.
• Fully client-side — no API calls, no auth/CORS.

Verification

• YAML serializer and all expression builders byte-tested against the CLI's Go policy.ToYAML() expected outputs.
• mint broken-links passes; component renders in mint dev.

Note

The CLI kosli create policy-file feature is still on the unmerged create_policy_file branch in kosli-dev/cli. Consider holding this until that ships, since the page references it.

Closes #269

[claude]

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

---

PR Review: Interactive Policy Builder

• Read CLAUDE.md and doc-review skill
• Read all changed files
• Verify navigation entry exists
• Check for relative links and other issues
• Post review findings

---

Review findings

Scope: policy-reference/policy_builder.mdx, policy-reference/environment_policy.mdx, snippets/policy-builder.jsx, config/navigation.json

Checklist

Check	Status
New page in config/navigation.json	Pass — added under Policies group
No relative links	Pass — all links are root-relative
Frontmatter (title, description)	Pass
Internal links resolve	Pass — all 5 linked pages exist
Writing style (active voice, "Kosli" naming, American spelling)	Pass
Cross-linking between builder and reference page	Pass — bidirectional links via <Tip> and "See also"

Suggestions

1. policy-reference/policy_builder.mdx:9 — "Toggle the requirements" wording

"Toggle the requirements you need" could be clearer. Consider: "Enable the requirements you need" — "toggle" implies switching back and forth rather than building up.

2. snippets/policy-builder.jsx:594 — * type triggers immediate validation error

The prior reviews flagged this repeatedly. The author confirmed * should stay as an option, but the UX issue remains: selecting * with default name: "*" shows an instant error. Since the author wants * available, the auto-clear approach is the least disruptive fix — clear name to "" when * type is selected so the user is prompted to provide a specific name. This avoids the "pick a listed option, get an error" trap without removing any functionality.

3. snippets/policy-builder.jsx:314-316 — hardcoded #2563eb on Copy button

All other colors use CSS variables (var(--gray-200, ...)) but the Copy button uses a hardcoded blue. If a Mintlify theme changes accent colors, this button will stand out. Minor, but worth aligning for consistency.

Summary

The PR is well-structured: new page has proper frontmatter and navigation entry, all links are root-relative and resolve to existing pages, and the reference page cross-links are bidirectional. The component is self-contained and thoroughly documented in its header comment. The main open item from prior reviews is the * type UX — consider the auto-clear fix since the author wants to keep * available.

[mintlify]

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

Project	Status	Preview	Updated (UTC)
kosli	🟢 Ready	View Preview	Jun 16, 2026, 1:56 PM