lighthouse-audit

name	lighthouse-audit
description	Run Lighthouse audits against websites using the Foghorn API. Use when the user wants to check a site's performance, accessibility, best practices, or SEO issues. Covers sign-up, authentication, team/site setup, and issue retrieval.
metadata	{"author":"artgaard","version":"1.0"}
allowed-tools	Bash(curl:*foghorn-api.artgaard.workers.dev*), Read, Write

Lighthouse Audit Skill

Run Lighthouse audits and retrieve performance, accessibility, best-practices, and SEO issues for any website using the Foghorn API.

Overview

Foghorn is a site-health monitoring service built on Lighthouse. You register a site, Foghorn crawls its sitemap, audits every page, and exposes the results through a REST API. This skill lets you interact with that API using curl.

Base URL: https://foghorn-api.artgaard.workers.dev

Authentication

All endpoints (except sign-up, sign-in, and health check) require a Bearer token in the Authorization header.

Step 1 — Check for a stored API key

Read ~/.foghorn. If the file exists and its contents start with fh_, you already have a valid API key. Set the auth header and skip to Setup Workflow:

AUTH="Authorization: Bearer <key from ~/.foghorn>"

Step 2 — First-time setup (only if ~/.foghorn is missing or empty)

If no stored key is found, ask the user for their email and password, then run through sign-up, sign-in, and key creation.

Sign up (first time only)

curl -s -X POST https://foghorn-api.artgaard.workers.dev/auth/sign-up \
  -H "Content-Type: application/json" \
  -d '{"email":"[e-mail]","password":"min8chars"}'

Sign in (get a JWT)

curl -s -X POST https://foghorn-api.artgaard.workers.dev/auth/sign-in \
  -H "Content-Type: application/json" \
  -d '{"email":"[e-mail]","password":"min8chars"}'

Returns { "token": "eyJ...", "expiresIn": 86400, "user": {...} }.

Create an API key

curl -s -X POST https://foghorn-api.artgaard.workers.dev/api-keys \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-agent-key"}'

Returns the full key once in apiKey.key.

Save the key

Write the fh_... key to ~/.foghorn so it is reused in future sessions. Then set the auth header:

AUTH="Authorization: Bearer <key>"

Setup Workflow

Before you can retrieve issues you need a team and a site.

1. Create a team

curl -s -X POST https://foghorn-api.artgaard.workers.dev/teams \
  -H "$AUTH" \
  -H "Content-Type: application/json" \
  -d '{"name":"My Team"}'

2. Add a site

curl -s -X POST https://foghorn-api.artgaard.workers.dev/sites \
  -H "$AUTH" \
  -H "Content-Type: application/json" \
  -d '{"teamId":"TEAM_ID","domain":"www.example.com"}'

The sitemapPath defaults to /sitemap.xml. Override it if your sitemap lives elsewhere.

3. Wait for the crawl

Foghorn periodically scrapes sitemaps and audits discovered pages. Check progress:

curl -s https://foghorn-api.artgaard.workers.dev/sites/SITE_ID \
  -H "$AUTH"

When hasScrapedTheSitemap is true, the sitemap has been processed. Then check pages:

curl -s "https://foghorn-api.artgaard.workers.dev/pages?siteId=SITE_ID" \
  -H "$AUTH"

Pages with a non-null lastAuditedAt have completed audits.

Querying Issues

The /issues endpoint aggregates audit failures across all audited pages.

# All issues for a site
curl -s "https://foghorn-api.artgaard.workers.dev/issues?siteId=SITE_ID" \
  -H "$AUTH"

# Filter by category
curl -s "https://foghorn-api.artgaard.workers.dev/issues?siteId=SITE_ID&category=accessibility" \
  -H "$AUTH"

Categories: performance, accessibility, bestPractices, seo

Response shape

{
  "issues": [
    {
      "auditId": "uses-responsive-images",
      "title": "Properly size images",
      "category": "performance",
      "pages": [
        {
          "pageId": "page-id",
          "url": "https://www.example.com/about",
          "path": "/about",
          "score": 0.45,
          "displayValue": "Potential savings of 120 KiB"
        }
      ]
    }
  ]
}

• Issues are sorted by number of affected pages (most widespread first).
• Pages within each issue are sorted by score ascending (worst first).
• Scores range from 0 (fail) to 1 (pass).

Searching Pages

Find specific pages by URL or path using regex search:

curl -s "https://foghorn-api.artgaard.workers.dev/pages?siteId=SITE_ID&search=blog" \
  -H "$AUTH"

Quick Reference

Method	Path	Purpose
GET	/	Health check
POST	/auth/sign-up	Create account
POST	/auth/sign-in	Get JWT token
POST	/api-keys	Create API key
GET	/api-keys	List API keys
DELETE	/api-keys/:id	Delete API key
POST	/teams	Create team
GET	/teams	List teams
GET	/teams/:id	Get team
PUT	/teams/:id	Update team
DELETE	/teams/:id	Delete team
POST	/teams/:id/members	Add member
GET	/teams/:id/members	List members
DELETE	/teams/:id/members/:userId	Remove member
POST	/sites	Add site
GET	/sites	List sites (optional ?teamId=)
GET	/sites/:id	Get site
PUT	/sites/:id	Update site
DELETE	/sites/:id	Delete site
GET	/pages	List pages (optional ?siteId=, ?search=)
GET	/pages/:id	Get page with audit report
GET	/issues	List issues (optional ?siteId=, ?category=)

See references/api-reference.md for full request/response schemas.