Documentation

1. Getting Started

1.1 Creating Your Account

To start using Conservatory, you'll need to create a free account:

1. Visit www.conservatory.app
2. Analyze your website by entering its URL
3. Sign Up free to create an account
4. Choose your signup method:
   • Email/Password: Enter your name, email, and create a secure password
   • Google OAuth: Sign up instantly with your Google account
   • GitHub OAuth: Connect with GitHub for seamless integration
5. Agree to the Terms of Service and Privacy Policy
6. Click "Create Account"

Free Plan includes:

• 3 complete analyses per month
• Basic reports (Lighthouse + axe-core audits)
• JSON/Markdown exports
• Unison Metrics™ scoring
• Community support

1.2 Dashboard Overview

After signing up, you'll land on your Dashboard, which contains:

• Analysis Input: Enter a URL to analyze a new website
• Recent Analyses: View your analysis history with Unison Metrics™ scores
• Usage Quota: Track your monthly analysis limit (e.g., "2 of 3 analyses remaining")
• Quick Actions: Export reports, create GitHub PRs, or upgrade your plan
• Account Settings: Manage preferences, integrations, and billing

2. Running Your First Analysis

2.1 Entering a URL

Conservatory analyzes any publicly accessible website:

1. On your Dashboard, locate the "Analyze Website" input field
2. Enter the full URL of the website you want to analyze

   Example: https://www.yourwebsite.com

3. Click "Start Analysis"

Supported URL formats:

• ✅ https://example.com
• ✅ https://www.example.com
• ✅ https://example.com/page (specific pages)
• ✅ https://subdomain.example.com
• ❌ localhost or private IPs (not accessible publicly)
• ❌ file:// URLs

2.2 Analysis Process

Once you submit a URL, Conservatory's AI-powered pipeline processes your website through multiple stages:

Stage 1: Headless Browser Capture (10-15s)
├── Loading page in Chromium headless browser
├── Executing JavaScript and capturing DOM-final state
├── Taking multi-viewport screenshots (desktop, tablet, mobile)
└── Recording network performance metrics

Stage 2: Parallel Analysis Engines (20-30s)
├── Semantic HTML Analysis (DeepSeek-R1)
│   ├── Parsing HTML5 structure
│   ├── Validating ARIA attributes
│   └── Checking heading hierarchy
│
├── Visual Intelligence (Qwen2.5-VL-72B)
│   ├── Layout analysis
│   ├── Color contrast detection
│   ├── Typography evaluation
│   └── UI element recognition
│
├── Accessibility Testing (axe-core + Custom Rules)
│   ├── WCAG 2.1/2.2 validation
│   ├── Keyboard navigation testing
│   └── Screen reader simulation
│
└── SEO/AEO Analysis (Lighthouse + Proprietary)
    ├── Core Web Vitals measurement
    ├── Meta tag validation
    ├── Structured data checking
    └── AI search readiness scoring

Stage 3: Correlation & Scoring (10-15s)
├── Cross-dimensional issue detection
├── Impact priority calculation
├── Fix recommendation generation
└── Unison Metrics™ score calculation

Stage 4: Report Generation (5-10s)
├── Creating visual report dashboard
├── Generating JSON/Markdown exports
└── (Optional) Creating GitHub Auto-PR

Total analysis time: 45-70 seconds (average: 60 seconds)

2.3 Monitoring Analysis Progress

During analysis, you'll see real-time progress updates:

• Progress Bar: Visual indicator showing completion percentage
• Status Messages:
  • "Loading page..." (Stage 1)
  • "Running 200+ automated checks..." (Stage 2)
  • "Analyzing semantic structure..." (Stage 2)
  • "Evaluating visual design..." (Stage 2)
  • "Calculating Unison Metrics™..." (Stage 3)
  • "Generating report..." (Stage 4)
• Estimated Time Remaining: Countdown timer showing seconds remaining

You can leave the page during analysis—your results will be saved and accessible from your Dashboard.

3. Understanding Unison Metrics™

3.1 What is Unison Metrics™?

Unison Metrics™ is Conservatory's proprietary holistic scoring algorithm that provides a single, actionable score (0-100) representing your website's overall health.

Unlike simple averages, Unison Metrics™ uses weighted correlation analysis to understand how issues in one area impact others.

