docs: update CLI and helm reference for v2.39.0 - #374
Conversation
Sorry, something went wrong.
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
Sorry, something went wrong.
|
Claude finished @github-actions[bot]'s task in 3m 7s —— View job Doc review: CLI & Helm reference for v2.39.0
Reviewed all 29 changed files against CLAUDE.md and the doc-review skill. All are generated pages — no new files, so no config/navigation.json change is needed. One critical rendering defect, plus three prose issues and two suggestions. Four are posted inline; the rest are below. Criticalclient_reference/kosli_create_attestation-type.md:87 — the backticks the CLI added around jq this release came through as ^ characters. The published accordion title reads "...with schema and ^jq^ evaluation rules". Backticks are valid there — kosli_fingerprint.md:103, :109, :115 already use them and render fine — and the same jq → `jq` change landed cleanly in the body prose (lines 22–38), so this is specific to the accordion-title escaping path. Details and a drop-in suggestion are inline. Because these pages come from kosli docs (.github/workflows/update-cli-docs.yml:41-45), the durable fix is in the kosli-dev/cli generator — a hand-edit here is overwritten by the next release. Fix this → Improvementkosli_snapshot_azure.md:22 — inline. British honours (CLAUDE.md requires American spelling; Vale's swap list doesn't cover honour and no workflow runs Vale, so nothing catches it), and the sentence restates the shared .kosli_ignore block that immediately follows on lines 23–25. kosli_attest_jira.md:46-48 — inline. The new text contradicts line 45: that line says wrong credentials are "reported as non existing Jira issue", the new text says they're reported as "not confirmed rather than silently as missing". Also "a warning naming them is printed" is ambiguous about what gets named. kosli_attest_sonar.md:29 — inline. Colon splice joining two independent sentences; should be a period. The rest of the --sonar-branch addition is internally consistent — flag table (line 80), mutual exclusion with --pull-request (lines 69 and 80), and the new example accordion (line 165) all agree. Suggestionkosli_diff_snapshots.md:254-259 — the regenerated live example now has both changed and not-changed as empty arrays (previously not-changed was populated). The flagship example for a diff command no longer demonstrates its two most interesting fields. Consider curating or pinning the snapshot pair used for this example so the output stays illustrative across regenerations. kosli_get_snapshot.md:4266 and :6861, plus kosli_log_environment.md — the regenerated output now embeds two long multi-paragraph cyber-dojo commit messages that narrate an unfixed Kosli CLI bug: "kosli attest copies evidence with PreserveOwner ... That behaviour looks like a bug and is written up in ../kosli-cli-preserve-owner-bug.md for an issue against kosli-dev/cli." Public reference docs are now carrying an internal bug report and a local file path as sample data (and two instances of British "behaviour"). Truncating message fields in generated example output would keep this class of content off the site. Verified clean
Two notes on scope: the PR title says "CLI and helm reference" but no helm/ files changed — presumably no chart changes in this release, worth confirming. And I could not run mint broken-links (the mint CLI isn't installed on this runner), so link resolution was checked by inspection only; all changed external links are github.com/app.kosli.com URLs from regenerated live data. This review is advisory — no changes requested, nothing committed. |
Sorry, something went wrong.
| ``` | ||
| </Accordion> | ||
| <Accordion title="create/update a custom attestation type with schema and jq evaluation rules"> | ||
| <Accordion title="create/update a custom attestation type with schema and ^jq^ evaluation rules"> |
There was a problem hiding this comment.
Critical — garbled markup in the rendered accordion title.
The backticks the CLI added around jq in this release came through as ^ characters, so the published page reads "...with schema and ^jq^ evaluation rules".
Backticks are valid in an <Accordion> attribute — client_reference/kosli_fingerprint.md:103, :109 and :115 already use them and render correctly. Note the same jq → `jq` change was applied cleanly in the body prose above (lines 22–38), so this is specific to the accordion-title escaping path.
These pages are produced by kosli docs (.github/workflows/update-cli-docs.yml:41-45), so the durable fix is in the kosli-dev/cli docs generator — a hand-edit here gets overwritten by the next release. Worth an upstream issue; the suggestion below unblocks this release if you'd rather not wait.
| <Accordion title="create/update a custom attestation type with schema and ^jq^ evaluation rules"> | |
| <Accordion> |
Sorry, something went wrong.
| will not match. See | ||
| https://learn.microsoft.com/en-us/azure/azure-functions/functions-app-settings#website_run_from_package | ||
|
|
||
| For zip-deployed apps, the fingerprint honours a `.kosli_ignore` file at the root of the deployed package. |
There was a problem hiding this comment.
Improvement — British spelling, and the sentence duplicates the paragraph below it.
Two things on this new lead-in line:
- honours is British. CLAUDE.md requires American spelling ("organization, behavior, color"). Vale's styles/Kosli/AmericanSpelling.yml doesn't have honour in its swap list and no workflow runs Vale, so nothing catches this automatically — but it's still a convention break on the published page.
- It restates what the next three lines already say. Lines 23–25 are the standard .kosli_ignore block used verbatim on eight other pages in this PR; this extra sentence in front of it is redundant except for the "zip-deployed apps" qualifier.
Suggest keeping just the qualifier, e.g. "For zip-deployed apps, the fingerprint respects a .kosli_ignore file at the root of the deployed package." followed by the shared block — or dropping the lead-in entirely. Fix belongs in the CLI's command long-description, not here.
Sorry, something went wrong.
| existing Jira issues. | ||
| If you have wrong Jira credentials or wrong Jira-base-url it will be reported as non existing Jira issue. | ||
| This is because Jira returns same 404 error code in all cases. | ||
| This is because Jira returns same 404 error code in all cases. When Jira's response shows that it did not |
There was a problem hiding this comment.
Improvement — the new sentence contradicts the one before it.
Line 45 still says wrong credentials or a wrong base URL "will be reported as non existing Jira issue". The new text on 46–48 says the opposite for the credentials case: the issue is "reported as not confirmed rather than silently as missing". A reader hitting a credential failure gets two different answers about what Kosli reports.
Also, "a warning naming them is printed" is ambiguous — them reads back to "the credentials", but naming which credentials? (the username? the flag that supplied them?) Spelling out what the warning identifies would make this actionable.
Suggest reworking the paragraph upstream as a single statement, roughly: a wrong base URL still surfaces as a non-existent issue because Jira returns 404 either way, but a credential rejection is detected and reported as not confirmed, with a warning identifying the credentials — use --debug to see the status Jira returned per issue.
Sorry, something went wrong.
| 2. Providing the Sonar project key and either the revision or the pull-request ID of the scan (plus the SonarQube server URL if relevant). | ||
| For branch scans: if running the Kosli CLI in some CI/CD pipeline, the revision is defaulted to the commit SHA. If you are running the command locally, | ||
| or have overriden the revision in SonarQube via parameters to the Sonar scanner, you can provide the correct revision using the `--sonar-revision` flag. | ||
| 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: |
There was a problem hiding this comment.
Suggestion — colon splice.
The colon joins two independent sentences ("...using the --sonar-branch flag:" / "SonarQube searches only the main branch..."). The second clause is a rationale, not a list or elaboration the colon is introducing. A period reads correctly:
...also provide the branch name using the --sonar-branch flag. SonarQube searches only the main branch unless it is told otherwise, so without it the scan cannot be found.
The rest of the --sonar-branch addition is consistent — the flag table entry (line 80), the mutual exclusion with --pull-request (lines 69 and 80), and the new example accordion (line 165) all agree.
Sorry, something went wrong.
Automated update of CLI and Helm reference documentation for release v2.39.0.