feat: introduce kosli next product for forward-looking docs

.claude/skills/kosli-next-writer/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: kosli-next-writer
+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.
+---
+
+# Writing for Kosli Next
+
+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).
+
+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.
+
+## Decision flow
+
+1. **Is the feature available to all customers today?** → Main docs. Stop reading this skill.
+2. **Is it an idea or direction we want feedback on, but nothing is built yet?** → Kosli Next → Concepts.
+3. **Is it real, usable, but opt-in / pre-GA?** → Kosli Next → Preview.
+
+## File locations
+
+| Content type | Directory |
+|---|---|
+| Concept page | `kosli_next/concepts/<slug>.mdx` |
+| Preview page | `kosli_next/preview/<slug>.mdx` |
+
+Use lowercase, underscore-separated slugs to match the rest of the repo (`kosli_next/concepts/my_concept.mdx`).
+
+## Required page template
+
+Every Kosli Next page starts with this shape:
+
+```mdx
+---
+title: "Short, specific title"
+description: "One sentence describing the page purpose."
+tag: "Concept"   # or "Preview"
+---
+
+import { ConceptBanner } from '/snippets/kosli-next-banner.mdx';
+{/* or: import { PreviewBanner } from '/snippets/kosli-next-banner.mdx'; */}
+
+<ConceptBanner />
+{/* or: <PreviewBanner /> */}
+
+Page content goes here.
+```
+
+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.
+
+## Navigation update (required)
+
+Add the new page path to `config/navigation.json` under the matching tab in the **Kosli Next** product:
+
+- Concept pages → `products[1].tabs[0].groups[0].pages`
+- Preview pages → `products[1].tabs[1].groups[0].pages`
+
+A page that isn't in `config/navigation.json` won't appear in the sidebar. This is a core repo rule.
+
+## Tone
+
+Standard Kosli writing rules from the project `CLAUDE.md` still apply:
+
+- Sentence case for headings.
+- Active voice and imperative mood.
+- "Kosli" - not "the Kosli platform" or "KOSLI".
+- Root-relative internal links (`/kosli_next/concepts/foo`, not `../foo`).
+- No em-dashes. Use hyphens or rewrite the sentence.
+
+Two Kosli Next-specific additions:
+
+- **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.
+- **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.)
+
+## Form
+
+Diátaxis is NOT enforced inside Kosli Next. Pick whichever shape best explains the idea:
+
+- A short PR/FAQ-style explainer (problem → proposed approach → open questions) is often a good fit for Concepts.
+- A how-to + reference combination tends to fit Previews.
+
+## Verification
+
+Before opening a PR:
+
+1. Run `mint dev` and confirm the page appears under the right tab in the Kosli Next product switcher.
+2. Confirm the banner renders.
+3. Run `mint broken-links`.
+

.gitignore

@@ -2,3 +2,5 @@
 .claude/settings.local.json
 tmp/
 __pycache__/
+docs/superpowers/
+.DS_Store

.mintlify/AGENTS.md

@@ -0,0 +1,96 @@
+# Kosli docs agent instructions
+
+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.
+
+## 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:
+
+- **`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.
+
+## Retrieval rules
+
+**Default to the `Product` surface.** When a customer asks how to do something, answer from the `Product` Product only.
+
+**Use Kosli Next only when:**
+
+1. The user explicitly asks about a future, concept, preview, beta, or roadmap topic, OR
+2. No answer exists in the `Product` surface AND a Kosli Next page is directly relevant.
+
+**Never** answer a "how do I do X today" question using a Kosli Next page without the disclaimer below.
+
+## Disclaimer when citing Kosli Next
+
+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."*
+
+End the answer with an invitation to share feedback at `support@kosli.com`.
+
+## When writing documentation
+
+These rules apply to any documentation you author or edit, including via the `@Mintlify` Slack bot.
+
+### Where things go
+
+- Features generally available today → main docs under `understand_kosli/`, `getting_started/`, `administration/`, `integrations/`, `tutorials/`, `troubleshooting/`, `client_reference/`, etc.
+- Ideas not built yet → `kosli_next/concepts/<slug>.mdx` with `tag: "Concept"` and the `<ConceptBanner />` from `/snippets/kosli-next-banner.mdx`.
+- Opt-in pre-GA features → `kosli_next/preview/<slug>.mdx` with `tag: "Preview"` and the `<PreviewBanner />` from `/snippets/kosli-next-banner.mdx`.
+
+Every new page must be registered in `config/navigation.json` under the matching Product and tab.
+
+### Required Kosli Next page shape
+
+```mdx
+---
+title: "Short, specific title"
+description: "One sentence describing the page purpose."
+tag: "Concept"   # or "Preview"
+---
+
+import { ConceptBanner } from '/snippets/kosli-next-banner.mdx';
+
+<ConceptBanner />
+
+Page content here.
+```
+
+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.
+
+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.
+
+### Style and tone
+
+- Refer to the product as **Kosli** - never "the Kosli platform" or "KOSLI".
+- Use "audit trail" not "audit log"; "attest" not "certify".
+- Active voice and imperative mood for instructions ("Run `kosli attest`", not "You should run").
+- Sentence case for all headings.
+- Root-relative internal links only (`/getting_started/install`, not `../install`).
+- No em-dashes. Use hyphens or rewrite the sentence.
+
+### MDX components
+
+Prefer the components already in use in this repo:
+
+- `<Steps>` / `<Step>` for sequential procedures.
+- `<Tabs>` / `<Tab>` for platform-specific alternatives.
+- `<Card>` / `<CardGroup>` / `<Columns>` for navigational tiles.
+- `<Accordion>` / `<AccordionGroup>` for progressive disclosure.
+- `<Tip>` / `<Info>` / `<Warning>` / `<Note>` for callouts, sparingly.
+- `<CodeGroup>` for the same command in multiple languages.
+- `<Frame>` for wrapping images.
+
+### Do not
+
+- Do not edit pages under `essentials/` - they are Mintlify's own content, not Kosli's.
+- Do not add new snippets unless the content is genuinely reused in 2+ pages.
+- Do not propose changes that bypass `config/navigation.json` - pages not in nav do not appear on the site.
+
+## Reference
+
+- Writer skill (for Claude in the repo): `.claude/skills/kosli-next-writer/SKILL.md`
+- Project conventions: `CLAUDE.md`

CLAUDE.md

@@ -6,9 +6,9 @@ This file governs repo-specific conventions for Claude Code. Skills, plugins, ag
 
 Apply these unless a skill, plugin, agent, or system prompt explicitly overrides them for its scope:
 
-1. Never commit directly to `main` — always work on a branch and open a PR.
+1. Never commit directly to `main` - always work on a branch and open a PR.
 2. Never create a page file without also adding it to `navigation` in `config/navigation.json`.
-3. Never use relative links — always use root-relative paths (e.g., `/getting_started/install`).
+3. Never use relative links - always use root-relative paths (e.g., `/getting_started/install`).
 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`.
 5. Run `mint broken-links` before committing navigation or link changes.
 