3.2 The Five Scoring Dimensions

Your Unison Metrics™ score is calculated across five dimensions:

3.3 Interpreting Your Score

Unison Metrics™ scores are graded on the following scale:

3.4 Correlation Intelligence Examples

Unison Metrics™ identifies cross-dimensional issues that traditional tools miss:

Example 1: Color Contrast Issue

• Primary Impact: Visual UX/UI (-8 points)
• Secondary Impact: Accessibility WCAG AA failure (-12 points)
• Tertiary Impact: SEO ranking penalty (-5 points)
• Total Impact: -25 points to overall score
• Fixing this single issue improves 3 dimensions simultaneously

Example 2: Missing Heading Hierarchy

• Primary Impact: Semantic Structure (-10 points)
• Secondary Impact: Accessibility screen reader navigation (-8 points)
• Tertiary Impact: AEO AI search understanding (-6 points)
• Total Impact: -24 points to overall score

Example 3: Poor Layout Hierarchy

• Primary Impact: Visual UX/UI (-7 points)
• Secondary Impact: SEO bounce rate increase (-5 points)
• Tertiary Impact: Core Web Vitals CLS penalty (-4 points)
• Total Impact: -16 points to overall score

4. Reading Analysis Reports

4.1 Report Structure

After analysis completes, your report is divided into the following sections:

1. Executive Summary
   • Overall Unison Metrics™ score with grade
   • Trend indicator (improved/declined vs. previous analysis)
   • Critical issues requiring immediate attention
   • Quick win recommendations
2. Dimension Breakdown
   • Individual scores for each of the 5 dimensions
   • Visual radar chart showing dimension balance
   • Comparison to industry benchmarks
3. Issues List (Prioritized)
   • Critical: Legal/compliance risks, major UX failures
   • High Priority: Significant impact on SEO, accessibility, or user experience
   • Medium Priority: Moderate improvements with measurable benefits
   • Low Priority: Minor optimizations and best practice recommendations
4. Detailed Findings
   • Each issue includes:
     • Description: What the issue is
     • Impact: How it affects your score and user experience
     • Location: Where the issue was found (line numbers, selectors)
     • Recommendation: How to fix it
     • Code Example: Before/after code snippets
     • WCAG Reference: Relevant accessibility guidelines (if applicable)
5. Visual Evidence
   • Screenshots highlighting specific issues
   • Annotated images showing problem areas
   • Multi-viewport screenshots (desktop, tablet, mobile)
6. Performance Metrics
   • Core Web Vitals: LCP, FID, CLS scores
   • Lighthouse Scores: Performance, Accessibility, Best Practices, SEO
   • Load Times: First Contentful Paint, Time to Interactive, Total Blocking Time

4.2 Understanding Issue Severity Levels

4.3 Exporting Reports

Conservatory supports multiple export formats:

• JSON: Machine-readable format for API integrations

  {
    "analysis_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "url": "https://example.com",
    "timestamp": "2025-10-23T14:30:00Z",
    "unison_metrics_score": 82,
    "dimensions": {
      "semantic": 85,
      "accessibility": 78,
      "seo": 84,
      "aeo": 80,
      "visual_ux": 83
    },
    "issues": [
      {
        "id": "issue_001",
        "severity": "high",
        "category": "accessibility",
        "description": "Missing alt text on 12 images",
        "impact": "Screen readers cannot describe images to visually impaired users",
        "wcag": "WCAG 2.1 Level A - 1.1.1 Non-text Content",
        "location": "index.html:45, index.html:67, ...",
        "recommendation": "Add descriptive alt text to all images"
      }
    ]
  }

• Markdown: Human-readable format for documentation

  # Website Analysis Report
  
  **URL:** https://example.com  
  **Date:** October 23, 2025  
  **Unison Metrics™ Score:** 82 (Good)
  
  ## Summary
  
  Your website scored 82/100, placing it in the "Good" category...
  
  ## Critical Issues (2)
  
  ### 1. Missing Alt Text on Images
  **Severity:** High  
  **Category:** Accessibility  
  **WCAG:** 2.1 Level A - 1.1.1 Non-text Content
  
  **Description:** 12 images are missing alt text attributes...
  

