Skip to main content
KEEP THIS ULTRA SIMPLE: This document is context for other AI agents. Do NOT add extra content, explanations, or “waffle”. Only include the absolute minimum commands needed.
DOUBLE HEADING BUG: MDX files automatically generate H1 from the title. Do NOT add a second H1 heading or you’ll get duplicate headings in the rendered page.

​
Writing Principles

​
One Concept Per Page

Each user manual page should focus on one single concept only. Never combine multiple concepts in a single page.

​
Simple Titles and Descriptions

  • Title: Simple action-focused titles - DO NOT include “How to”
  • Description: Use simple, clear language - avoid “comprehensive” or overly complex descriptions
  • No Double Headings: Don’t add H1 (#) after the frontmatter title

​
Content Structure

  • Use clear subheadings to organize content
  • Break down complex processes into simple steps
  • Keep explanations minimal and focused

​
Examples

Good: “Add Team Members” Bad: “How to Add Team Members” or “Team Management and User Roles” Good: “Log In” Bad: “How to Log In” or “Logging Into Your Account” Good Description: “Step-by-step guide to invite team members” Bad Description: “Comprehensive user manual for inviting and managing team members”

​
Page Structure Rules

​
NEVER Include These Sections:

  • Overview - The title and description already explain what the page does
  • Introduction - The description is the introduction
  • Before You Start - If they’re on the page, they want to do the task
  • Prerequisites - Only include critical warnings inline where needed
  • Introduction paragraphs - Keep opening content minimal
  • Getting Started - Jump straight to the steps
  • Opening sentences that repeat the title/description - No waffle at the top

​
ALWAYS Follow This Structure:

For Simple Single-Concept Pages: 
---
title: [Action]
description: 'Step-by-step guide to [simple action]'
---

<Steps>
  <Step title="[Action]">
    [Brief description of what to do]
    
    <img src="/images/[workflow-name]/[##-filename].png" alt="[Description]" />
  </Step>
</Steps>
WRONG - Never do this: 
---
title: 'Edit Medication'
description: 'How to update medication details'
---

## Overview
This guide shows how to edit medications...

## Steps
For Complex Multi-Section Pages: 
---
title: [Action]
description: 'Step-by-step guide to [simple action]'
---

## [Descriptive Action Name]

<Steps>
  <Step title="[Action]">
    [Brief description of what to do]
    
    <img src="/images/[workflow-name]/[##-filename].png" alt="[Description]" />
  </Step>
</Steps>

## [Next Descriptive Action Name]

<Steps>
  <Step title="[Action]">
    [Brief description]
    
    <Warning>
      **Only include warnings when absolutely critical**
    </Warning>
  </Step>
</Steps>

​
When to Use Section Headings:

  • Use section headings only when you have multiple distinct groups of steps
  • Skip section headings for simple, single-concept workflows
  • Don’t add headings just because you think you need them

​
Section Heading Rules:

  • NO “Step-by-Step Process” - the description already says it’s step-by-step
  • NO “Getting Started” or similar generic headings
  • Use descriptive action names like “Access User Management”, “Send Invitation”, “Configure Settings”
  • Be specific about what the section accomplishes
  • Never repeat words from the title or description

​
Examples of Good Section Headings:

  • “Access User Management”
  • “Send Invitation”
  • “Configure Role Permissions”
  • “Navigate to Settings”
  • “Complete Profile Setup”

​
Examples of Bad Section Headings:

  • “Step-by-Step Process”
  • “How to Get Started”
  • “Follow These Steps”
  • “Process Overview”

​
NO WAFFLE RULE:

  • Start immediately with the first section heading or Steps
  • Never repeat what’s already in the title or description
  • No “Overview” sections - The description IS the overview
  • No opening sentences like “This guide will show you…” or “Follow these steps…”
  • No permission statements like “You’ll need Admin permissions” - put these in warnings inside steps if critical
  • Jump straight to the content - the title and description already explain what the page does

​
Inline Warnings Only

  • Put warnings INSIDE the relevant step
  • Only warn about critical issues that would cause problems
  • Don’t warn about obvious things (like “make sure you want to do this”)

​
Essential Process

​
1. Setup Environment

# Start application
npm run dev

# Start documentation server  
cd docs-external && mintlify dev

​
2. Configure Browser

mcp_playwright_browser_resize
Width: 1440
Height: 900

​
3. Navigate & Screenshot

mcp_playwright_browser_navigate
URL: http://localhost:5176

mcp_playwright_browser_take_screenshot
Filename: "01-descriptive-name.png"

​
4. User Actions

mcp_playwright_browser_type
Element: "Email Address textbox"
Ref: "e47" 
Text: "cameron+2053@houston.nz"

mcp_playwright_browser_click
Element: "Sign In button"
Ref: "e69"

mcp_playwright_browser_wait_for
Time: 3

​
5. Two-Factor Authentication Handling

SECURITY REQUIREMENT: Never attempt to bypass 2FA or use test codes. Always complete the proper authentication flow.
When 2FA verification screen appears:
  1. STOP and ask the user for the current 2FA code
  2. WAIT for the user to provide the 6-digit verification code
  3. NEVER attempt to bypass or skip 2FA verification
  4. ALWAYS use the code provided by the user
Proper 2FA workflow: 
# After login, when redirected to /mfa-verify
mcp_playwright_browser_type
Element: "Verification Code textbox"
Ref: "[snapshot-ref]"
Text: "[USER-PROVIDED-CODE]"

mcp_playwright_browser_click
Element: "Verify Code button"
Ref: "[snapshot-ref]"

mcp_playwright_browser_wait_for
Time: 3

​
6. Copy Screenshots

cp "/var/folders/.../playwright-mcp-output/timestamp/screenshot.png" docs-external/images/workflow-name/

​
7. Verify Files

ls -la docs-external/images/workflow-name/

​
Image References in MDX

<img src="/images/workflow-name/01-login-screen.png" alt="Description" />

​
Test Credentials

​
File Structure

docs-external/
├── how-to/[workflow-name].mdx
├── images/[workflow-name]/
│   ├── 01-login-screen.png
│   └── 02-next-step.png
└── mint.json

​
Key Commands Only

  • mcp_playwright_browser_navigate - Go to URL
  • mcp_playwright_browser_resize - Set browser size
  • mcp_playwright_browser_take_screenshot - Capture screen
  • mcp_playwright_browser_type - Fill form fields
  • mcp_playwright_browser_click - Click elements
  • mcp_playwright_browser_wait_for - Wait for loading
  • cp - Copy screenshots to docs folder

​
Final Review Checklist

CRITICAL: Before completing any documentation task, review ALL created files and verify:

​
Content Structure Review

  • No “Overview” sections - Does the content jump straight to steps or section headings?
  • No waffle - Are there any opening sentences that repeat the title/description?
  • No double headings - Is there any repetition between title/description and content?
  • No permission statements - Are admin requirements mentioned as waffle instead of inline warnings?

​
Page Structure Review

  • Title follows rules - Simple action, no “How to” prefix
  • Description is simple - No “comprehensive” or overly complex language
  • Section headings are specific - No generic headings like “Getting Started”
  • Steps are clear - Each step has a clear action and screenshot

​
Common Violations to Fix

  • “Overview” sections → DELETE immediately
  • “This guide shows…” → DELETE immediately
  • “You’ll need Admin permissions” → Move to inline warning if critical
  • “Before You Start” → DELETE or move to inline warnings
  • Generic section headings → Make specific and action-focused
If any violations are found, fix them immediately before delivery.