feat: introduce kosli next product for forward-looking docs#237
feat: introduce kosli next product for forward-looking docs#237dangrondahl wants to merge 4 commits into
Conversation
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
Add a second Mintlify Product, "Kosli Next", alongside the existing "Product" surface, for content that is not yet available in Kosli. Kosli Next has two tabs: - Concepts - ideas we want feedback on; nothing built. - Preview - opt-in pre-GA features. Includes: - Restructured config/navigation.json under a top-level products array. - New kosli_next/ landing, concepts, and preview seed pages. - Shared banner snippet (snippets/kosli-next-banner.mdx) carrying the disclaimer and feedback channel, so it can be swapped centrally. - .mintlify/AGENTS.md with retrieval rules, the required disclaimer when citing Kosli Next, and writing rules for the @mintlify Slack bot and dashboard agent. - .claude/skills/kosli-next-writer/ for repo-local Claude sessions, plus a pointer from CLAUDE.md. - No-em-dash rule added to CLAUDE.md and applied across the file. - Kosli Next link added to the footer.
- Collapse Kosli Next from two tabs to direct groups (Concepts, Preview) under the product. - Add the Controls concept page and the MCP Server preview page with matching images. - Switch banners to a Callout component, with peach (Concepts) and blue (Preview) colours, and recolour the sidebar tag pills to match via data-nav-tag selectors in style.css. - Add light/dark hero images to the Kosli Next landing page. - Ignore .DS_Store globally.
|
Claude finished @dangrondahl's task in 2m 24s —— View job PR Review: Kosli Next Product
Review summaryGood structure overall. The two-product split is clean, the banner snippet is a smart single-source-of-truth pattern, and the MCP Server page is well-written with practical install tabs. A few things to address: Critical (1)
Improvements (5)
Suggestions (3)
Other observations
|
![claude[bot]](https://cdn.statically.io/img/avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
| It contains two kinds of content: | ||
|
|
||
| - **Concepts** - ideas and directions we're considering. Nothing here is built yet. We publish them to gather feedback on the problem and the proposed approach. | ||
| - **Preview** - real features available to opt-in customers ahead of general availability. Behaviour can still change. |
There was a problem hiding this comment.
Improvement - British spelling: "Behaviour" should be "Behavior" per the writing style guide in CLAUDE.md (American spelling enforced by Vale).
| - **Preview** - real features available to opt-in customers ahead of general availability. Behaviour can still change. | |
| - **Preview** - real features available to opt-in customers ahead of general availability. Behavior can still change. |
|
|
||
| ## Project context | ||
|
|
||
| Kosli is a platform for recording changes in software and business processes so customers can prove compliance and maintain security without slowing delivery. The docs site is organised into two Mintlify Products: |
There was a problem hiding this comment.
Improvement - British spelling: "organised" should be "organized" per the CLAUDE.md style guide (American spelling).
| Kosli is a platform for recording changes in software and business processes so customers can prove compliance and maintain security without slowing delivery. The docs site is organised into two Mintlify Products: | |
| Kosli is a platform for recording changes in software and business processes so customers can prove compliance and maintain security without slowing delivery. The docs site is organized into two Mintlify Products: |
| - **`Product`** - documentation for what Kosli does today. This is the default and the authoritative source for "how do I do X" questions. | ||
| - **`Kosli Next`** - forward-looking content. Two tabs: | ||
| - **Concepts** (`kosli_next/concepts/`) - ideas we're considering. Nothing in here is built. | ||
| - **Preview** (`kosli_next/preview/`) - real features available to opt-in customers ahead of general availability. Behaviour can still change. |
There was a problem hiding this comment.
Improvement - British spelling: "Behaviour" should be "Behavior" for consistency with the American spelling rule.
| - **Preview** (`kosli_next/preview/`) - real features available to opt-in customers ahead of general availability. Behaviour can still change. | |
| - **Preview** (`kosli_next/preview/`) - real features available to opt-in customers ahead of general availability. Behavior can still change. |
| Every answer that draws on a page under `kosli_next/` must begin with one of: | ||
|
|
||
| - For Concepts: *"This isn't available in Kosli today - it's a concept we're sharing to gather feedback."* | ||
| - For Previews: *"This is a preview feature, available to opt-in customers. Behaviour can still change."* |
There was a problem hiding this comment.
Improvement - Same British spelling here: "Behaviour" → "Behavior".
| - For Previews: *"This is a preview feature, available to opt-in customers. Behaviour can still change."* | |
| - For Previews: *"This is a preview feature, available to opt-in customers. Behavior can still change."* |
| - No em-dashes. Use hyphens or rewrite the sentence. | ||
|
|
||
| ## Don'ts | ||
|
|
There was a problem hiding this comment.
Improvement - The PR adds a "no em-dashes" rule and replaces some — with -, but several em-dashes remain in this Don'ts section (lines 94, 95, 98) and throughout the Architecture section (lines 3, 34-41, 47, 63, 66-69, 80, 87, 104-105). Consider a sweep to clean them all up in this PR since it introduces the rule.
| - Don't use relative links - they break when pages move. | |
| - Don't create a page without updating `config/navigation.json` - it won't appear in the site. |
| @@ -0,0 +1,15 @@ | |||
| export const ConceptBanner = () => ( | |||
| <Callout icon="flask" iconType="solid" color="#FFB4AA"> | |||
| <strong>This is a concept</strong> and not available in Kosli today. We're sharing it to gather your feedback. <p /> | |||
There was a problem hiding this comment.
Suggestion - The <p /> self-closing tag is being used as a visual separator, but it's semantically a self-closing empty paragraph. A <br /> would be more conventional here if the intent is a line break between the two sentences.
| ## Prerequisites | ||
|
|
||
| - Node.js v20 or higher | ||
| - A [Kosli API token](/getting_started/service-accounts) |
There was a problem hiding this comment.
Suggestion - The link /getting_started/service-accounts works via a redirect to /getting_started/authenticating_to_kosli. Consider linking directly to the canonical path to avoid the redirect hop and reduce fragility.
| - A [Kosli API token](/getting_started/service-accounts) | |
| - A [Kosli API token](/getting_started/authenticating_to_kosli) |
| @@ -0,0 +1,12 @@ | |||
| --- | |||
| title: "Concepts" | |||
| description: "Ideas and directions we're considering for Kosli. Nothing here is built yet — we publish them to gather feedback." | |||
There was a problem hiding this comment.
Improvement - Em-dash in the description violates the new no-em-dash rule added in this same PR. Also, consider adding tag: "Concept" to front matter to match the required template in the skill file.
| description: "Ideas and directions we're considering for Kosli. Nothing here is built yet — we publish them to gather feedback." | |
| description: "Ideas and directions we're considering for Kosli. Nothing here is built yet - we publish them to gather feedback." |
| It contains two kinds of content: | ||
|
|
||
| - **Concepts** - ideas and directions we're considering. Nothing here is built yet. We publish them to gather feedback on the problem and the proposed approach. | ||
| - **Preview** - real features available to opt-in customers ahead of general availability. Behaviour can still change. |
There was a problem hiding this comment.
Improvement - British spelling: "Behaviour" should be "Behavior" per the CLAUDE.md writing style guide (American spelling).
| - **Preview** - real features available to opt-in customers ahead of general availability. Behaviour can still change. | |
| - **Preview** - real features available to opt-in customers ahead of general availability. Behavior can still change. |
|
|
||
| ## Project context | ||
|
|
||
| Kosli is a platform for recording changes in software and business processes so customers can prove compliance and maintain security without slowing delivery. The docs site is organised into two Mintlify Products: |
There was a problem hiding this comment.
Improvement - British spelling: "organised" should be "organized" per the CLAUDE.md style guide (American spelling).
| Kosli is a platform for recording changes in software and business processes so customers can prove compliance and maintain security without slowing delivery. The docs site is organised into two Mintlify Products: | |
| Kosli is a platform for recording changes in software and business processes so customers can prove compliance and maintain security without slowing delivery. The docs site is organized into two Mintlify Products: |
| - **`Product`** - documentation for what Kosli does today. This is the default and the authoritative source for "how do I do X" questions. | ||
| - **`Kosli Next`** - forward-looking content. Two tabs: | ||
| - **Concepts** (`kosli_next/concepts/`) - ideas we're considering. Nothing in here is built. | ||
| - **Preview** (`kosli_next/preview/`) - real features available to opt-in customers ahead of general availability. Behaviour can still change. |
There was a problem hiding this comment.
Improvement - British spelling: "Behaviour" should be "Behavior".
| - **Preview** (`kosli_next/preview/`) - real features available to opt-in customers ahead of general availability. Behaviour can still change. | |
| - **Preview** (`kosli_next/preview/`) - real features available to opt-in customers ahead of general availability. Behavior can still change. |
| Every answer that draws on a page under `kosli_next/` must begin with one of: | ||
|
|
||
| - For Concepts: *"This isn't available in Kosli today - it's a concept we're sharing to gather feedback."* | ||
| - For Previews: *"This is a preview feature, available to opt-in customers. Behaviour can still change."* |
There was a problem hiding this comment.
Improvement - Same: "Behaviour" → "Behavior".
| - For Previews: *"This is a preview feature, available to opt-in customers. Behaviour can still change."* | |
| - For Previews: *"This is a preview feature, available to opt-in customers. Behavior can still change."* |
|
|
||
| Page content goes here. | ||
| ``` | ||
|
|
There was a problem hiding this comment.
Critical - These navigation paths are wrong. Kosli Next uses flat groups (no tabs), so the correct JSON paths are:
- Concept pages →
products[1].groups[1].pages - Preview pages →
products[1].groups[2].pages
The current paths reference .tabs[0] and .tabs[1] which don't exist, and would mislead AI tools updating navigation.
| - Concept pages → `products[1].groups[1].pages` | |
| - Preview pages → `products[1].groups[2].pages` |
| /* ─── Kosli Next page tags ─────────────────────────────────────────────────── */ | ||
| /* | ||
| * Recolor the sidebar "Concept" and "Preview" tag pills to match the | ||
| * Kosli Next callout colour, so the future-state signal is consistent |
There was a problem hiding this comment.
Suggestion - British spelling in comment: "colour" → "color" for consistency with the American spelling rule. Minor since it's a CSS comment, but keeps things consistent.
| * Kosli Next callout colour, so the future-state signal is consistent | |
| * Recolor the sidebar "Concept" and "Preview" tag pills to match the | |
| * Kosli Next callout color, so the future-state signal is consistent |
| ## Prerequisites | ||
|
|
||
| - Node.js v20 or higher | ||
| - A [Kosli API token](/getting_started/service-accounts) |
There was a problem hiding this comment.
Suggestion - This link works via a redirect. Consider linking directly to the canonical path to avoid the redirect hop and reduce fragility if the redirect is ever removed.
| - A [Kosli API token](/getting_started/service-accounts) | |
| - A [Kosli API token](/getting_started/authenticating_to_kosli) |
| @@ -0,0 +1,15 @@ | |||
| export const ConceptBanner = () => ( | |||
| <Callout icon="flask" iconType="solid" color="#FFB4AA"> | |||
| <strong>This is a concept</strong> and not available in Kosli today. We're sharing it to gather your feedback. <p /> | |||
There was a problem hiding this comment.
Suggestion - The <p /> self-closing tag is being used as a visual separator, but semantically it's an empty paragraph. A <br /> would be more conventional here if the intent is a line break.
(Same on line 11.)
1 participant
Summary
Introduce a second Mintlify Product, Kosli Next, alongside the existing Product surface. Kosli Next is the home for forward-looking content we want customer feedback on, kept clearly separate from what Kosli does today.
config/navigation.jsonto use a top-levelproductsarray. Existing tabs sit under "Product"; "Kosli Next" has direct groups for Concepts and Preview.Callout-based banner snippet (snippets/kosli-next-banner.mdx) carrying the disclaimer and feedback channel for every Kosli Next page. Single source of truth so the feedback channel can be swapped later.Concept,Preview) recoloured viastyle.cssto match their on-page callouts..mintlify/AGENTS.mddefines retrieval rules, the required disclaimer when citing Kosli Next, and writing rules - applies to the dashboard agent, the @mintlify Slack bot, and the docs site assistant..claude/skills/kosli-next-writer/plus a pointer fromCLAUDE.md, so colleagues writing Kosli Next pages get consistent guidance.CLAUDE.mdand applied across files.Test plan
mint devlocally - Product switcher shows "Product" and "Kosli Next"; default landing is "Product".mint broken-linkspasses.