• PDF: Professional report for stakeholders (Premium/Enterprise plans)
• CSV: Spreadsheet format for issue tracking

5. Using Auto-Fix Features

5.1 What is Auto-Fix?

Auto-Fix is Conservatory's intelligent code remediation system that automatically generates fixes for detected issues and creates ready-to-merge Pull Requests in your GitHub repository.

Available on: Starter, Premium, Enterprise plans

5.2 What Can Be Auto-Fixed?

Conservatory can automatically remediate the following issue types:

5.3 Enabling Auto-Fix

Prerequisites:

1. Paid plan (Starter, Premium, or Enterprise)
2. GitHub account connected to Conservatory
3. Repository with write access

Steps to enable:

1. In your analysis report, click "Enable Auto-Fix"
2. Connect your GitHub account (if not already connected)
3. Select the repository where the website code is stored
4. Choose the branch to create PRs from (e.g., main or develop)
5. Review permissions:
   • Read: Access repository structure and code
   • Write: Create branches and Pull Requests
   • Not granted: Merge PRs (you maintain full control)
6. Click "Authorize Conservatory"

5.4 Reviewing and Approving Auto-Fixes

After Auto-Fix generates a PR, follow these steps:

1. Notification: You'll receive a GitHub notification and email
2. Review PR: Open the PR in GitHub to review changes
   • PR title: [Conservatory] Fix accessibility and semantic issues (Score: 82 → 91)
   • PR description includes:
     • List of issues fixed
     • Before/after Unison Metrics™ score
     • Detailed explanation of each change
     • Link back to Conservatory report
3. Review Code Diff: Examine the "Files changed" tab
   • Green highlights show added code
   • Red highlights show removed code
   • Each change includes inline comments explaining the fix
4. Test Locally: (Recommended) Check out the PR branch and test changes

   git fetch origin
   git checkout conservatory-fix-abc123
   npm run dev

5. Approve or Request Changes:
   • If satisfied, click "Approve" and "Merge pull request"
   • If adjustments needed, leave comments or edit files directly in the PR
6. Merge: Once approved, merge the PR into your main branch

Safety Features:

• ✅ PRs never auto-merge (you maintain full control)
• ✅ All changes are tracked in Git history
• ✅ Easy rollback if issues occur
• ✅ CI/CD tests run before merge (if configured)

6. GitHub Integration

6.1 Connecting GitHub

1. Go to Settings → Integrations
2. Click "Connect GitHub"
3. Authorize Conservatory to access your GitHub account
4. Select repositories to grant access (or grant access to all repositories)
5. Click "Install & Authorize"

6.2 Repository Setup

For each repository you want to analyze:

1. In Conservatory, go to Repositories
2. Click "Add Repository"
3. Select the repository from the dropdown
4. Configure settings:
   • Default Branch: main or develop
   • PR Base Branch: Branch to create PRs against
   • Auto-Analysis: Enable automatic analysis on commits (Premium/Enterprise)
   • Source Maps: Upload source maps for accurate line attribution (Premium/Enterprise)
5. Click "Save Configuration"

6.3 Source Map Attribution

Source maps allow Conservatory to attribute issues to original source files (before minification/transpilation).

Why this matters:

• Instead of showing issues in bundle.min.js:1:45923
• Conservatory shows src/components/Header.jsx:15:8

How to enable:

1. Generate source maps in your build process

   // webpack.config.js
   module.exports = {
     devtool: 'source-map', // or 'hidden-source-map'
     // ...
   };

2. Upload source maps to Conservatory via CLI or API

   npx conservatory upload-sourcemaps \
     --project=your-project-id \
     --version=v1.2.3 \
     --files=dist/**/*.map

7. API Reference

7.1 Authentication

All API requests require authentication using an API key.

Obtaining an API key:

1. Go to Settings → API Keys
2. Click "Generate New API Key"
3. Name your key (e.g., "Production Server")
4. Click "Create"
5. Copy the API key (shown only once)

Using the API key:

curl -X POST https://api.conservatory.app/v1/analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

7.2 Core API Endpoints

POST /v1/analyze

Start a new website analysis.

Request:

{
  "url": "https://example.com",
  "options": {
    "viewport": "desktop",        // "desktop", "tablet", or "mobile"
    "include_screenshots": true,
    "run_autofix": false
  }
}

