Skip to content

AGENTS.md

Latest commit

 

History

History
147 lines (102 loc) · 5.55 KB

AGENTS.md

File metadata and controls

147 lines (102 loc) · 5.55 KB

AGENTS

This file provides guidance to AI Agents when working with code in this repository.

This is the user-facing documentation repository for Flipt, a feature flag and experimentation platform. The documentation files are located in the docs/ directory and built using Mintlify and hosted at flipt.io/docs.

Working Principles

  • Collaboration: You can push back on ideas—this can lead to better documentation. Cite sources and explain your reasoning when you do so
  • Clarity: ALWAYS ask for clarification rather than making assumptions
  • Accuracy: NEVER lie, guess, or make up anything

Project Structure

Documentation Versions

The documentation is organized into two main versions:

  • docs/v1: Legacy documentation for Flipt v1.x (open-source version)
  • docs/v2: Current documentation for Flipt v2.x (including Pro features)

Both versions are maintained to support users on different versions of Flipt.

Configuration

  • Format: MDX files with YAML frontmatter
  • Config: docs/docs.json for navigation, theme, settings (docs.json schema)
  • Components: Mintlify components

Required Frontmatter

  • title: Clear, descriptive page title
  • description: Concise summary for SEO/navigation

Writing Guidelines

Content Strategy

  • Document just enough for user success - not too much, not too little
  • Prioritize accuracy and usability
  • Make content evergreen when possible
  • Search for existing content before adding anything new
  • Check existing patterns for consistency
  • Start by making the smallest reasonable changes

Writing Standards

  • Use the Microsoft Writing Style Guide
  • Second-person voice ("you")
  • Target audience: developers and operators
  • Avoid technical jargon; explain concepts clearly
  • Focus on how to use and configure the product (not deep technical internals)

Technical Requirements

  • Prerequisites at start of procedural content
  • Test all code examples before publishing
  • Match style and formatting of existing pages
  • Include both basic and advanced use cases
  • Language tags on all code blocks
  • Alt text on all images
  • Relative paths for internal links

Link Formatting

  • Always use markdown link syntax: [Link Text](https://example.com) instead of raw URLs
  • Use descriptive link text: [Installation guide](https://helm.sh/docs/intro/install/)
  • Keep link text concise: Use terms like "Download", "Installation guide", "Documentation"
  • Examples:
    • ✅ Good: Docker installed ([Download](https://www.docker.com/products/docker-desktop))
    • ❌ Bad: Docker installed (Download: https://www.docker.com/products/docker-desktop)

Git Workflow

  • Create a new branch when no clear branch exists for changes
  • Commit frequently throughout development
  • Follow Conventional Commits format (feat:, fix:, docs:, chore:)
  • NEVER use --no-verify when committing
  • NEVER skip or disable pre-commit hooks
  • Ask how to handle uncommitted changes before starting

Development Commands

Local Development

  • mint dev - Start local development server (run from docs/ directory)
  • mint rename - Rename file and update internal link references

Code Quality

  • npm run lint - Run ESLint to check code quality (run from docs/ directory)
  • npm run format - Format code using Prettier (run from docs/ directory)

Documentation Linting

  • vale sync - Install Vale dependencies for documentation linting (run from docs/ directory)
  • vale * - Lint all documentation files (run from docs/ directory)
  • vale README.md - Lint specific file (run from docs/ directory)

Publishing

Changes are automatically deployed to production when pushed to the main branch.

Quality Assurance

Visual Verification

After making any documentation changes, you MUST use the Playwright MCP browser tools to verify the changes render correctly in the local dev server (mint dev, typically running on port 3000):

  1. Get browser context with tabs_context_mcp (create tab group if needed)
  2. Create a new tab with tabs_create_mcp
  3. Navigate to each changed page at http://localhost:3000/...
  4. Scroll to each modified section (use find + scroll_to to locate headings)
  5. Take screenshots to verify:
    • Content renders correctly (no broken markdown, missing sections, or layout issues)
    • Code blocks display with proper syntax highlighting
    • Tables are well-formatted with correct columns and alignment
    • Callout components (<Note>, <Warning>, <Tip>) render properly
    • "On this page" navigation includes new sections
    • Links are functional

Automated Checks

  • ESLint with MDX support for linting
  • Prettier for formatting
  • Vale for prose linting with Microsoft Writing Style Guide rules
  • GitHub Actions run Vale on PRs with inline comments

Vale Configuration

  • Custom Flipt style rules: docs/.vale/styles/flipt/
  • Spelling exceptions: docs/.vale/styles/Flipt/spelling-exceptions.txt (lowercase, alphabetical)
  • Configuration: docs/.vale.ini

Development Setup

  1. Install Mintlify CLI globally: npm i mint -g
  2. Install Vale for linting: Follow Vale installation guide
  3. Run vale sync to install Vale packages (from docs/ directory)
  4. Start development server: mint dev (from docs/ directory)

Do Not

  • Skip frontmatter on any MDX file
  • Use absolute URLs for internal links
  • Include untested code examples
  • Make assumptions - always ask for clarification