Skip to content

CLAUDE.md

Latest commit

 

History

History
190 lines (141 loc) · 9.39 KB

CLAUDE.md

File metadata and controls

190 lines (141 loc) · 9.39 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+.

Automated PR checks

Reported by the Mintlify GitHub app, alongside this repo's own workflows:

Check Enforces Source
Mintlify Validation (kosli) - vale-spellcheck .vale.ini + styles/Kosli/AmericanSpelling.yml Mintlify app
Mintlify Validation (kosli) - link-rot Link targets — unreliable, frequently reports skipping. Don't rely on it; run mint broken-links locally (core rule 5) and check gh pr checks before assuming links were validated. Mintlify app
Mintlify Deployment Preview build Mintlify app
Doc quality review The doc-review skill doc-review.yml
Validate PR Title Conventional Commits pr-quality.yml
Test live-docs scripts pytest tests/ — including navigation integrity, so core rule 2 is enforced: a page file with no config/navigation.json entry fails the build pr-quality.yml

Because spelling is already enforced, review agents should not spend turns hand-checking it.

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), doc-structure.yml (monthly navigation and coverage audit that files issues), pr-quality.yml (PR title + live-docs tests), 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 — update-cli-docs.yml deletes and rewrites them on every CLI release, so an edit here is silently reverted and the defect ships again. Fix the source:

Page Fix it in
client_reference/kosli*.md kosli-dev/cli → cmd/kosli/<command>.go (kosli_attest_sonar.md ← attestSonar.go)
helm/k8s_reporter/*.mdx kosli-dev/cli → charts/k8s-reporter/mintlify/<page>.md.gotmpl, or values.yaml
kosli * nav groups in config/navigation.json scripts/update-cli-nav.py
Live-docs sections scripts/add_livedocs.py, scripts/live_docs_*_data.py

In the CLI's Go long descriptions, ^ means backtick (^--jq^) and kosli docs substitutes it — so a literal ^ on a published page is a generator escaping bug, not a typo in the description.

client_reference/overview.md and client_reference/output_and_verbosity.md are hand-authored; regeneration only removes kosli*.md.

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

Auditing navigation

python scripts/audit_navigation.py           # readable report
python scripts/audit_navigation.py --check    # exit 1 on integrity findings
python scripts/audit_navigation.py --json     # for the doc-structure skill

Integrity — orphaned pages (a file with no navigation entry, core rule 2) and dangling entries (an entry with no file). Enforced on every PR by pytest tests/.

Shape — advisory information-architecture signals: single-child groups, deep nesting, Title Case labels, oversized groups, inconsistent icons. Never fails a build. The Reference ▸ CLI Reference subtree is exempt because update-cli-nav.py generates it from the CLI's command tree.

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:

  • Writing or updating a page — use the doc-write skill (.claude/skills/doc-write/).
  • Reviewing a page or a PR — use the doc-review skill (.claude/skills/doc-review/).
  • Auditing site navigation and changelog coverage — use the doc-structure skill (.claude/skills/doc-structure/). It files issues; it never edits docs.
  • PR creation — use the pr-creator skill if available.
  • Changelog entries — most entries are generated by .mintlify/workflows/update-changelog.md from release tags. When writing one by hand, 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.