[mintlify]

Shows how to pin a published policy version with --identifier <id>@v<n> and adds --server-side for evaluate trail/trails (beta: controls page already carries the beta banner; pinning is on prod and in CLI v2.52.0).

Based on evaluate a pinned policy version with --identifier @v, Evaluate a pinned version of a published rego policy and unhide server-side evaluation commands and --server-side flag.

[mintlify]

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

Project	Status	Preview	Updated
kosli	🟢 Ready	View Preview	Nov 3, 2026, 9:39 AM

[claude]

Claude finished @mintlify[bot]'s task in 1m 7s —— View job

---

Doc review: PR #486

• Read the diff and both changed files at the branch head
• Check the prose against client_reference/kosli_evaluate_{policy,trail,trails}.md
• Sweep the site for wording that pinning makes stale
• Post findings

policy-reference/rego_policy.mdx

Improvement: the version-status table still says evaluations always run the newest version

• Location: policy-reference/rego_policy.mdx:148
• Issue: The valid row says "Evaluations run the newest valid version." Once --identifier <id>@v<n> exists, that's only the default. This is the policy reference page, and the PR touches it, but pinning is documented only in the tutorial. Someone reading the reference won't learn that pinning exists.
• Recommendation: Change it to e.g. "The version can be evaluated. Evaluations run the newest valid version unless one is pinned with --identifier <id>@v<n>; see Pinning a policy version." Fix this →

Improvement: "the same policy file" contradicts the list that follows it (:407, see the inline comment). The next bullets say local and server input have different shapes and that a policy can compile locally but fail on the server. So adding --server-side to a working local check may change the verdict.

Upstream: does not block this merge

• kosli-dev/cli → cmd/kosli/evaluatePolicy.go: caret escaping bug in the --identifier text. client_reference/kosli_evaluate_policy.md:27 renders Append `@v`n and `:83` renders identifier@vn ``. The ^ markers around `n` inside `@v^n^` became broken nested backticks. The tutorial in this PR spells it correctly as `@v`. Fix the description, or the generator's `^` handling, upstream.

The links resolve: #pinning-a-policy-version matches the new heading. I couldn't run gh pr checks or read the kosli-dev/cli source from this job, so I haven't confirmed the link-rot result or the server-side input shape.

2 Improvements, 0 Critical, 1 upstream. Safe to merge once the two wording fixes are in.

[claude]

Improvement: "the same policy file" reads as a promise that a local policy works unchanged with --server-side. The next list says otherwise: local input is the trails-API shape, "not a trail moment", and fields differ (name vs trail_name, flow.name vs flow_name, see the table under Local input data). Also, a policy that passes locally "can still fail to compile on the server". A reader who adds --server-side to a working local check could get a different verdict or a compile failure.

Suggest dropping "the same" and saying which input the server builds, e.g.:

Suggested change

To evaluate the same policy file on the Kosli server instead, add `--server-side` (beta) to either command. Kosli builds the input from the trails you name, so the CLI reads no trail data. The flag can't be combined with `--attestations`, `--show-input` or `--output-rule`, and a server-side evaluation takes at most 100 trails.

To evaluate a policy file on the Kosli server instead, add `--server-side` (beta) to either command. Kosli builds the input from the trails you name as [trail moments](#trail-moment), so the CLI reads no trail data, and a policy written for local input may need its field paths changed. The flag can't be combined with `--attestations`, `--show-input` or `--output-rule`, and a server-side evaluation takes at most 100 trails.

(I couldn't read the CLI source from this job to confirm the server-side input shape for evaluate trail, so check this against kosli-dev/cli#1318 before you accept it.)