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 connection comes later: connect repositories after signup from the product workflow
5. Agree to the Terms of Service and Privacy Policy
6. Click "Create Account"

Free Plan includes:

• 3 complete analyses per month
• Deterministic semantic, accessibility, SEO, and AEO readiness reports
• JSON/Markdown/PDF exports
• Unison Metrics™ scoring
• Community support

Important Notes:

• ✅ No credit card required for free plan
• ✅ Paid plan access uses the active billing provider when self-serve checkout is available
• ✅ If checkout does not open, choose the target plan in Plan Management and use the documented founders billing fallback via support@conservatory.app

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, view code fixes, 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 processes your website through a launch-safe pipeline optimized for static HTML and SSR-friendly pages:

Stage 1: HTML Capture (5-10s)
├── Fetching static HTML via HTTP request
├── Parsing DOM structure
├── Extracting page metadata
└── Identifying page resources

Stage 2: Parallel Analysis Engines (20-30s)
├── Semantic HTML Analysis
│   ├── HTML5 structure validation
│   ├── ARIA attributes verification
│   └── Heading hierarchy assessment
│
├── Accessibility Signal Analysis
│   ├── Landmark presence and structure checks
│   ├── Form and label coverage
│   └── Alt text and heading signal checks
│
└── SEO Technical Analysis
    ├── Meta tag validation
    ├── Structured data checking
    ├── Canonical and social metadata checks
    └── Link and image metadata assessment

Stage 2B: AEO Readiness Analysis
├── Schema and metadata coverage
├── Content structure signals
└── Discoverability recommendations

Stage 3: Correlation & Scoring (10-15s)
├── Issue classification
├── Impact priority calculation
├── Safe fix suggestion generation
└── Unison Metrics™ score calculation

Stage 4: Report Generation (5-10s)
├── Creating report dashboard
├── Generating code fixes with diffs
└── Preparing JSON/Markdown exports

Total analysis time: varies by page complexity, queue load, and export steps.

