​

AI Agent Documentation Standards

​

Core Principles

1. Verify existence first — Search codebase to confirm feature exists before documenting
2. Never assume — Always verify before writing
3. Never hallucinate — If you can’t verify it, don’t document it
4. Be specific — Use exact UI labels, button text, and navigation paths
5. Stay current — Database configurations change; always verify current values
6. Stay non-technical — Help docs are for users, not developers
7. Font Awesome 6 icons only — The icon library is fontawesome. Never use Lucide names.
8. WCAG AA colors — All theme colors must pass 4.5:1 contrast ratio minimum.
9. Use reusable snippets — Import from /snippets/ for repeated content (fees, warnings, support sections). Never duplicate snippet content inline.

​

Audience & Location Rules

• NO code examples
• NO API endpoints
• NO database references
• NO technical architecture
• YES user actions
• YES plain English
• YES benefits and outcomes

• Reference /developers/ docs: “See API Docs for technical details”
• Keep main content focused on what users do, not how it works

​

Universal Pre-Documentation Checklist

​

Step 1: Feature Existence Verification

​

Required Searches

# Search for UI components
grep -r "featureName" resources/client/ --include="*.tsx" --include="*.ts"

# Search for backend logic
grep -r "featureName" app/ --include="*.php"

# Search for routes
grep -r "featureName" routes/ --include="*.php"

# Search for database migrations
grep -r "featureName" database/migrations/ --include="*.php"

​

What to Verify

• UI components implementing the feature exist
• Backend controllers/services powering it exist
• Database tables/columns for data storage exist
• Routes exposing the feature exist

• No UI components implementing it
• No backend controllers handling it
• No database tables storing it
• No routes exposing it

​

Step 2: UI Navigation & Labels Verification

​

Key Files to Check

​

Verification Commands

# Get profile dropdown menu items (auth-dropdown)
php artisan tinker --execute="$menus = json_decode(\DB::table('settings')->where('name', 'menus')->first()->value, true); foreach($menus as $menu) { if (in_array('auth-dropdown', $menu['positions'] ?? [])) { foreach($menu['items'] as $item) { echo $item['label'] . ' → ' . $item['action'] . PHP_EOL; } } }"

# List all menu positions
php artisan tinker --execute="$menus = json_decode(\DB::table('settings')->where('name', 'menus')->first()->value, true); foreach($menus as $m) { echo $m['name'] . ': ' . implode(', ', $m['positions'] ?? []) . PHP_EOL; }"

​

Verified UI Elements Reference

​

Step 3: Database Configuration Verification

​

Contact & Company

# Contact email
php artisan tinker --execute="echo settings('mail.contact_page_address');"

​

Subscription Plans

# Products (plans)
php artisan tinker --execute="echo json_encode(\DB::table('products')->select('id', 'name', 'free')->get()->toArray(), JSON_PRETTY_PRINT);"

# Prices (billing intervals)
php artisan tinker --execute="echo json_encode(\DB::table('prices')->select('id', 'product_id', 'amount', 'currency', 'interval', 'interval_count')->get()->toArray(), JSON_PRETTY_PRINT);"

​

Upload Formats

# Blocked extensions
php artisan tinker --execute="echo \DB::table('settings')->where('name', 'uploads.blocked_extensions')->first()->value;"

# Allowed extensions
php artisan tinker --execute="echo \DB::table('settings')->where('name', 'uploads.allowed_extensions')->first()->value;"

​

Revenue Model

# Check payout configuration
php artisan tinker --execute="echo json_encode(config('beatpass.payouts'), JSON_PRETTY_PRINT);"

​

Writing Standards (All Documentation)

​

Language & Tone

• Non-technical — Write for users, not developers
• Clear — Use simple, direct language
• Actionable — Guide users step-by-step
• Accurate — Every claim must be verifiable

​

Avoiding Technical Jargon

​

UI References

​

Navigation Format

Click your **profile avatar** in the top navigation bar, then select **Billing** from the menu.

Go to Settings → Subscription

​

Common Mistakes to Avoid

​

❌ Don’t Do This

0. Document features that don’t exist
   • Wrong: Creating docs for “demo downloads”, “watermarked previews”
   • Fix: Search codebase FIRST
1. Trust backend config without verifying frontend
   • Wrong: “Legendary achievements don’t exist” (config says rarity 5)
   • Fix: Check frontend code for actual display mapping
2. Assume navigation paths
   • Wrong: “Go to Settings → Subscription”
   • Fix: Verify actual menu structure
3. Invent menu item names
   • Wrong: “Select Settings from the menu”
   • Fix: Check database for actual labels
4. Use generic section names
   • Wrong: “the Localization section”
   • Fix: Use exact labels: “Location and language”
5. Confuse sidenav with panel titles
   • Wrong: “the Delete Account section” (panel is “Danger zone”)
   • Fix: Read both sidenav and panel component files
6. Use inconsistent capitalization
   • Wrong: “This Device”, “Log Out Other Devices”
   • Fix: “This device”, “Logout other sessions”
