You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
feat: introduce kosli next product for forward-looking docs
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.
description: Use when writing or editing docs for Kosli Next - the docs surface for forward-looking concepts and preview features. Triggers on mentions of "Kosli Next", "concept docs", "preview feature docs", or any work on files under `kosli_next/`. Covers where files go, required front matter and banners, navigation updates, and tone.
4
+
---
5
+
6
+
# Writing for Kosli Next
7
+
8
+
Kosli Next is a separate Mintlify Product (alongside "Product") for content that is **not currently available in Kosli**. Use it for concepts (ideas we're considering) and preview features (opt-in pre-GA features).
9
+
10
+
If the content describes something shippable today, it does NOT belong in Kosli Next - it goes in the main "Product" surface under `understand_kosli/`, `getting_started/`, etc.
11
+
12
+
## Decision flow
13
+
14
+
1.**Is the feature available to all customers today?** → Main docs. Stop reading this skill.
15
+
2.**Is it an idea or direction we want feedback on, but nothing is built yet?** → Kosli Next → Concepts.
16
+
3.**Is it real, usable, but opt-in / pre-GA?** → Kosli Next → Preview.
17
+
18
+
## File locations
19
+
20
+
| Content type | Directory |
21
+
|---|---|
22
+
| Concept page |`kosli_next/concepts/<slug>.mdx`|
23
+
| Preview page |`kosli_next/preview/<slug>.mdx`|
24
+
25
+
Use lowercase, underscore-separated slugs to match the rest of the repo (`kosli_next/concepts/my_concept.mdx`).
26
+
27
+
## Required page template
28
+
29
+
Every Kosli Next page starts with this shape:
30
+
31
+
```mdx
32
+
---
33
+
title: "Short, specific title"
34
+
description: "One sentence describing the page purpose."
{/* or: import { PreviewBanner } from '/snippets/kosli-next-banner.mdx'; */}
40
+
41
+
<ConceptBanner />
42
+
{/* or: <PreviewBanner /> */}
43
+
44
+
Page content goes here.
45
+
```
46
+
47
+
The banner snippet (`snippets/kosli-next-banner.mdx`) is the single source of truth for the disclaimer + feedback CTA. Do NOT inline a custom disclaimer.
48
+
49
+
## Navigation update (required)
50
+
51
+
Add the new page path to `config/navigation.json` under the matching tab in the **Kosli Next** product:
A page that isn't in `config/navigation.json` won't appear in the sidebar. This is a core repo rule.
57
+
58
+
## Tone
59
+
60
+
Standard Kosli writing rules from the project `CLAUDE.md` still apply:
61
+
62
+
- Sentence case for headings.
63
+
- Active voice and imperative mood.
64
+
- "Kosli" - not "the Kosli platform" or "KOSLI".
65
+
- Root-relative internal links (`/kosli_next/concepts/foo`, not `../foo`).
66
+
- No em-dashes. Use hyphens or rewrite the sentence.
67
+
68
+
Two Kosli Next-specific additions:
69
+
70
+
-**Be honest about status.** Don't write a Concept page in the present tense as if it works ("Kosli reports X..."). Write in the conditional ("Kosli would report X...") so readers aren't misled into thinking the feature exists.
71
+
-**Invite feedback.** End each page with a short prompt: "Tell us what you think - email support@kosli.com." (The banner says this too; an end-of-page nudge is fine.)
72
+
73
+
## Form
74
+
75
+
Diátaxis is NOT enforced inside Kosli Next. Pick whichever shape best explains the idea:
76
+
77
+
- A short PR/FAQ-style explainer (problem → proposed approach → open questions) is often a good fit for Concepts.
78
+
- A how-to + reference combination tends to fit Previews.
79
+
80
+
## Verification
81
+
82
+
Before opening a PR:
83
+
84
+
1. Run `mint dev` and confirm the page appears under the right tab in the Kosli Next product switcher.
These instructions apply to the Mintlify agent across the dashboard, the `@Mintlify` Slack bot, and the docs site assistant. Read them before answering any question or writing any documentation.
4
+
5
+
## Project context
6
+
7
+
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:
8
+
9
+
-**`Product`** - documentation for what Kosli does today. This is the default and the authoritative source for "how do I do X" questions.
10
+
-**`Kosli Next`** - forward-looking content. Two tabs:
11
+
-**Concepts** (`kosli_next/concepts/`) - ideas we're considering. Nothing in here is built.
12
+
-**Preview** (`kosli_next/preview/`) - real features available to opt-in customers ahead of general availability. Behaviour can still change.
13
+
14
+
## Retrieval rules
15
+
16
+
**Default to the `Product` surface.** When a customer asks how to do something, answer from the `Product` Product only.
17
+
18
+
**Use Kosli Next only when:**
19
+
20
+
1. The user explicitly asks about a future, concept, preview, beta, or roadmap topic, OR
21
+
2. No answer exists in the `Product` surface AND a Kosli Next page is directly relevant.
22
+
23
+
**Never** answer a "how do I do X today" question using a Kosli Next page without the disclaimer below.
24
+
25
+
## Disclaimer when citing Kosli Next
26
+
27
+
Every answer that draws on a page under `kosli_next/` must begin with one of:
28
+
29
+
- For Concepts: *"This isn't available in Kosli today - it's a concept we're sharing to gather feedback."*
30
+
- For Previews: *"This is a preview feature, available to opt-in customers. Behaviour can still change."*
31
+
32
+
End the answer with an invitation to share feedback at `support@kosli.com`.
33
+
34
+
## When writing documentation
35
+
36
+
These rules apply to any documentation you author or edit, including via the `@Mintlify` Slack bot.
37
+
38
+
### Where things go
39
+
40
+
- Features generally available today → main docs under `understand_kosli/`, `getting_started/`, `administration/`, `integrations/`, `tutorials/`, `troubleshooting/`, `client_reference/`, etc.
41
+
- Ideas not built yet → `kosli_next/concepts/<slug>.mdx` with `tag: "Concept"` and the `<ConceptBanner />` from `/snippets/kosli-next-banner.mdx`.
42
+
- Opt-in pre-GA features → `kosli_next/preview/<slug>.mdx` with `tag: "Preview"` and the `<PreviewBanner />` from `/snippets/kosli-next-banner.mdx`.
43
+
44
+
Every new page must be registered in `config/navigation.json` under the matching Product and tab.
45
+
46
+
### Required Kosli Next page shape
47
+
48
+
```mdx
49
+
---
50
+
title: "Short, specific title"
51
+
description: "One sentence describing the page purpose."
Do not inline a custom disclaimer. The banner snippet is the single source of truth so the feedback channel can be swapped later without editing every page.
63
+
64
+
For Concept pages, write in the conditional ("Kosli would report X..."), not the present tense, so readers are not misled into thinking the feature exists.
65
+
66
+
### Style and tone
67
+
68
+
- Refer to the product as **Kosli** - never "the Kosli platform" or "KOSLI".
69
+
- Use "audit trail" not "audit log"; "attest" not "certify".
70
+
- Active voice and imperative mood for instructions ("Run `kosli attest`", not "You should run").
71
+
- Sentence case for all headings.
72
+
- Root-relative internal links only (`/getting_started/install`, not `../install`).
73
+
- No em-dashes. Use hyphens or rewrite the sentence.
74
+
75
+
### MDX components
76
+
77
+
Prefer the components already in use in this repo:
78
+
79
+
-`<Steps>` / `<Step>` for sequential procedures.
80
+
-`<Tabs>` / `<Tab>` for platform-specific alternatives.
81
+
-`<Card>` / `<CardGroup>` / `<Columns>` for navigational tiles.
82
+
-`<Accordion>` / `<AccordionGroup>` for progressive disclosure.
83
+
-`<Tip>` / `<Info>` / `<Warning>` / `<Note>` for callouts, sparingly.
84
+
-`<CodeGroup>` for the same command in multiple languages.
85
+
-`<Frame>` for wrapping images.
86
+
87
+
### Do not
88
+
89
+
- Do not edit pages under `essentials/` - they are Mintlify's own content, not Kosli's.
90
+
- Do not add new snippets unless the content is genuinely reused in 2+ pages.
91
+
- Do not propose changes that bypass `config/navigation.json` - pages not in nav do not appear on the site.
92
+
93
+
## Reference
94
+
95
+
- Writer skill (for Claude in the repo): `.claude/skills/kosli-next-writer/SKILL.md`
Copy file name to clipboardExpand all lines: CLAUDE.md
+25-23Lines changed: 25 additions & 23 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,11 +4,11 @@ This file governs repo-specific conventions for Claude Code. Skills and system p
4
4
5
5
## Core rules
6
6
7
-
These are non-negotiable — follow them regardless of other instructions:
7
+
These are non-negotiable - follow them regardless of other instructions:
8
8
9
-
1. Never commit directly to `main`— always work on a branch and open a PR.
9
+
1. Never commit directly to `main`- always work on a branch and open a PR.
10
10
2. Never create a page file without also adding it to `navigation` in `config/navigation.json`.
11
-
3. Never use relative links — always use root-relative paths (e.g., `/getting_started/install`).
11
+
3. Never use relative links - always use root-relative paths (e.g., `/getting_started/install`).
12
12
4. Commit messages and PR titles must follow [Conventional Commits](https://www.conventionalcommits.org/): `type: short description` (lowercase, no period). Common types: `feat`, `fix`, `docs`, `style`, `chore`.
13
13
5. Run `mint broken-links` before committing navigation or link changes.
14
14
@@ -31,13 +31,13 @@ Requires Node.js v19+.
31
31
32
32
## Architecture
33
33
34
-
-**`docs.json`**— Central config: theme, API settings, logos. Uses `$ref` to compose from files in `config/`.
|`<CodeGroup>`| Same command in multiple languages/tools |
72
72
|`<Frame>`| Wrapping images |
73
73
74
74
### Writing style
75
75
76
76
- Use active voice and imperative mood for instructions ("Run `kosli attest`", not "You should run").
77
-
- Refer to the product as **Kosli**— not "the Kosli platform" or "KOSLI".
77
+
- Refer to the product as **Kosli**- not "the Kosli platform" or "KOSLI".
78
78
- Use "audit trail" not "audit log"; "attest" not "certify".
79
79
- Sentence case for all headings.
80
+
- No em-dashes. Use hyphens or rewrite the sentence.
80
81
81
82
## Don'ts
82
83
83
-
- Don't use relative links — they break when pages move.
84
-
- Don't create a page without updating `config/navigation.json`— it won't appear in the site.
85
-
- Don't edit files in `essentials/`— they are Mintlify's content, not Kosli's.
84
+
- Don't use relative links - they break when pages move.
85
+
- Don't create a page without updating `config/navigation.json`- it won't appear in the site.
86
+
- Don't edit files in `essentials/`- they are Mintlify's content, not Kosli's.
86
87
- Don't add content to `snippets/` unless it is genuinely reused in 2+ pages.
87
88
- Don't commit image files without placing them in an appropriate subdirectory.
88
-
- Don't push to `main` directly — always use a PR.
89
+
- Don't push to `main` directly - always use a PR.
89
90
90
91
## Skills
91
92
92
93
When available, prefer skills over ad-hoc approaches:
93
94
94
-
-**PR creation** — use the `pr-creator` skill if available.
95
-
-**Changelog entries** — use the `changelog-creator` skill if available. Follow the existing `<Update>` format in `changelog/index.mdx` exactly:
95
+
-**Kosli Next writing** - for any docs work under `kosli_next/` (concepts and preview features), use the `kosli-next-writer` skill in `.claude/skills/kosli-next-writer/`. It covers file locations, the required banner snippet, navigation updates, and tone.
96
+
-**PR creation** - use the `pr-creator` skill if available.
97
+
-**Changelog entries** - use the `changelog-creator` skill if available. Follow the existing `<Update>` format in `changelog/index.mdx` exactly:
0 commit comments