Note: Current version is optimized for static HTML and SSR-friendly sites. Deep rendered-page analysis stays outside the current founders launch scope.

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 deterministic checks..." (Stage 2)
  • "Analyzing semantic structure..." (Stage 2)
  • "Calculating report scores..." (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 weighted report score (0-100), designed to summarize the current analysis in one actionable number.

It should be read as a report score for the current engine, not as a substitute for reviewing the underlying findings and supported fixes.

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™ helps summarize issues that influence more than one part of the report:

Example 1: Missing title tag

• Primary impact: technical SEO completeness
• Secondary impact: social metadata consistency
• Fix path: a supported deterministic title fix may be proposed

Example 2: Missing image alt text

• Primary impact: accessibility signal quality
• Secondary impact: metadata completeness for shared assets
• Fix path: Conservatory can propose a deterministic `alt` patch for supported cases

4. Technical Architecture

4.1 Analysis Pipeline Architecture

Conservatory v1.0 uses a pragmatic architecture optimized for speed and cost-effectiveness:

HTML Capture Layer

• Static HTML fetching via HTTPS
• DOM parsing and structure analysis
• Optimized for: Server-Side Rendered sites (Next.js SSR/SSG, Gatsby, Hugo, Jekyll)
• Analysis speed: <60 seconds per page

Current Limitations:

• Does not execute JavaScript (client-side SPAs require Deep Analysis - coming Q2 2026)
• Cannot analyze lazy-loaded content
• Limited to initial HTML response

Deterministic Accessibility Signals

• Deterministic checks based on HTML structure and markup coverage
• Focus on missing alt text, heading hierarchy, landmarks, labels, and metadata
• Best suited for structural accessibility issues that can be detected from fetched HTML
• Deep rendered accessibility analysis is part of the future Deep Analysis track

AI Enhancement Layer

• AI is best used for explanation, prioritization, and UX guidance, not as the primary truth engine
• Current and planned AI-assisted experiences include:
  • Issue explanation
  • Prioritization summaries
  • Natural language recommendations
• Optimized for speed and cost efficiency
• Deterministic findings remain the base layer for launch decisions

Correlation Engine (Unison Metrics™)

• Weighted report scoring across the current analysis dimensions
• Issue prioritization based on severity and category
• Used as a summary layer, not as the only source of truth

4.2 Post-Launch Direction

4.3 What We Use vs. What We're Building

Current Stack (v1.0 - Available Now)

5. Reading Analysis Reports

5.1 Report Structure

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

1. Executive Summary
   • Overall Unison Metrics™ score with grade
   • Current findings that require immediate review
   • Analysis metadata and current workflow context
2. Dimension Breakdown
   • Current score cards across the supported report dimensions
   • Issue totals by category and severity
   • Experimental vector information when available
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.2 Understanding Issue Severity Levels

5.3 Exporting Reports

Conservatory supports multiple export formats:

• JSON: Machine-readable format for API integrations
• Markdown: Human-readable format for documentation
• PDF: Professional report for stakeholders (Premium/Enterprise plans)
• CSV: Spreadsheet format for issue tracking

6. Using Auto-Fix Features

6.1 What is Auto-Fix?

Auto-Fix is Conservatory's review-first remediation system that:

1. Generates deterministic code fixes for supported issue types
2. Supports a Manual Fix Mode so you can preview fixes from analyzed markup without GitHub
3. Supports a GitHub Review Mode so you can review repository-backed diffs and open a draft PR

Key Features:

• 📊 Visual diff viewer: See exactly what will change (like VSCode)
• 👍 Accept or reject: Keep only the patches you want in the draft PR
• 📋 Copy fixed code: Copy the proposed fixed content from the viewer when your plan includes manual fix copy
• 🔒 Full control: PRs never auto-merge without your approval

Available on: Free can preview deterministic manual fixes. Starter, Premium, and Enterprise unlock Copy Code, GitHub review, and draft PR creation.

What makes this different from other tools:

Unlike Lighthouse or axe DevTools that only report issues, Conservatory shows you the exact code changes needed and lets you apply them instantly.

6.2 What Can Be Auto-Fixed?

Conservatory can automatically remediate the following issue types:

6.3 Enabling Auto-Fix

Prerequisites:

1. Any plan to preview manual fixes from a completed analysis
2. Starter, Premium, or Enterprise to copy manual fixes from the workspace
3. Starter, Premium, or Enterprise plus a GitHub repository with write access for draft PR workflows

Steps to use Manual Fix Mode:

1. In your analysis report, click "Open Manual Fix Mode" or open the Auto-Fix workspace
2. Choose a deterministic fix preview from the list
3. Review the interactive diff viewer (see section 6.4 below)
4. Copy the updated markup when your plan includes Copy Code, or upgrade if you are still on Free

Steps to use GitHub Review Mode:

1. Connect your GitHub account through the Conservatory GitHub App
2. Select the repository where the website code is stored
3. Choose the branch to create PRs from (e.g., main or develop)
4. Start the review session and generate repository-backed patches
5. Accept the patches you want to move into the draft PR

6.4 Interactive Diff Viewer

Before creating a GitHub PR, Conservatory shows you exactly what will change using an interactive diff viewer:

Step 1: Review Issues

After analysis completes, click "View Fixes" to see all fixable issues.

Step 2: Visual Diff Review

For each issue, you'll see:

┌─────────────────────────────────────────────┐
│ Files Affected                              │
├─────────────────────────────────────────────┤
│ 📄 index.html                      +3 -0   │
│ 📄 about.html                      +2 -1   │
│ 📄 styles.css                      +12 -0  │
└─────────────────────────────────────────────┘

Side-by-side diff:
  12 <div className="hero">
  13   <img src="logo.png"
- 14        />
+ 14        alt="Company logo" />
  15 </div>

Step 3: Accept or Reject

• 👍 Accept individual fixes or all at once
• ❌ Reject fixes that don't fit your code style

Step 4: Export Options

Once you've approved fixes:

• 📋 Copy to clipboard: Paste directly into your editor when your plan includes Copy Code
• 🔗 Create GitHub draft PR: Generate a draft PR in your repository from accepted patches

Safety Features:

• All changes are reviewable before applying
• Syntax highlighting for all major languages
• Line-by-line comparison
• Preserves your code formatting and style

6.5 GitHub Integration

After approving fixes in the diff viewer, you can create a GitHub draft Pull Request:

1. Review PR: Open the draft PR in GitHub to review changes
   • PR title follows the accepted patch set for the current session
   • PR description includes:
     • a summary of accepted patches
     • the generated branch name
     • the analysis session context
2. Test Locally: (Recommended) Check out the PR branch and test changes
3. 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)

