​

Cleft Documentation - Mintlify Project

​

Working Relationship

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

​

Project Context

• Format: MDX files with YAML frontmatter
• Config: docs.json for navigation, theme, settings
• Components: Mintlify components
• Current version: v1.10.0 (updated 2025-09-10)
• All MDX files should include version and lastUpdated frontmatter

​

Content Strategy

• Document just enough for user success - not too much, not too little
• Prioritize accuracy and usability of information
• Make content evergreen when possible
• Search for existing information before adding new content. Avoid duplication unless it is done for a strategic reason
• cross-referencing documents is preferred
• let users go deeper, if they want to not because we made them
• Check existing patterns for consistency
• Start by making the smallest reasonable changes

​

Development Commands

• mintlify dev - Start local development server (runs on port 3000)
• ./compress-images.sh - Compress images over 5MB in the /images directory
• ./rename-images.sh - Rename images utility script

​

Architecture

​

Content Structure

• User Guides (/user-guides/) - Feature guides and role-based workflows
• Trust (/trust/) - Legal documents (privacy policy, terms, DPA, vendor info)
• Resources (/resources/) - Changelog, community, podcast content
• Images (/images/) - Organized in subdirectories (features/, logos/, screenshots/, etc.)

​

Navigation & Configuration

• Site configuration: docs.json (theme: maple, primary color: #e54b2b)
• Navigation structure defined in docs.json with anchors and groups
• Versioning: Implemented using Mintlify’s versions feature in navigation
• Current version: v1.10.0 (macOS released Aug 24, 2025; iOS awaiting App Store approval)
• Future version: v2.0 planned for November 2025

​

docs.json Schema

• Refer to the docs.json schema when building the docs.json file and site navigation
• Versioning is configured in the navigation.versions array
• Each version can have its own navigation structure

​

Frontmatter Requirements for Pages

• title: Clear, descriptive page title
• description: Concise summary for SEO/navigation
• version: “v1.10.0” (current version)
• lastUpdated: “2025-09-08” (current update date)

​

Writing Standards

• Second-person voice (“you”)
• 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
• Use callouts strategically (see Callout Standards below)

​

Git Workflow

• NEVER use —no-verify when committing
• Ask how to handle uncommitted changes before starting
• Create a new branch when no clear branch exists for changes
• Commit frequently throughout development
• NEVER skip or disable pre-commit hooks

​

EU Accessibility Act Compliance (WCAG 2.1 AA)

​

Required Accessibility Features

​

Navigation & Structure

• Add role and aria-label attributes to all interactive elements
• Include skip navigation links on pages with multiple sections
• Use proper heading hierarchy (h1 > h2 > h3) with ID anchors
• Ensure keyboard navigation support (tab order, focus indicators)

​

Component Standards

• Cards: Add aria-label with descriptive text
  Copy

  <Card title="Title" icon="icon" href="/link" aria-label="Navigate to specific action or page">
  

• Accordions: Add role="button" and aria-expanded
  Copy

  <Accordion title="Title" role="button" aria-expanded="false" aria-controls="content-id">
  

• Links: Use descriptive text, avoid “click here” or generic text
• Images: Always include alt text describing content/function
• Forms: Label all inputs, provide clear error messages

​

Color & Contrast

• Ensure 4.5:1 contrast ratio for normal text
• 3:1 for large text and UI components
• Don’t rely on color alone to convey information
• Use Cleft brand colors (#e54b2b) with sufficient contrast

​

Screen Reader Support

• Test with NVDA, JAWS, and VoiceOver
• Provide text alternatives for visual content
• Use semantic HTML elements over generic divs

​

Accessibility Testing Checklist

• Keyboard-only navigation works throughout the site
• Screen reader announces content correctly
• Focus indicators visible and logical
• Color contrast meets WCAG AA standards
• All forms are accessible with proper labels
• Error messages are clear and actionable
• Skip navigation links function properly

​

Skip Navigation Template

<nav role="navigation" aria-label="Page navigation" className="skip-links">
  <a href="#main-content" className="skip-link">Skip to main content</a>
  <a href="#getting-help" className="skip-link">Skip to Getting Help</a>
</nav>

​

Do Not

• Skip frontmatter on any MDX file
• Use absolute URLs for internal links
• Include untested code examples
• Make assumptions - always ask for clarification
• Create Cards or Accordions without proper ARIA labels
• Rely on color alone to convey information
• Use generic link text like “click here” or “read more”

​

Content Conventions

​

Mintlify Components

• <Update> - Changelog entries with labels, descriptions, and tags
• <Note>, <Tip>, <Card> - Content highlighting
• <Tabs> - Multiple content versions (e.g., simplified/legal documents)
• <AccordionGroup> - Collapsible sections

​

Callout Standards

• <Note> - Documentation status, general context, version notes, neutral information
  • Example: “Documentation last updated on [date]”
  • Use for: Status updates, context setting, version information
• <Info> - Important explanations, background information, clarifications
  • Example: “Cleft processes all transcription locally on your device”
  • Use for: Technical explanations, important context, feature details
• <Tip> - Best practices, helpful suggestions, power user features, optimization advice
  • Example: “Use keyboard shortcuts to speed up your workflow”
  • Use for: Productivity tips, shortcuts, pro tips, workflow optimization
• <Warning> - Potential issues, things to avoid, compatibility concerns, non-critical problems
  • Example: “This feature requires iOS 16 or later”
  • Use for: Compatibility warnings, potential pitfalls, things to watch out for
• <Check> - Success confirmations, guarantees, completed actions, positive outcomes
  • Example: “All support emails get a response within 24 hours”
  • Use for: Service guarantees, confirmation of actions, success states
• <Danger> - Critical warnings, data loss risks, irreversible actions, security concerns
  • Example: “Deleting your account permanently removes all data”
  • Use for: Irreversible actions, data loss warnings, security risks
• <Callout> - Custom callouts with specific icons/colors for unique situations
  • Use sparingly for special cases that don’t fit other categories
  • Always include icon and color parameters for consistency

​

Link Formats

• Internal links: Use absolute paths starting with /
• External links: Full URLs to Cleft app, social media, or App Store

​

Date Formatting

• Use “Month Day, Year” format (e.g., “September 6, 2025”)
• Changelog tags: ["release"], ["policy"], ["press"], ["coming-soon"]

​

Trust Section Pattern

​

Key Context

• Cleft 2.0 major update coming November 2025
• Documentation frequently updated for new app releases
• Role-based guides target 15+ different user types (executives, consultants, students, etc.)
• Strong focus on privacy and user data protection
• Recent updates: Enhanced privacy comparison with LLM details, mermaid diagram accessibility improvements
• iOS v1.10 status: NOW LIVE on App Store (released September 10, 2025)

​

Internationalization Status

• Current: Mintlify does not have built-in i18n support
• Workarounds: Separate subdomains or manual file organization for multiple languages
• Future: Monitor Mintlify updates for potential i18n features

​

Versioning Strategy

• Using Mintlify’s versions feature in docs.json navigation
• Current: v1.10.0 documentation with all features
• Future: v2.0 documentation structure planned for November 2025 release
• Each version maintains independent navigation and content structure

​

Cleft Philosophy: Doing One Thing Exceptionally Well

​

What We’re Opinionated About:

• Voice is first-class - Not an afterthought, but how many people naturally process complex ideas
• Privacy matters - Your thoughts shouldn’t train someone else’s AI (local Whisper processing)
• Custom instructions are essential - Generic formatting doesn’t work for personal productivity
• Integration > competition - We work WITH Google Meet, Teams, Notion, Obsidian, not against them

​

What We’re Unopinionated About:

• Organization methods (folders, tags, whatever works for you)
• Export destinations (send your notes anywhere)
• Processing levels (dial AI formatting up or down)
• Workflow integration (fit Cleft into YOUR process, not ours)

​

Key Positioning:

• NOT a transcription service - We transform thoughts, not just convert speech to text
• NOT an AI assistant - We process YOUR thoughts, don’t generate new ones
• NOT a meeting recorder - We’re for personal notes IN meetings, not FOR meetings
• Artisan software - We charge for an amazing experience, not consumption metrics
• Complementary tool - Works alongside typing and handwriting, doesn’t replace them