​

AI Agent Guide: BeatPass Documentation

​

Quick Start

​

What Type of Documentation?

​

Section 1: Universal Principles (Apply to ALL Documentation)

​

Core Mandates

1. Verify First, Write Second — Never document without confirming feature exists
2. Exact UI Labels — Use bold text for buttons, menus, sections: **Billing**
3. No Technical Jargon — music.create permission → “ability to upload tracks”
4. User-Focused — Write “you can” not “we have added”
5. Root-Relative Links — /help/path not ../path or https://...
6. Font Awesome 6 Icons Only — The icon library is fontawesome. Never use Lucide icon names.
7. WCAG AA Compliance — All colors must meet minimum 4.5:1 contrast ratio against their background.
8. Use Snippets for Repeated Content — Never duplicate content that exists as a reusable snippet. Import from /snippets/ instead.

​

Audience Separation Rule

• ❌ NO code examples
• ❌ NO API endpoint references
• ❌ NO technical implementation details
• ❌ NO database column names
• ❌ NO internal architecture explanations
• ✅ YES plain English explanations
• ✅ YES user actions and outcomes
• ✅ YES benefits and value propositions

• Reference the developers documentation: “See API Reference for technical details”
• Keep the main content focused on user actions
• Don’t explain how it works, explain how to use it

❌ Wrong (for /help/):
"The system uses the `processPayment()` method with the 
`stripe.payment_intent` webhook to handle transactions."

✅ Correct (for /help/):
"When you complete your purchase, your payment is processed 
securely and you'll receive a confirmation email."

✅ With technical reference:
"Your payment is processed securely. See the 
[Payment API Reference](/developers/api/payments) for 
technical integration details."

​

The Golden Rule

NEVER document a feature without verifying it exists in the codebase.

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

# Search backend
grep -r "FeatureName" app/ --include="*.php"

# Verify database
grep -r "feature_table" database/migrations/

​

Critical Verification Checklist

• Feature existence — Found in codebase
• UI elements — Exact labels from components
• Navigation — Actual menu paths verified
• Database values — Queried if applicable (pricing, settings)
• No hallucination — Only documented verified facts

​

Common Verification Commands

# Profile 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'] . ' → ' . $item['action'] . PHP_EOL; } } }"

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

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

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

​

Prohibited Content

​

Section 1.5: Icon Library, Links & Accessibility (CRITICAL)

​

Icon Library: Font Awesome 6 ONLY

​

Common Lucide → Font Awesome 6 Mistakes

​

Validation Rule

NEVER use an icon name without verifying it at fontawesome.com/icons. If the icon doesn’t exist in FA6, it will render as blank — no error, no warning, just an invisible icon.

​

Link Rules

✅ /help/billing/invoices
✅ /developers/quickstart
❌ ../billing/invoices
❌ https://docs.beatpass.ca/help/billing/invoices

✅ https://open.beatpass.ca/login
✅ https://open.beatpass.ca/register
✅ https://open.beatpass.ca/pricing
✅ https://open.beatpass.ca/forgot-password
✅ https://open.beatpass.ca/pages/licensing
❌ /login  (this resolves as a doc path, not an app URL)
❌ /register
❌ /pricing

Rule: If the link target is a page inside the Mintlify docs (exists as an .mdx file), use a root-relative path. If it’s an app page, external site, or non-doc resource, use a full https:// URL.

1. If it starts with /help/ or /developers/ or /release-notes/ → verify the .mdx file exists on disk AND is listed in docs.json navigation
2. If it points to an app page → use https://open.beatpass.ca/...
3. If the target file was moved or renamed → update ALL references across the entire docs

​

WCAG AA Color Compliance

• Primary: #187AB4 (4.63:1 vs white ✅)
• Light: #5BC0F0 (9.94:1 vs dark ✅)
• Dark: #1F8AC8 (5.36:1 vs dark ✅)

Never change the primary color without verifying WCAG AA compliance. Use a contrast checker like webaim.org/resources/contrastchecker.

​

Mintlify CLI Known Issues

​

Section 2: Writing New Documentation

​

When to Create New Docs

• Feature exists but has no documentation
• User confusion reported (support tickets)
• Complex workflow needs explanation
• Gap in current documentation coverage

​

The 6-Step Process

​

Step 1: Research

• What does this feature do?
• Who uses it? (audience)
• How do they access it? (navigation)
• What are prerequisites?
• What are the outcomes?

# Find UI
grep -r "FeatureName" resources/client/ --include="*.tsx"

# Find backend
grep -r "FeatureName" app/ --include="*.php"

# Find routes
grep -r "feature-route" routes/ --include="*.php"

​

Step 2: Verify Everything

• Menu items from database query
• Button text from component files
• Pricing from products/prices tables
• File formats from settings table

​

Step 3: Determine Structure

​

Step 3.5: Check for Applicable Snippets

​

Step 4: Create File

• lowercase-with-hyphens.mdx
• Descriptive but concise
• Group in subfolders if related