7. Document features without verification
   • Wrong: “Select monthly or yearly billing”
   • Fix: Query database to confirm intervals
8. Use generic button names
   • Wrong: “Click the Cancel button”
   • Fix: Use exact text: “Click Cancel plan”
9. Use technical terminology
   • Wrong: “You need the music.create permission”
   • Fix: “You need the ability to upload tracks”

​

Universal Quality Checklist

​

Content Verification

• Feature existence verified via codebase search
• UI elements verified in actual components
• Database values verified via queries (if applicable)
• Navigation paths verified
• No hallucinated features
• No assumed navigation
• No invented labels

​

Writing Quality

• All claims verifiable
• No technical jargon users don’t see
• Exact UI labels used and bolded
• User-focused language (“you”, not “we”)
• Active voice (present tense for features, past for fixes)
• Specific numbers instead of vague terms

​

Reusable Snippets

• Snippets checked — applicable snippets from /snippets/ imported and used
• No inline duplication — content that exists as a snippet is not written inline
• Import paths absolute — all snippet imports use /snippets/... (not relative paths)
• Import names PascalCase — e.g., PlatformFee, NeedHelp, ApiInviteOnly
• Imports after frontmatter — import statements go between --- and first content

​

Technical Requirements

• Frontmatter complete with all required fields
• Internal doc links use root-relative paths (/help/path not ../path)
• App page links use full URLs (https://open.beatpass.ca/login not /login)
• All icon names verified against Font Awesome 6 (not Lucide)
• All Card href targets verified (.mdx file exists + in docs.json nav)
• Mintlify components used correctly
• Tooltips added for domain jargon and technical terms (first occurrence per page)
• No duplicate tooltips for the same term on the same page
• No emoji (use Mintlify icons only)
• Proper Markdown/MDX syntax
• If colors changed in docs.json: WCAG AA verified via mint a11y

​

Cross-References

• Related documentation linked
• Parent/child pages connected
• No orphaned content

​

Documentation Folder Structure

Documentation/
├── snippets/                        # Reusable content (auto-hidden by Mintlify)
│   ├── callouts/                    # Info/Note/Warning callout blocks
│   │   ├── platform-fee.mdx
│   │   ├── platform-fee-note.mdx
│   │   ├── subscription-required.mdx
│   │   └── stripe-connect-required.mdx
│   ├── warnings/                    # Warning blocks
│   │   ├── api-invite-only.mdx
│   │   ├── no-public-sandbox.mdx
│   │   └── producer-only.mdx
│   ├── sections/                    # Reusable page sections
│   │   ├── need-help.mdx
│   │   ├── still-need-help.mdx
│   │   ├── support-contact.mdx
│   │   ├── api-getting-help.mdx
│   │   ├── release-feedback.mdx     # Release notes feedback footer
│   │   └── security-trust.mdx       # Security trust closing block
│   ├── developer/                   # Developer-specific blocks
│   │   ├── bearer-auth-example.mdx
│   │   ├── http-status-codes.mdx
│   │   └── rate-limit-headers.mdx
│   └── data/                        # Exported constants and data tables
│       ├── platform-constants.mdx
│       └── plan-comparison-table.mdx
├── help/
│   ├── index.mdx                    # Main help landing
│   ├── account-settings/
│   │   ├── index.mdx                # Overview
│   │   └── [specific-pages].mdx
│   ├── billing/
│   │   ├── index.mdx
│   │   └── [specific-pages].mdx
│   ├── producer-dashboard/
│   │   ├── index.mdx
│   │   └── [specific-pages].mdx
│   └── [other-sections]/
├── developers/                      # API & developer docs
└── release-notes/
    ├── index.mdx                    # Landing page
    ├── changelog.mdx                # Unified changelog (Update components + RSS feed)
    ├── v3.0/                        # Current version
    │   ├── index.mdx                # v3.0 overview
    │   └── {version}.mdx            # Individual release pages (e.g., 3.0.8-25.mdx)
    └── v2.x/                        # Legacy version
        ├── index.mdx
        └── {version}.mdx

​

Quick Verification Commands

# Search for a feature in UI
grep -r "featureName" resources/client/ --include="*.tsx"

# Search for backend controller
grep -r "featureName" app/Http/Controllers/ --include="*.php"

# Check database for settings
php artisan tinker --execute="echo settings('setting.key');"

# Get menu items
php artisan tinker --execute="$menus = json_decode(\DB::table('settings')->where('name', 'menus')->first()->value, true); foreach($menus as $menu) { if (in_array('auth-dropdown', $menu['positions'] ?? [])) { foreach($menu['items'] as $item) { echo $item['label'] . PHP_EOL; } } }"

# Check plans
php artisan tinker --execute="echo json_encode(\DB::table('products')->get(['name', 'free'])->toArray());"

​

Related Resources

• AI Agent Guide — Main entry point
• Update Guide — Updating existing docs
• New Doc Guide — Creating new docs
• Mintlify Reference — Component usage
• Verification Standards — Detailed verification