7. GitHub Integration

7.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"

7.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
   • Repository Mapping: Keep a controlled repo connected for Auto-Fix and draft PR workflows
5. Click "Save Configuration"

8. Billing and Plan Management

8.1 What the plans mean today

Conservatory keeps the billing story intentionally narrow during founders:

• Free: report workflow and exports
• Starter: unlocks GitHub-backed Auto-Fix and draft PR creation
• Premium: the same core workflow as Starter, but with more volume
• Enterprise: sales-assisted rollout, not a separate self-serve product

The product truth stays the same even if the payment provider changes: founders should read the upgrade as the jump from report review into review-first remediation.

8.2 What Plan Management does

The Plan Management page is the billing control center during founders. It currently lets you:

• see your current plan and usage snapshot
• store a paid plan intent before or between checkout attempts
• understand whether billing is manual, pending, or active
• see the current founders billing fallback path for paid activation

8.3 Current billing path during founders

Conservatory supports two launch-safe upgrade paths for founders:

1. Self-serve checkout: this is the primary path. If the active billing provider is configured, the selected paid plan hands off directly to checkout.
2. Manual founders billing fallback: if checkout does not open, the founder can still choose the target plan and complete the handoff through support.

Important: the manual founders billing fallback is acceptable during founders, but it should stay secondary and unambiguous by the time the public launch gate is reached.

8.4 Manual founders billing fallback path

If paid checkout does not open from Plan Management, use this path:

1. Choose the target paid plan in Conservatory first
2. Email support@conservatory.app
3. Include your workspace ID, account email, billing email, and selected plan
4. Wait for the founders billing reply with the next step

Recommended subject line: [workspace-id] Founders Starter billing

8.5 Customer portal expectations

The billing portal should be treated as a post-activation convenience, not as the first founders upgrade path.

• If the provider is active for your account and the portal is exposed in-product, it can be used for follow-up billing operations.
• If the provider portal is not exposed yet, support remains the correct path for post-purchase billing changes.
• During founders, support is the fallback for billing ambiguity, not the primary upgrade path.

8.6 Founder upgrade checklist

• confirm the report workflow delivers value first
• decide whether you need only reports or the remediation workflow
• choose the target plan in Plan Management
• use self-serve checkout when it opens
• otherwise use the documented founders billing fallback without waiting or guessing

9. API Reference

9.1 Current Status

Conservatory does not currently offer a public self-serve API for website analysis.

The current product is centered on the web workflow:

• run an analysis from the dashboard
• review the report and exports
• connect GitHub
• prepare Auto-Fix patches
• create a draft PR

Important: any future public API should be treated as post-launch work, not as an already available launch capability.

9.2 What Exists Today

Internally, Conservatory already has application routes that support the product workflow, such as analysis creation, usage snapshots, GitHub repository sync, Auto-Fix sessions, patch acceptance, and draft PR creation.

Those routes power the web app and should not be presented as a public API contract yet.

9.4 Rate Limits

