docs: empty flag values by JonJagger · Pull Request #365 · kosli-dev/docs

JonJagger · 2026-08-18T13:18:28Z

No description provided.

A pipeline that has been quietly passing an empty flag value starts failing on the release that refuses it, and the person it fails for reads the docs, not the release notes. The FAQ section follows the boolean-flags one it sits below: the failing command, the error verbatim, why the value is usually empty, and what to do about it. The changelog entry says the accepting was the bug, so a new failure reads as a diagnosis rather than a regression. Both carry vX.Y.0 as a placeholder until the release version is decided.

Both sides add to the top of the changelog, so changelog/index.mdx conflicted. Kept both, with the unreleased empty-flag-values entry above main's August entries, since it describes a release that has not happened yet. Main's side also brings the regenerated client_reference pages, which carry the flag-type column from #1068. That accounts for most of the file count here.

The FAQ and changelog were written before the version was known. A customer reading either needs to know which version changed under them, so the version is the part that cannot stay a placeholder.

mintlify · 2026-08-18T13:18:33Z

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

Project	Status	Preview	Updated (UTC)
kosli	🟢 Ready	View Preview	Aug 18, 2026, 1:20 PM

claude · 2026-08-18T13:18:53Z

Claude finished @mbevc1's task in 1m 6s —— View job

Review of PR #365 — Empty flag values

Previously flagged issues — all resolved ✓

The placeholder date (MONTH DD, 2026), British spelling (behaviour), and duplicate line issues from earlier reviews have all been fixed.

`changelog/index.mdx`

No issues. The new <Update> entry follows the established format, uses the correct tags={["CLI"]}, and cross-links to the FAQ with a root-relative path (/faq/faq#empty-flag-values).

`faq/faq.md`

No issues. The new ## Empty flag values section sits outside <AccordionGroup>, consistent with the existing ## Boolean flags section. American spelling is used throughout. No relative links. The content is clear, gives concrete examples, and provides actionable guidance.

Summary

Both files are existing pages already in config/navigation.json — no navigation update needed. No relative links, no spelling issues, no structural problems. The PR looks good to merge.

changelog/index.mdx conflicted again because both sides add entries at the top. Kept both, with the unreleased v2.37.0 entry above main's August 11-14 entries. Main's newest CLI release is v2.36.6, so v2.37.0 remains the next version. Worth noting the pattern: this file will conflict on every merge while the branch is open, always the same way and always resolved the same way. If that becomes tiresome, the alternative is to keep the changelog entry out of this branch and add it at release time, when the date is known anyway. Merge branch 'main' into empty-flag-values

claude · 2026-08-18T13:26:01Z

 rss: true
 ---

+<Update label="MONTH DD, 2026" description="v2.37.0" tags={["CLI"]}>


Critical — Placeholder date
"MONTH DD, 2026" is still a placeholder. Every other changelog entry uses a real date. This will render as-is on the live site.
Suggested change
<Updatelabel="MONTH DD, 2026"description="v2.37.0"tags={["CLI"]}>
<Updatelabel="August 18, 2026"description="v2.37.0"tags={["CLI"]}>
Adjust the date to match the actual release date.

Co-authored-by: claude[bot] <209825114+claude[bot]@users.noreply.github.com>

claude · 2026-08-18T13:29:03Z

 rss: true
 ---

+<Update label="MONTH DD, 2026" description="v2.37.0" tags={["CLI"]}>


Critical — Placeholder date still present
This was flagged in a prior review and is still unresolved. Every other changelog entry uses a real date.
Suggested change
<Updatelabel="MONTH DD, 2026"description="v2.37.0"tags={["CLI"]}>
<Updatelabel="August 18, 2026"description="v2.37.0"tags={["CLI"]}>
Adjust to the actual release date.

Co-authored-by: claude[bot] <209825114+claude[bot]@users.noreply.github.com>

claude · 2026-08-18T13:31:59Z

 rss: true
 ---

+<Update label="MONTH DD, 2026" description="v2.37.0" tags={["CLI"]}>


Critical — Placeholder date
"MONTH DD, 2026" is still a placeholder. Every other changelog entry uses a real date. This will render as-is on the live site.
Suggested change
<Updatelabel="MONTH DD, 2026"description="v2.37.0"tags={["CLI"]}>
<Updatelabel="August 18, 2026"description="v2.37.0"tags={["CLI"]}>
Adjust the date to match the actual release date.

Co-authored-by: claude[bot] <209825114+claude[bot]@users.noreply.github.com>

JonJagger added 3 commits August 18, 2026 14:11

docs: name v2.37.0 as the release that refuses empty flag values
9e15ac1
The FAQ and changelog were written before the version was known. A customer reading either needs to know which version changed under them, so the version is the part that cannot stay a placeholder.

JonJagger requested a review from a team as a code owner August 18, 2026 13:18