Documentation/help/
├── [section]/                    # e.g., billing
│   ├── index.mdx                # Section overview
│   └── specific-topic.mdx       # Individual pages

​

Step 5: Write Content

---
audience: help
title: "Descriptive Page Title"
description: "One-line summary for SEO."
---

import NeedHelp from "/snippets/sections/need-help.mdx";
{/* Add other snippet imports as needed */}

• Introduction: 2-3 sentences
• Prerequisites: Bullet list (if needed)
• Steps: Numbered, exact UI labels in bold
• No technical jargon
• Specific numbers, not vague terms

# Managing Your Subscription

Manage your BeatPass subscription, change plans, update payment methods, and view billing history.

## Accessing Billing

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

## Changing Your Plan

1. In the **Current plan** section, click **Change plan**.
2. Select your new plan from the options.
3. Click **Confirm change** to apply.

Your new plan takes effect at the start of your next billing cycle.

# Subscription Management

We have added a new subscription management interface for users.

Go to Settings → Subscription to manage your plan.

Click the Change Plan button and select a new plan.

​

Step 6: Cross-Link

• Link to related documentation
• Update parent index to include new doc
• Link FROM related docs TO this one

​

New Documentation Checklist

• Feature verified to exist
• Navigation paths verified
• UI labels exact and bolded
• No technical jargon
• Frontmatter complete
• Root-relative links for internal docs, full URLs for app pages
• All icon names verified against Font Awesome 6 (NOT Lucide)
• Snippets checked — used for all applicable patterns (fees, warnings, support sections)
• No inline duplication of content that exists in /snippets/
• Snippet imports use absolute paths (/snippets/...)
• Related docs cross-linked
• Parent index updated

​

Section 3: Updating Documentation

​

When to Update

• UI text changed (button names, menu items)
• Navigation paths changed
• Pricing or plans changed
• Feature behavior changed
• Error found in current docs
• Feature removed or deprecated

​

The Update Process

​

Step 1: Read Current Doc

​

Step 2: Verify Current State

# Check if mentioned menu items still exist
php artisan tinker --execute="..."

# Verify pricing if mentioned
php artisan tinker --execute="..."

# Check UI component for button text
cat resources/client/.../component.tsx | grep -i "button"

​

Step 3: Identify Changes

​

Step 4: Make Minimal Changes

• Change only what’s wrong
• Preserve correct content
• Maintain existing tone
• Keep structure if possible

- Go to **Settings** → **Subscription**.
+ Click your **profile avatar**, then select **Billing**.

- The Classic plan costs $19/month.
+ The Classic plan costs $29/month (CAD).

​

Step 5: Check Related Docs

grep -r "old-navigation-path" Documentation/help/ --include="*.mdx"

​

Update vs. Rewrite Decision

​

Update Checklist

• Current doc fully read
• All claims verified
• Outdated content identified
• Minimal targeted changes made
• Related docs checked for same errors
• Tone and style preserved
• No accidental content deletion
• Snippet opportunities identified — inline content replaced with snippet imports where applicable
• Existing snippet imports verified — still using correct paths and names

​

Section 4: Release Notes

1. Individual release note pages — Detailed pages in release-notes/v3.0/ with full content
2. Unified changelog — release-notes/changelog.mdx using Mintlify Update components with tag filters and RSS feed (/release-notes/changelog/rss.xml)

​

Quick Reference

​

The 9-Step Process

1. Select template based on type
2. Determine metadata (audience, tags, components, severity)
3. Verify feature existence (search codebase)
4. Write individual page (summary, what’s new, why it matters, how to use)
5. Apply style (present tense for features, past for fixes, bold UI refs)
6. Validate (checklist + Mintlify components)
7. Place individual file in release-notes/v3.0/{version}.mdx
8. Add changelog entry — Update component at top of release-notes/changelog.mdx
9. Update docs.json — Add page to correct month group in “What’s New” tab

​

Individual Page Specifics

---
title: "Feature Name"
date: "YYYY-MM-DD"
severity: "minor"  # major, minor, patch, hotfix
audience: "All"    # All, Producers, Developers
tags: ["feature"]  # From taxonomy
components: ["dashboard"]  # From taxonomy
---

• Summary — 2-3 sentences, lead with benefit
• What’s New — 3-7 bullets, active voice
• Why It Matters — 2-4 bullets, user value
• How to Use — Steps if applicable
• Migration Guide — If breaking changes

• Past tense for fixes (“Fixed…”, “Resolved…”)
• Present tense for features (“Adds…”, “Improves…”)
• Time-bounded (dated)
• Severity classification
• Audience-specific

​

Changelog Entry Specifics

<Update label="{Month Day, Year}" description="v{version}" tags={["{Tag1}", "{Tag2}"]}>
  ## {Title}

  {1-2 sentence summary.}

  - **{Key change 1}** — Brief description
  - **{Key change 2}** — Brief description
  - **{Key change 3}** — Brief description

  [Read full release notes →](/release-notes/v3.0/{version})