10. CI/CD Integration

10.1 Current Status

Conservatory does not yet ship a public GitHub Action, CLI package, or turnkey CI/CD integration for analysis on every commit.

The current recommended workflow is:

1. run analyses from the dashboard against staging or production URLs
2. review issues and export the report
3. connect GitHub for Auto-Fix and draft PRs on supported issues

10.3 Practical Guidance For Now

• Use a controlled repo for remediation validation
• Run analyses manually before important launches or releases
• Document your smoke test URLs and repositories
• Treat automated CI gating as future work, not a current launch dependency

11. Best Practices

11.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
• Release Readiness: Run manual smoke tests before important launches until CI/CD automation exists

11.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

11.3 Team Collaboration

• Share Reports: Use export links to share reports with stakeholders
• Use Diff Viewer: Review fixes together before creating PRs
• Current launch-safe path: share reports and PR links manually while deeper collaboration features stay post-launch

12. Troubleshooting

12.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
• For private or authenticated pages, start with a public or staging URL in the current launch-safe workflow

"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)

Diff Viewer Not Showing Changes

Possible causes:

• No fixable issues detected
• Issues require manual intervention
• Browser compatibility issue

Solutions:

• Check that your plan includes Auto-Fix (Starter+)
• Try a different browser (Chrome/Firefox recommended)
• Review the full report for manual fix recommendations

12.2 Contacting Support

If you encounter issues not covered here:

• Email: support@conservatory.app
• Documentation: Full documentation

If checkout does not open during the founders phase, select the target paid plan in Plan Management, include your workspace ID and billing email, and support will complete the backup billing handoff.

13. Symphony Instruments

Conservatory is part of the Symphony Ecosystem - a lineup of AI-native instruments for modern product, content, and web workflows.

The currently live instruments are Anthology, Conservatory,Strauss AI, and Unison Metrics.

13.1 Anthology

Anthology is the public product name for the semantic and AI-first framework currently distributed through the existing symphonycss package. If you're building a new project or want to apply Conservatory recommendations at scale, Anthology is also designed with Microsoft NLWeb and conversational interface patterns in mind, and provides:

• Zero-Class Baseline: Beautiful pages with just semantic HTML—no class soup required
• WCAG 2.2 AA Compliance: Accessible by default with pre-configured color systems and typography
• 14.99KB Gzipped: Lightweight yet comprehensive
• AI-First: Designed for AI-assisted building workflows and code generation
• Container Queries: Modern responsive design without viewport breakpoints

Current package surface:

# Install via NPM
npm i symphonycss

# Or use CDN
<link rel="stylesheet" href="https://unpkg.com/@symphonyui/symphonycss/dist/symphony.core.min.css">

Example usage:

<!DOCTYPE html>
<html lang="en">
<head>
  <link rel="stylesheet" href="https://unpkg.com/@symphonyui/symphonycss/dist/symphony.core.min.css">
</head>
<body>
  <main>
    <article>
      <h1>Welcome to Anthology</h1>
      <p>Beautiful pages with just semantic HTML.</p>
      <button data-variant="primary">Get Started</button>
    </article>
  </main>
</body>
</html>

Learn more:

• GitHub Repository
• NPM Package
• Full Documentation

13.2 Current Symphony Lineup

• Anthology: semantic and AI-first framework for modern and conversational interfaces
• Conservatory: website intelligence and review-first remediation
• Strauss AI: ecosystem AI layer for explanation and guidance
• Unison Metrics: weighted scoring and correlation system

13.3 Combining Conservatory + Anthology

Recommended Workflow:

1. Analyze your existing site with Conservatory
2. Review semantic HTML and accessibility recommendations
3. Rebuild with Anthology to implement best practices from scratch
4. Re-analyze to verify improvements (typically see 20-30 point score increase)

Many Conservatory users report that starting new projects with Anthology significantly reduces the need for post-launch fixes identified in analyses.