Skip to content

CLAUDE.md

Latest commit

 

History

History
138 lines (101 loc) · 6.33 KB

CLAUDE.md

File metadata and controls

138 lines (101 loc) · 6.33 KB
Raw

CLAUDE.md

This file governs repo-specific conventions for Claude Code. Skills, plugins, agents, and system prompts govern their own domains and take precedence within their scope — don't let the rules below override them.

Core rules

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.
  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).
  4. Commit messages and PR titles must follow Conventional Commits: type: short description (lowercase, no period). Common types: feat, fix, docs, style, chore.
  5. Run mint broken-links before committing navigation or link changes.

Project Overview

Kosli documentation site built with Mintlify. Content is authored in Markdown (.md) and MDX (.mdx) files. Configuration lives in docs.json.

Development Commands

npm i -g mint          # Install Mintlify CLI (one-time)
mint dev               # Start local dev server at http://localhost:3000
mint dev --port 3333   # Start on custom port
mint update            # Update Mintlify CLI
mint broken-links      # Validate all internal links
mint a11y              # Check color contrast and accessibility

Requires Node.js v19+.

Architecture

  • docs.json — Central config: theme, API settings, logos. Uses $ref to compose from files in config/.
  • config/ — Split config files: navigation.json (all page routing), redirects.json, footer.json.
  • Content directories — understand_kosli/, getting_started/, administration/, integrations/, implementation_guide/, tutorials/, troubleshooting/, faq/, changelog/, client_reference/, helm/, policy-reference/, terraform-reference/, template-reference/, labs/
  • snippets/ — Reusable MDX content fragments
  • style.css — Custom CSS overrides applied on top of the Mintlify theme
  • scripts/ — Python scripts that generate "live docs" (mostly under client_reference/) and update navigation. See Live docs below.
  • tests/ — pytest suite for the live-docs scripts.
  • .github/workflows/ — doc-review.yml (Claude-powered PR review), pr-quality.yml (link/title checks), update-cli-docs.yml, update-schemas.yml.
  • schemas/ — Generated JSON Schema assets. See Schemas below.

Live docs

client_reference/ content is partly generated by scripts in scripts/. Run scripts/dev_live_docs.sh to regenerate locally; it restores client_reference/ on exit. Don't hand-edit generated pages — find the source script first.

Tests for the generators live in tests/ and run with pytest.

Schemas

schemas/flow-template/v1.json and schemas/policy/v1.json are the static JSON Schema assets served from https://docs.kosli.com/schemas/.... They are generated from the Kosli API (the source of truth in kosli-dev/server), not hand-edited:

python scripts/update_schemas.py          # regenerate from the API
python scripts/update_schemas.py --check   # exit non-zero if they have drifted

The update-schemas.yml workflow runs the script on a schedule and opens a PR when the committed files drift from the API. Don't hand-edit these files — fix the Pydantic models in kosli-dev/server instead.

Content Conventions

Every page requires YAML front matter:

---
title: Short, specific title
description: One sentence describing the page purpose.
---
  • 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 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?")
  • MAY Add an icon field to front matter using Font Awesome names.

MDX Components

Component Use for
<Steps> / <Step> Sequential procedures
<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
<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".
  • 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.

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.

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: 
    <Update label="Month Year" description="vX.X.X" tags={["Product Name"]}>

## New features / Bug fixes / Changes

- ...

[View on GitHub](https://github.com/kosli-dev/...)

</Update>
    Always prompt the user for the tags value (e.g., "Terraform Provider", "CLI") before generating an entry.

Deployment

Automatic via Mintlify GitHub app on push to main. No manual deployment steps.