docs: kosli evaluate policy is announced in the changelog but has no reference page #438

A reader who sees the v2.43.0 entry and goes looking for kosli evaluate policy finds nothing. The command has no reference page, no navigation entry, and no mention anywhere else on the site.

The changelog entry

changelog/index.mdx:22 (CLI v2.43.0, 17 September 2026):

kosli evaluate policy — evaluate a policy and record the decision in a single request, instead of calling evaluate and record separately. Beta

Note that this entry, unlike almost every other CLI feature entry around it, links to nothing.

What the reader finds instead

Nothing:

$ ls client_reference/ | grep evaluate
kosli_evaluate_input.md
kosli_evaluate_trail.md
kosli_evaluate_trails.md

config/navigation.json:375-379 — the kosli evaluate group lists exactly those three pages:

"group": "kosli evaluate",
"pages": [
  "client_reference/kosli_evaluate_input",
  "client_reference/kosli_evaluate_trail",
  "client_reference/kosli_evaluate_trails"
]

And nothing in the hand-authored content mentions it:

$ grep -rn "evaluate policy\|evaluate_policy" --include=*.md --include=*.mdx . | grep -v "^./client_reference/kosli" | grep -v changelog
tutorials/evaluate_trails_with_opa.mdx:63:This policy applies three design rules that every evaluate policy should follow.

That single hit is an unrelated use of the words, not the command.

Why this is not just a stale generator run

client_reference/overview.md:7 states the reference was generated from CLI v2.45.0 — two releases after the one that introduced the command. So update-cli-docs.yml has run since v2.43.0 and still produced no page. Other features from the same window did land: --download-concurrency and --download-budget from v2.42.0 are in client_reference/kosli_snapshot_s3.md:39-40, --sonar-branch from v2.39.0 is in kosli_attest_sonar.md, --jira-trailer from v2.40.0 is in kosli_attest_jira.md.

Beta status is not the explanation either: kosli attest sbom shipped as beta in v2.41.0 and has a full page at client_reference/kosli_attest_sbom.md.

So one of these is true, and the fix differs by which:

1. The command is hidden from kosli docs generation upstream in kosli-dev/cli (cmd/kosli/ — the Hidden field on the cobra command). Fix it upstream; the page then generates on the next release.
2. The command was withdrawn or renamed between v2.43.0 and v2.45.0. Then the changelog entry should be corrected or removed, because it announces something that no longer exists.

Either way the reference page must not be hand-written — update-cli-docs.yml runs rm -f client_reference/kosli*.md on every CLI release.

What a reader currently cannot find out

What kosli evaluate policy takes as input, what it records, how it differs from kosli evaluate input plus kosli attest decision, and whether it is safe to use in a pipeline while in beta.

Related

This also trips the rule proposed in #389 section 3 — do not announce a feature the docs do not cover. That issue would prevent the next one; this issue is the instance already published.

Evidence

$ grep -n 'kosli evaluate policy' changelog/index.mdx
$ ls client_reference/ | grep evaluate
$ grep -n evaluate config/navigation.json
$ head -8 client_reference/overview.md

Found by the monthly doc-structure audit, step 4 (changelog coverage).