docs: update CLI and helm reference for v2.39.1 - #375
Merged
Conversation
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
mbevc1
enabled auto-merge (squash)
August 30, 2026 17:35
Contributor
|
Claude encountered an error after 3m 21s —— View job Doc review — v2.39.1 reference regeneration
Verdict: looks good to merge. No Critical findings. This is a machine-generated reference refresh — 12 of the 14 files are pure fixture churn (timestamps, snapshot indices, fingerprints, commit SHAs from the CriticalNone. Checks run against this repo's
Improvement
SuggestionPR title — "update CLI and helm reference" but no Two changes worth calling out as clearly good:
Notes on verification
Top 3 priorities (all upstream in |
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
Comment on lines
+45
to
+49
|
|
||
| A reachable but wrong base URL still surfaces as a non-existent issue, because Jira answers 404 | ||
| both for an issue that does not exist and for one you may not view. A base URL that cannot be | ||
| reached is reported as not confirmed, with the transport error as the reason. A credential | ||
| rejection is likewise detected and reported as not confirmed, with a warning identifying the |
Contributor
There was a problem hiding this comment.
Improvement — this rewritten paragraph is the only substantive prose change in the PR, and a few things read ambiguously for a reference page:
for one you may not view—may notis ambiguous between permission and possibility.one you do not have permission to viewis unambiguous.- The causal link is loose. The sentence claims a wrong base URL surfaces as a non-existent issue because Jira 404s for both "issue missing" and "issue not visible". Those two 404 cases explain the permission scenario, not the wrong-base-URL scenario. Splitting them would be clearer.
- The flag isn't named. The previous text said "wrong Jira-base-url"; the new text only says "base URL". On a lookup-oriented reference page, naming
--jira-base-url(documented at line 93) helps readers connect the prose to the flag. - Three distinct outcomes in one paragraph. Reachable-but-wrong URL → reported missing; unreachable URL → not confirmed + transport error; rejected credentials → not confirmed + warning. A short list would be easier to scan than prose.
scripts/ and the Live docs section of CLAUDE.md), so any wording fix has to land in the CLI's long-description in kosli-dev/cli — not here. Non-blocking for this release PR.
Comment on lines
+29
to
+30
| If the scan ran on a branch other than the project's main branch in SonarQube, also provide the branch name using the `--sonar-branch` flag. | ||
| SonarQube only searches the project's main branch unless told otherwise, so without this flag the scan cannot be found. |
Contributor
There was a problem hiding this comment.
Suggestion — the rewrite here is an improvement (splitting the run-on into two sentences and dropping the dangling colon). Two pre-existing issues in the same paragraph that are worth fixing upstream while this text is being touched:
- Line 28 (and lines 19, 85):
overriden→overridden. - The sentence still says "the project's main branch in SonarQube" then repeats "the project's main branch" immediately after. Dropping the repetition would tighten it.
Generated file — fix in kosli-dev/cli, not in this PR.
mbevc1
approved these changes
Aug 30, 2026
dangrondahl
added a commit
that referenced
this pull request
Sep 3, 2026
Reviewed the last 20 non-bot PRs (14 touched docs) against what `doc-write` and `doc-review` actually ask for, then fixed what the record showed was wrong. No site content changes — this is all agent tooling. ## Why `doc-review` produced **0 Critical, 5 Improvement and ~20 Suggestion** findings across those 14 PRs. Its genuinely valuable catches were all cross-file consistency checks the skill never asked for: - a changelog entry documenting `kosli update attestation-type`, a command with no reference page (#371) - `template-reference/flow_template.md` out of sync with the schema the same PR regenerated (#296) - the one file an approvals-removal sweep missed, `understand_kosli/how_kosli_works.md:22` (#345) Its weakest findings were prose polish, some already fixed at branch head. Meanwhile its written checklist was dominated by things that always pass or are already enforced by `vale-spellcheck`. Two structural gaps the PR record made obvious: - **Placement was never questioned.** In #305 a pure reference page was authored into `integrations/`, and a human reviewer had to ask for the move — commit `9e7a121 docs: move GitHub Action reference into the Reference section`. That question should come from the review. - **Generated pages were handled inconsistently.** #375 got it right and said so. #374 wrote *"the durable fix is in the `kosli-dev/cli` generator — a hand-edit here is overwritten by the next release"* and then emitted a `Fix this` link scoped to `repo=kosli-dev/docs` telling an agent to edit the generated file anyway, plus 4 inline comments on regenerated files. ## What changed **`doc-review`** — promoted the three accidental wins to named checks, each carrying its precedent. Added placement, redirects and anchor stability. Added an explicit *what not to report* bar and an 8-finding cap. Stopped hand-checking spelling. Dropped the "what looks good" recital that the sticky comment re-renders on every push. **Generated pages** — split into three categories rather than one blanket ban: deterministically regenerated (edit is deleted), agent-synced (edit survives but drifts), and hand-authored despite the directory (`client_reference/overview.md`, `output_and_verbosity.md`). Includes the filename→source mapping, verified upstream: `kosli_attest_sonar.md` ← `cmd/kosli/attestSonar.go`. Also records that **`^` is the CLI's backtick convention** in Go long descriptions, substituted by `kosli docs`. That makes the `^jq^` defect #374 found a generator escaping bug in the Accordion-title path, not a typo in the Go string — so a reviewer can point at the right fix. Worth filing upstream separately. **`doc-write`** — added a Diátaxis→tab placement table so #305 can't recur, plus redirects, anchor stability, and the generated-paths table. **New `doc-structure` skill + monthly workflow** — audits navigation shape and changelog coverage, which per-PR review structurally cannot see, and files issues. Read-only against docs; issues are its only write. Capped at 8 issues, deduplicating against open issues first — its headline check reproduces the `/getting_started/attestations` summary gap, which is already open as #364. **New `scripts/audit_navigation.py` + 22 tests** — the audit's mechanical checks, extracted from an inline heredoc. Three payoffs: 1. `pr-quality.yml` already runs `pytest tests/`, so **CLAUDE.md core rule 2 is now enforced deterministically** — a page file with no `navigation` entry fails the build. No new job needed. 2. `doc-structure.yml` can allow `Bash(python3 scripts/audit_navigation.py:*)` instead of `Bash(python3:*)`, which was arbitrary code execution. 3. Determinism. The inline version had already shipped a bug: `sed 's|\.mdx\?$||'` is a no-op on BSD sed, so every page looked orphaned on macOS. That case is now a regression test. Integrity findings (orphans, dangling entries) are separated from shape findings (single-child groups, deep nesting, Title Case labels, oversized groups, inconsistent icons). Only integrity can fail a build — the script cannot tell a group that should be merged from one deliberately kept separate. `Reference ▸ CLI Reference` is exempt from shape checks: `update-cli-nav.py` generates it from the CLI's command tree, so a single-child `kosli allow` group is upstream truth. Without that exemption the audit reported 54 findings, 21 of them proposing to reshape generated navigation — the same mistake being fixed in `doc-review`. It now reports 33, all hand-maintained. **New `docs-restructure` issue template** — Markdown, not a YAML form: `gh issue create --body` doesn't apply templates mechanically and YAML forms can't be filled from the CLI, so a form would help humans and do nothing for the job. Its URL-impact section encodes the distinction that decides whether a restructure is safe — a group rename changes no URLs, a moved page file needs a `config/redirects.json` entry. `config.yml` keeps blank issues enabled. **`CLAUDE.md`** — documented the six automated PR checks, the generated-page source map, the audit script, and the three skills. Removed the pointer to a `changelog-creator` skill that doesn't exist in this repo. ## Anti-rot pass Swept all three skills for dated claims. Counts ("three of the last fourteen PRs") and current-state assertions ("link-rot reports skipping on most PRs") became durable rules. The link-rot guidance now routes through `gh pr checks` so it self-heals if Mintlify starts running it reliably. Past-tense `Precedent:` items were kept — they're what make the checks concrete. ## Verification - `python3 -m pytest tests/` — 44 passed (22 pre-existing + 22 new) - `python3 scripts/audit_navigation.py --check` — exit 0, integrity clean - `mint broken-links` — no new broken links - Both workflows parse; triggers and permissions confirmed ## Follow-ups, not in this PR - `tutorials/working_with_controls.mdx:24` links to `/getting_started/service-accounts`, which has never existed — the page is `/administration/authentication/service_accounts`. Broken on `main` since #154; `link-rot` reports `skipping`, which is why it went unseen. - The `mintlify-docs` plugin in `kosli-plugins` still ships near-duplicate `doc-writer`/`doc-reviewer` agents that say "update `docs.json` navigation" — the pre-`config/` layout. Needs its own PR there. - The reviews twice asked for `python3` in `doc-review.yml`'s `--allowedTools` to validate JSON payloads and fence balance. Left alone — `Bash(python3:*)` is a security-surface call worth making deliberately.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Automated update of CLI and Helm reference documentation for release
v2.39.1.