@@ -60,13 +60,13 @@ description: One sentence describing the page purpose.
 ---
 ```
 
-- **MUST** Use root-relative paths for internal links: `/understand_kosli/what_is_kosli` ✓ — `../what_is_kosli` ✗
+- **MUST** Use root-relative paths for internal links: `/understand_kosli/what_is_kosli` ✓ - `../what_is_kosli` ✗
 - **MUST** Adding a new page: create the file AND add its path to `navigation` in `config/navigation.json`. Both steps are required.
 - **SHOULD** Follow the [Diátaxis](https://diataxis.fr/) framework when choosing page form:
-  - **Tutorial** — teaches by doing (e.g., "Get familiar with Kosli")
-  - **How-to guide** — step-by-step for a specific goal (e.g., "Report AWS environments")
-  - **Reference** — factual, lookup-oriented (e.g., CLI reference pages)
-  - **Explanation** — concepts and background (e.g., "What is Kosli?")
+  - **Tutorial** - teaches by doing (e.g., "Get familiar with Kosli")
+  - **How-to guide** - step-by-step for a specific goal (e.g., "Report AWS environments")
+  - **Reference** - factual, lookup-oriented (e.g., CLI reference pages)
+  - **Explanation** - concepts and background (e.g., "What is Kosli?")
 - **MAY** Add an `icon` field to front matter using [Font Awesome](https://fontawesome.com/icons) names.
 
 ### MDX Components
@@ -77,32 +77,34 @@ description: One sentence describing the page purpose.
 | `<Tabs>` / `<Tab>` | Platform-specific or alternative content |
 | `<Card>` / `<CardGroup>` | Navigational links, feature highlights |
 | `<Accordion>` / `<AccordionGroup>` | Progressive disclosure, FAQs |
-| `<Tip>` / `<Info>` / `<Warning>` / `<Note>` | Callouts — use sparingly |
+| `<Tip>` / `<Info>` / `<Warning>` / `<Note>` | Callouts - use sparingly |
 | `<CodeGroup>` | Same command in multiple languages/tools |
 | `<Frame>` | Wrapping images |
 
 ### Writing style
 
 - Use active voice and imperative mood for instructions ("Run `kosli attest`", not "You should run").
-- Refer to the product as **Kosli** — not "the Kosli platform" or "KOSLI".
+- Refer to the product as **Kosli** - not "the Kosli platform" or "KOSLI".
 - Use "audit trail" not "audit log"; "attest" not "certify".
 - Use American spelling (organization, behavior, color), not British. Enforced by Vale via `styles/Kosli/AmericanSpelling.yml`.
 - Sentence case for all headings.
+- No em-dashes. Use hyphens or rewrite the sentence.
 
 ## Don'ts
 
 - 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.
 - Don't add content to `snippets/` unless it is genuinely reused in 2+ pages.
 - Don't commit image files without placing them in an appropriate subdirectory.
-- Don't push to `main` directly — always use a PR.
+- Don't push to `main` directly - always use a PR.
 
 ## Skills
 
 When available, prefer skills over ad-hoc approaches:
 
-- **PR creation** — use the `pr-creator` skill if available.
-- **Changelog entries** — use the `changelog-creator` skill if available. Follow the existing `<Update>` format in `changelog/index.mdx` exactly:
+- **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.
+- **PR creation** - use the `pr-creator` skill if available.
+- **Changelog entries** - use the `changelog-creator` skill if available. Follow the existing `<Update>` format in `changelog/index.mdx` exactly:
   ```mdx
   <Update label="Month Year" description="vX.X.X" tags={["Product Name"]}>
 

config/footer.json

@@ -25,6 +25,10 @@
           "label": "Labs",
           "href": "/labs"
         },
+        {
+          "label": "Kosli Next",
+          "href": "/kosli_next/index"
+        },
         {
           "label": "Blog",
           "href": "https://kosli.com/blog/"