​

CLAUDE.md

​

Project overview

​

Tech stack

• Node.js >= 18.0.0
• Mintlify ^4.2.577 (docs framework)
• pnpm (lockfile present; npm also supported per README)
• OpenAPI 3.x spec (api-reference/openapi.json) — source of truth for the API reference
• Chariow REST API base URL: https://api.chariow.com/v1 (bearer auth)

​

Getting started

npm install
# or
pnpm install

# Start local dev server (http://localhost:3000)
npm run dev

​

Common commands

​

Architecture

• docs.json — Mintlify site configuration: theme, navigation tree, API settings, localization, integrations (GA4, telemetry).
• en/ — English MDX content pages (introduction, guides, resources, mcp/, n8n/).
• fr/ — French MDX content pages mirroring the English structure.
• api-reference/ — Auto-generated API pages driven by openapi.json; shared between both language tabs.
• images/ — Static assets referenced in docs pages.
• umami.js — Custom analytics script injected into the site.

​

Conventions

• Content is written in MDX; Mintlify-specific components (<Card>, <CodeGroup>, etc.) are available.
• Both en/ and fr/ must stay structurally in sync — new guides should be added to both language trees.
• API reference pages are generated from api-reference/openapi.json; update the spec rather than hand-editing generated pages.
• No test framework is present; npm run lint (Mintlify broken-links check) is the only automated quality gate.
• Use pnpm for dependency management to stay consistent with the checked-in pnpm-lock.yaml.

​

Git Conventions

​

1. Branch names

^(feature|fix|hotfix|chore|docs|refactor|test|ci|perf|build|style)/[a-z0-9._-]+$

• Lowercase only, kebab-case after the prefix, max 50 characters total.
• Use the full word feature/ — never feat/ (the short feat form is only for commit message types).
• Include the ticket id when relevant: feature/AXA-123-add-stripe (the ticket id is lowercased to satisfy the pattern — e.g. feature/axa-123-add-stripe).
• Never use a claude/ prefix or any prefix outside the allowed set.
• main, release, staging are permanent protected branches — never push to them directly.
• If a branch is misnamed, rename it before pushing: git branch -m <old> <new>.

​

2. Commit messages

^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\([^)]+\))?!?: .+

• Lowercase type, optional scope in parens, optional ! for breaking changes, subject after : .
• Subject starts with a lowercase letter and has no trailing period.
• Examples: feat(checkout): add Apple Pay support, fix(api): handle expired tokens, chore(deps): bump axios from 1.7.2 to 1.15.2, refactor!: drop Node 18 support.
• Do not rewrite Dependabot commits — chore(deps): bump X from a to b is already enforced via .github/dependabot.yml.

​

3. Files that are always rejected

• .env, .env.* (only .env.example and .env.sample are allowed), **/.env, **/.env.*
• Private keys: **/id_rsa{,.pub}, **/id_dsa, **/id_ecdsa, **/id_ed25519, **/.ssh/id_*
• Credentials: **/.aws/credentials, **/credentials.json, **/service-account.json, **/firebase-adminsdk-*.json, **/secrets.{yml,yaml}
• Extensions: *.pem, *.key, *.p12, *.pfx, *.jks, *.keystore, *.ppk, *.asc, *.gpg
• Any file larger than 100 MB (use git LFS) If a secret is needed, use .env.example for env vars and an external secret manager for credentials.

​

Pull requests targeting main, release, staging

• 1 approval, all conversations resolved, squash or rebase merge only (linear history enforced — no merge commits).
• Commits must be GPG- or SSH-signed. Signing is required for main (required-signatures-main ruleset).
• The PR title becomes the squash commit message and must match the commit-message regex above (enforced on all three branches).

​

Pre-push checklist

1. Branch name matches the regex.
2. Every commit in origin/main..HEAD matches the commit pattern (git log --format=%s origin/main..HEAD).
3. No staged file is in the blocked paths/extensions list.
4. Commits are signed if the target is main.