Response:

{
  "analysis_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "processing",
  "estimated_time": 60,
  "created_at": "2025-10-23T14:30:00Z"
}

GET /v1/analyze/{analysis_id}

Get the status and results of an analysis.

Response:

{
  "analysis_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "completed",            // "processing", "completed", "failed"
  "url": "https://example.com",
  "unison_metrics_score": 82,
  "dimensions": { ... },
  "issues": [ ... ],
  "completed_at": "2025-10-23T14:31:15Z"
}

GET /v1/reports/{analysis_id}/export

Export analysis report in various formats.

Query Parameters:

• format: json, markdown, pdf, csv

Example:

GET /v1/reports/{analysis_id}/export?format=json

7.3 Rate Limits

Rate limit headers:

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 7
X-RateLimit-Reset: 1634567890

8. CI/CD Integration

8.1 GitHub Actions

Automatically analyze your website on every commit or pull request.

Create .github/workflows/conservatory.yml:

name: Conservatory Analysis

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Run Conservatory Analysis
        uses: conservatory/action@v1
        with:
          api-key: ${{ secrets.CONSERVATORY_API_KEY }}
          url: https://staging.yourwebsite.com
          fail-on-score: 70  # Fail if score below 70
          
      - name: Comment PR with Results
        if: github.event_name == 'pull_request'
        uses: conservatory/comment-action@v1
        with:
          api-key: ${{ secrets.CONSERVATORY_API_KEY }}

8.2 GitLab CI

Add to .gitlab-ci.yml:

conservatory_analysis:
  stage: test
  image: node:18
  script:
    - npx @conservatory/cli analyze \
        --api-key=$CONSERVATORY_API_KEY \
        --url=https://staging.yourwebsite.com \
        --fail-on-score=70
  only:
    - main
    - merge_requests

8.3 Configuring Fail Conditions

Set thresholds to prevent deployments with low scores:

conservatory analyze \
  --url=https://staging.example.com \
  --fail-on-score=75 \
  --fail-on-critical=1 \      # Fail if any critical issues
  └── --fail-on-accessibility=80   # Fail if accessibility score < 80

9. Best Practices

9.1 When to Run Analyses

• Before Launch: Analyze staging site before deploying to production
• After Major Changes: Run analysis after design updates, content changes, or code refactors
• Regular Monitoring: Schedule monthly analyses to catch regressions
• CI/CD Integration: Automate analysis on every PR to prevent score degradation

9.2 Prioritizing Fixes

1. Fix Critical Issues First: Address legal/compliance risks immediately
2. Focus on High-Impact Fixes: Tackle issues that improve multiple dimensions
3. Use Auto-Fix: Let Conservatory handle routine semantic and accessibility fixes
4. Manual Review for Complex Issues: Some issues require human judgment (e.g., content strategy)

9.3 Team Collaboration

• Share Reports: Use export links to share reports with stakeholders
• GitHub PRs: Use Auto-Fix PRs to facilitate code reviews
• Team Accounts: Premium/Enterprise plans support team collaboration with role-based permissions

10. Troubleshooting

10.1 Common Issues

Analysis Failed or Timed Out

Possible causes:

• Website is down or unreachable
• Slow-loading page (>120 seconds)
• Authentication required (login-protected page)

Solutions:

• Verify the URL is publicly accessible
• Optimize page load time (check Core Web Vitals)
• For private pages, use API with authentication headers (Enterprise feature)

"Analysis Limit Reached"

Cause: You've exceeded your monthly analysis limit.

Solutions:

• Wait for your limit to reset (1st of next month)
• Upgrade to a higher plan
• Purchase additional analyses (contact sales)

Auto-Fix PR Not Created

Possible causes:

• GitHub integration not connected
• Insufficient repository permissions
• No fixable issues detected

Solutions:

• Verify GitHub connection in Settings → Integrations
• Ensure Conservatory has "write" access to the repository
• Check that your plan includes Auto-Fix (Starter+)

10.2 Contacting Support

If you encounter issues not covered here:

• Email: Contact support
• Live Chat: Available in-app (Premium/Enterprise)
• Community Forum: Join our Discord

When contacting support, include:

• Analysis ID
• URL analyzed
• Steps to reproduce the issue
• Screenshots or error messages