</Update>

<Update label="..." description="..." tags={[...]} rss={{title: "...", description: "..."}}>

​

Release Note Checklist

• Feature existence verified
• Template selected correctly
• Frontmatter complete
• Tags from taxonomy
• Severity appropriate
• Version bump calculated (see Section 4.5)
• Summary leads with benefit
• 3-7 bullets in What’s New
• Past tense for fixes, present for features
• UI references exact and bold
• Individual page named correctly: release-notes/v3.0/{version}.mdx
• Changelog Update entry added at top of changelog.mdx
• Update label format: "Month Day, Year"
• Update tags: 1-3 Title Case from approved set
• docs.json navigation updated (correct month group)
• .env APP_VERSION updated (see Section 4.5)
• package.json version updated
• public/version.json version updated

​

Section 4.5: Version Management (Release Notes Only)

​

Single Source of Truth

.env APP_VERSION (single source of truth)
    ↓
common/resources/config/site.php → env('APP_VERSION')
    ↓
BaseBootstrapData.php:76 → $this->data['settings']['version']
    ↓
Admin Panel displays "Version: X.Y.Z"

​

Semantic Versioning Rules

​

Version Bump Process

1. Read current version from .env file (line with APP_VERSION=)
2. Determine severity from release note type (see Quick Reference table above)
3. Calculate new version:
   • patch or hotfix: X.Y.Z → X.Y.(Z+1)
   • minor: X.Y.Z → X.(Y+1).0
   • major: X.Y.Z → (X+1).0.0
4. Update ALL three files:

5. Clear config cache: php artisan config:clear

​

Frontmatter Integration

---
title: "Feature Name"
date: "YYYY-MM-DD"
severity: "minor"        # This determines version bump type
version: "3.1.0"         # New version after this release
audience: "All"
tags: ["feature"]
components: ["dashboard"]
---

​

Version Bump Checklist

• Current version verified from .env (APP_VERSION=X.Y.Z)
• Severity determined from release note type
• New version calculated correctly per SemVer rules
• .env updated with new APP_VERSION
• package.json updated with matching version
• public/version.json updated with matching version
• Version bump matches severity in frontmatter
• For major releases: Breaking changes documented
• For major releases: Migration guide included
• Config cache cleared after .env changes

​

Common Version Scenarios

Current: 3.0.8
Release: Fixed typo in billing email
Severity: patch
New Version: 3.0.9

Current: 3.0.8
Release: New analytics dashboard
Severity: minor
New Version: 3.1.0

Current: 3.1.5
Release: New API authentication (old keys deprecated)
Severity: major
New Version: 4.0.0

​

Section 5: Quality Checklist (All Documentation)

​

Pre-Publication Verification

• All claims verifiable in codebase
• Feature existence confirmed
• UI labels exact (verified against components)
• Navigation paths tested mentally
• No technical jargon users don’t see
• No hallucinated features
• Tooltips added for domain jargon and technical terms (first occurrence per page)
• Tooltip tip text is 1-2 sentences, BeatPass-contextual, no code
• No duplicate tooltips for the same term on the same page
• Snippets used for all applicable repeated content (platform fee, need help, warnings)
• No hardcoded values that exist in snippets (contact email, fee amounts, plan prices)

• Active voice (present for features, past for fixes)
• User-focused (“you” not “we”)
• Specific numbers (“95% faster” not “much faster”)
• UI elements in bold: **Button Name**
• Contractions used for approachable tone
• Paragraphs under 4 lines

• Frontmatter complete (audience, title, description)
• Root-relative links for doc pages: /help/path
• Full URLs for app pages: https://open.beatpass.ca/...
• All icons verified against Font Awesome 6 (not Lucide)
• Mintlify components used correctly
• No emoji (use icons)
• Valid Markdown/MDX syntax
• Card href targets verified (file exists + in docs.json nav)

• Related docs linked
• Parent index updated (for new docs)
• No orphaned pages

​

Common Mistakes to Avoid

​

Section 6: Quick Reference

​

File Paths and Commands

Documentation/help/[section]/[page].mdx

# Search UI
grep -r "term" resources/client/ --include="*.tsx"

# Search backend
grep -r "term" app/ --include="*.php"

# Query database
php artisan tinker --execute="..."

# Find 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; } } }"

• Documentation Standards — Universal standards
• New Doc Guide — Creating new docs
• Update Guide — Updating existing docs
• Mintlify Reference — Components
• Verification Standards — Detailed verification

​

Emergency Decision Tree

​

Summary: The AI Agent Documentation Workflow

1. IDENTIFY task type (new / update / release note)
2. VERIFY feature existence (search codebase)
3. VERIFY UI elements (check components, query DB)
4. CHECK snippets — identify applicable reusable content from /snippets/
5. WRITE using exact labels, no jargon, importing snippets
6. CROSS-LINK to related docs
7. SELF-REVIEW against checklist (including snippet usage)
8. SUBMIT