@eightmedia/flightcheck 0.0.0-stage → 0.1.0

package/dist/crawler/tier1Extractors.js

@@ -0,0 +1,255 @@
+function crawlIssue(id, severity, message) {
+    return { id, severity, message };
+}
+function parsePixelSize(value) {
+    if (!value)
+        return null;
+    const match = value.trim().match(/^(\d+(?:\.\d+)?)px$/i);
+    return match ? Number(match[1]) : null;
+}
+function isDecorativeImage($img) {
+    if ($img.attr("aria-hidden") === "true")
+        return true;
+    if (($img.attr("role") ?? "").toLowerCase() === "presentation")
+        return true;
+    const width = parsePixelSize($img.attr("width")) ?? parsePixelSize($img.attr("style")?.match(/width:\s*(\d+px)/i)?.[1]);
+    const height = parsePixelSize($img.attr("height")) ?? parsePixelSize($img.attr("style")?.match(/height:\s*(\d+px)/i)?.[1]);
+    if (width !== null && height !== null && width <= 2 && height <= 2)
+        return true;
+    return false;
+}
+const GENERIC_ALT = new Set(["image", "photo", "picture", "img", "logo", "icon"]);
+const IMAGE_EXTENSION_RE = /\.(?:jpe?g|png|gif|webp|avif|svg)$/i;
+const IMAGE_FILENAME_IN_TEXT_RE = /([^\/?#\s&,=]+\.(?:jpe?g|png|gif|webp|avif|svg))/gi;
+function tryDecodeURIComponent(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return value;
+    }
+}
+function looksUrlEncoded(value) {
+    return /%[0-9a-f]{2}/i.test(value);
+}
+function extractProxyImageUrl(value) {
+    if (!/[?&]url=/i.test(value))
+        return null;
+    const match = value.match(/[?&]url=([^&]+)/i);
+    if (!match?.[1])
+        return null;
+    return tryDecodeURIComponent(match[1]);
+}
+function isValidImageFilename(filename) {
+    if (!filename || filename.includes("&") || filename.includes("="))
+        return false;
+    if (filename.includes("%") || filename.includes("://"))
+        return false;
+    if (!IMAGE_EXTENSION_RE.test(filename))
+        return false;
+    return !/^\d+$/.test(filename.replace(IMAGE_EXTENSION_RE, ""));
+}
+function filenameFromUrl(url) {
+    let working = url.trim();
+    if (!working || working.startsWith("data:") || working.startsWith("blob:"))
+        return null;
+    if (looksUrlEncoded(working)) {
+        working = tryDecodeURIComponent(working);
+    }
+    const proxyUrl = extractProxyImageUrl(working);
+    if (proxyUrl) {
+        working = proxyUrl;
+    }
+    let pathname;
+    try {
+        pathname = working.includes("://") ? new URL(working).pathname : working.split(/[?#]/)[0] ?? "";
+    }
+    catch {
+        pathname = working.split(/[?#]/)[0] ?? "";
+    }
+    const filename = pathname.split("/").filter(Boolean).pop() ?? "";
+    return isValidImageFilename(filename) ? filename : null;
+}
+function filenamesInText(text) {
+    const seen = new Set();
+    const filenames = [];
+    const decoded = looksUrlEncoded(text) ? tryDecodeURIComponent(text) : text;
+    for (const source of [text, decoded]) {
+        for (const match of source.matchAll(IMAGE_FILENAME_IN_TEXT_RE)) {
+            const filename = match[1];
+            if (!isValidImageFilename(filename) || seen.has(filename))
+                continue;
+            seen.add(filename);
+            filenames.push(filename);
+        }
+    }
+    return filenames;
+}
+function srcsetCandidates(srcset) {
+    return srcset
+        .split(/,\s*(?=(?:https?:)?\/)/i)
+        .map((entry) => entry.trim().split(/\s+/)[0] ?? "")
+        .filter(Boolean);
+}
+function imageReferenceFromValue(value, pageUrl) {
+    const trimmed = value.trim();
+    if (!trimmed)
+        return null;
+    const candidates = /\d+w|\d+x/i.test(trimmed) ? srcsetCandidates(trimmed) : [trimmed];
+    for (const candidate of candidates) {
+        const decoded = tryDecodeURIComponent(candidate);
+        const proxyUrl = extractProxyImageUrl(candidate) ?? extractProxyImageUrl(decoded);
+        const lookups = [proxyUrl, decoded, candidate].filter((entry) => Boolean(entry));
+        for (const lookup of lookups) {
+            const filename = filenameFromUrl(lookup) ?? filenamesInText(lookup)[0];
+            if (!filename)
+                continue;
+            const url = toAbsoluteImageUrl(lookup, pageUrl);
+            if (!url)
+                continue;
+            return { filename, url };
+        }
+    }
+    return null;
+}
+function toAbsoluteImageUrl(value, pageUrl) {
+    let working = value.trim();
+    if (!working || working.startsWith("data:") || working.startsWith("blob:"))
+        return null;
+    if (looksUrlEncoded(working)) {
+        working = tryDecodeURIComponent(working);
+    }
+    const proxyUrl = extractProxyImageUrl(working);
+    if (proxyUrl) {
+        working = proxyUrl;
+    }
+    try {
+        return working.includes("://") ? new URL(working).href : new URL(working, pageUrl).href;
+    }
+    catch {
+        return null;
+    }
+}
+function collectImageReference($, $img, pageUrl) {
+    const candidates = [];
+    const src = ($img.attr("src") ?? "").trim();
+    if (src)
+        candidates.push(src);
+    const srcset = ($img.attr("srcset") ?? "").trim();
+    if (srcset)
+        candidates.push(srcset);
+    const $picture = $img.closest("picture");
+    if ($picture.length > 0) {
+        $picture.find("source").each((_, source) => {
+            const $source = $(source);
+            const sourceSrc = ($source.attr("src") ?? "").trim();
+            if (sourceSrc)
+                candidates.push(sourceSrc);
+            const sourceSrcset = ($source.attr("srcset") ?? "").trim();
+            if (sourceSrcset)
+                candidates.push(sourceSrcset);
+        });
+    }
+    for (const candidate of candidates) {
+        const reference = imageReferenceFromValue(candidate, pageUrl);
+        if (reference)
+            return reference;
+    }
+    return null;
+}
+function imageIssueMessage(base, reference) {
+    if (!reference)
+        return base;
+    return `${base} ([${reference.filename}](${reference.url}))`;
+}
+function isGenericAlt(alt, src) {
+    const normalized = alt.trim().toLowerCase();
+    if (!normalized)
+        return false;
+    if (GENERIC_ALT.has(normalized))
+        return true;
+    const filename = src.split("/").pop()?.split("?")[0] ?? "";
+    const basename = filename.replace(/\.[^.]+$/, "").toLowerCase();
+    return basename.length > 0 && normalized === basename;
+}
+export function extractImageIssues($, pageUrl) {
+    const issues = [];
+    $("img").each((_, element) => {
+        const $img = $(element);
+        if (isDecorativeImage($img))
+            return;
+        const src = ($img.attr("src") ?? "").trim();
+        const reference = collectImageReference($, $img, pageUrl);
+        const hasAlt = $img.get(0)?.attribs && Object.prototype.hasOwnProperty.call($img.get(0).attribs, "alt");
+        const alt = ($img.attr("alt") ?? "").trim();
+        if (!hasAlt) {
+            issues.push(crawlIssue("missing-alt", "error", imageIssueMessage("Image is missing an alt attribute.", reference)));
+            return;
+        }
+        if (alt.length === 0) {
+            issues.push(crawlIssue("empty-alt", "warning", imageIssueMessage("Image has an empty alt attribute.", reference)));
+            return;
+        }
+        if (isGenericAlt(alt, src)) {
+            issues.push(crawlIssue("generic-alt", "warning", imageIssueMessage("Image uses generic alt text.", reference)));
+        }
+    });
+    return issues;
+}
+function headingLevel(tagName) {
+    const match = tagName.match(/^h([1-6])$/i);
+    return match ? Number(match[1]) : null;
+}
+function hasAssociatedLabel($, $input) {
+    const id = ($input.attr("id") ?? "").trim();
+    if (id && $(`label[for="${id}"]`).length > 0)
+        return true;
+    if (($input.attr("aria-label") ?? "").trim())
+        return true;
+    if (($input.attr("aria-labelledby") ?? "").trim())
+        return true;
+    if ($input.parents("label").length > 0)
+        return true;
+    if (($input.attr("title") ?? "").trim())
+        return true;
+    return false;
+}
+export function extractA11yStaticIssues($) {
+    const issues = [];
+    const headings = $("h1, h2, h3, h4, h5, h6")
+        .toArray()
+        .map((element) => headingLevel("name" in element ? String(element.name) : ""))
+        .filter((level) => level !== null);
+    if ($("h1").length > 1) {
+        issues.push(crawlIssue("multiple-h1", "warning", "Page has multiple h1 elements."));
+    }
+    let previousLevel = null;
+    for (const level of headings) {
+        if (previousLevel !== null && level > previousLevel + 1) {
+            issues.push(crawlIssue("heading-skip", "warning", "Heading levels skip a rank."));
+            break;
+        }
+        previousLevel = level;
+    }
+    const lang = ($("html").first().attr("lang") ?? "").trim();
+    if (!lang) {
+        issues.push(crawlIssue("missing-lang", "error", "html element is missing a lang attribute."));
+    }
+    $("input, select, textarea")
+        .not('[type="hidden"], [type="submit"], [type="button"], [type="reset"], [type="image"]')
+        .each((_, element) => {
+        const $input = $(element);
+        if (!hasAssociatedLabel($, $input)) {
+            issues.push(crawlIssue("unlabeled-input", "error", "Form control is missing an associated label."));
+        }
+    });
+    $("[tabindex]")
+        .toArray()
+        .forEach((element) => {
+        const value = Number.parseInt($(element).attr("tabindex") ?? "", 10);
+        if (Number.isFinite(value) && value > 0) {
+            issues.push(crawlIssue("positive-tabindex", "warning", "Element uses a positive tabindex."));
+        }
+    });
+    return issues;
+}

package/dist/crawler/tracking.d.ts

@@ -0,0 +1,8 @@
+import type { TrackingItem } from "./schema.js";
+type TrackingResult = {
+    tagManager: TrackingItem[];
+    analytics: TrackingItem[];
+};
+export declare function extractTracking(html: string): TrackingResult;
+export {};
+//# sourceMappingURL=tracking.d.ts.map

package/dist/crawler/tracking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracking.d.ts","sourceRoot":"","sources":["../../src/crawler/tracking.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,KAAK,cAAc,GAAG;IACpB,UAAU,EAAE,YAAY,EAAE,CAAC;IAC3B,SAAS,EAAE,YAAY,EAAE,CAAC;CAC3B,CAAC;AAMF,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAkD5D"}

package/dist/crawler/tracking.js

@@ -0,0 +1,50 @@
+function uniq(values) {
+    return [...new Set(values)];
+}
+export function extractTracking(html) {
+    const fullText = html;
+    const tagManager = [];
+    const analytics = [];
+    const gtmMatches = fullText.match(/GTM-[A-Z0-9]+/gi) ?? [];
+    const ga4Matches = fullText.match(/\bG-[A-Z0-9]{6,}\b/gi) ?? [];
+    const uaMatches = fullText.match(/\bUA-\d+-\d+\b/gi) ?? [];
+    const matomoSiteIdMatches = fullText.match(/(?:_paq\.push\(\[['"]setSiteId['"],\s*['"]?(\d+)['"]?\]\)|siteId['"]?\s*[:=]\s*['"]?(\d+)['"]?)/gi) ?? [];
+    const pixelMatches = fullText.match(/\bfbq\(['"]init['"],\s*['"](\d{6,})['"]\)/gi) ?? [];
+    const plausibleMatch = /plausible\.io\/js\/script\.js/i.test(fullText);
+    for (const id of uniq(gtmMatches)) {
+        tagManager.push({ provider: "google-tag-manager", id });
+    }
+    for (const id of uniq(ga4Matches)) {
+        analytics.push({ provider: "google-analytics-ga4", id });
+    }
+    for (const id of uniq(uaMatches)) {
+        analytics.push({ provider: "google-analytics-ua", id });
+    }
+    for (const raw of uniq(matomoSiteIdMatches)) {
+        const idMatch = raw.match(/(\d+)/);
+        if (idMatch)
+            analytics.push({ provider: "matomo", id: idMatch[1] });
+    }
+    for (const raw of uniq(pixelMatches)) {
+        const idMatch = raw.match(/(\d{6,})/);
+        if (idMatch)
+            analytics.push({ provider: "facebook-pixel", id: idMatch[1] });
+    }
+    if (plausibleMatch) {
+        analytics.push({ provider: "plausible", id: "" });
+    }
+    const dedupeByProviderAndId = (items) => {
+        const seen = new Set();
+        return items.filter((item) => {
+            const key = `${item.provider}:${item.id}`;
+            if (seen.has(key))
+                return false;
+            seen.add(key);
+            return true;
+        });
+    };
+    return {
+        tagManager: dedupeByProviderAndId(tagManager),
+        analytics: dedupeByProviderAndId(analytics),
+    };
+}

package/dist/crawler/urlUtils.d.ts

@@ -0,0 +1,12 @@
+export declare function sleep(ms: number): Promise<void>;
+/**
+ * True for Vercel or Netlify platform default/preview hostnames.
+ * Custom production domains mapped onto those platforms return false.
+ */
+export declare function isPlatformPreviewHostname(hostname: string): boolean;
+export declare function isHttpUrl(urlString: string): boolean;
+export declare function normalizeUrl(urlString: string): string;
+export declare function resolveUrlMaybe(value: string, baseUrl: string): string;
+export declare function parseExcludePatterns(rawExcludes: string[]): string[];
+export declare function matchesExcludePattern(urlString: string, patterns: string[]): boolean;
+//# sourceMappingURL=urlUtils.d.ts.map

package/dist/crawler/urlUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"urlUtils.d.ts","sourceRoot":"","sources":["../../src/crawler/urlUtils.ts"],"names":[],"mappings":"AAAA,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C;AAKD;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAGnE;AAED,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAOpD;AAED,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAUtD;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAOtE;AAED,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAGpE;AAED,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAKpF"}

package/dist/crawler/urlUtils.js

@@ -0,0 +1,53 @@
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** Vercel / Netlify platform hostnames (*.vercel.app, *.netlify.app) — not custom domains. */
+const PLATFORM_PREVIEW_SUFFIXES = [".vercel.app", ".netlify.app"];
+/**
+ * True for Vercel or Netlify platform default/preview hostnames.
+ * Custom production domains mapped onto those platforms return false.
+ */
+export function isPlatformPreviewHostname(hostname) {
+    const lower = hostname.toLowerCase();
+    return PLATFORM_PREVIEW_SUFFIXES.some((suffix) => lower === suffix.slice(1) || lower.endsWith(suffix));
+}
+export function isHttpUrl(urlString) {
+    try {
+        const url = new URL(urlString);
+        return url.protocol === "http:" || url.protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+}
+export function normalizeUrl(urlString) {
+    const url = new URL(urlString);
+    url.hash = "";
+    url.search = "";
+    if (url.pathname === "") {
+        url.pathname = "/";
+    }
+    return url.toString();
+}
+export function resolveUrlMaybe(value, baseUrl) {
+    if (!value)
+        return "";
+    try {
+        return normalizeUrl(new URL(value, baseUrl).toString());
+    }
+    catch {
+        return value;
+    }
+}
+export function parseExcludePatterns(rawExcludes) {
+    if (rawExcludes.length === 0)
+        return [];
+    return rawExcludes.flatMap((item) => item.split(",")).map((item) => item.trim()).filter(Boolean);
+}
+export function matchesExcludePattern(urlString, patterns) {
+    if (patterns.length === 0)
+        return false;
+    const normalized = normalizeUrl(urlString);
+    const pathname = new URL(normalized).pathname;
+    return patterns.some((pattern) => normalized.includes(pattern) || pathname.includes(pattern));
+}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+export * from "./checks/index.js";
+export { buildMarkdown, parseReport, reportSchema, buildReportAnalysis } from "./analyze/report.js";
+export { buildStructuredReport, renderReportMarkdown, FLIGHTCHECK_REPORT_VERSION, } from "./analyze/structuredReport.js";
+export type { ReportRecord, Tier1ReportData, BuildMarkdownOptions, ReportAnalysis } from "./analyze/report.js";
+export type { FlightcheckReport, FlightcheckReportAnalysis, ReportFinding, FindingSeverity, FindingCategory, FindingScope, } from "./analyze/structuredReport.js";
+/** @deprecated Prefer structured report JSON; kept for transitional imports. */
+export { buildFixManifest, FIX_MANIFEST_VERSION } from "./analyze/fixManifest.js";
+/** @deprecated Prefer structured report JSON; kept for transitional imports. */
+export type { FixManifest, WorkPackage, ManifestIssue, LocationDiscovery, FixSurface, } from "./analyze/fixManifest.js";
+export { runCrawler } from "./crawler/runCrawler.js";
+export type { VerificationRecord } from "./crawler/schema.js";
+export { CHECK_GROUPS, resolveActiveGroups } from "./crawler/checkGroups.js";
+export type { CheckGroup } from "./crawler/checkGroups.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAElC,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AACpG,OAAO,EACL,qBAAqB,EACrB,oBAAoB,EACpB,0BAA0B,GAC3B,MAAM,+BAA+B,CAAC;AACvC,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC/G,YAAY,EACV,iBAAiB,EACjB,yBAAyB,EACzB,aAAa,EACb,eAAe,EACf,eAAe,EACf,YAAY,GACb,MAAM,+BAA+B,CAAC;AACvC,gFAAgF;AAChF,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAClF,gFAAgF;AAChF,YAAY,EACV,WAAW,EACX,WAAW,EACX,aAAa,EACb,iBAAiB,EACjB,UAAU,GACX,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,YAAY,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC7E,YAAY,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+export * from "./checks/index.js";
+export { buildMarkdown, parseReport, reportSchema, buildReportAnalysis } from "./analyze/report.js";
+export { buildStructuredReport, renderReportMarkdown, FLIGHTCHECK_REPORT_VERSION, } from "./analyze/structuredReport.js";
+/** @deprecated Prefer structured report JSON; kept for transitional imports. */
+export { buildFixManifest, FIX_MANIFEST_VERSION } from "./analyze/fixManifest.js";
+export { runCrawler } from "./crawler/runCrawler.js";
+export { CHECK_GROUPS, resolveActiveGroups } from "./crawler/checkGroups.js";

package/docs/agent-fixes.md

@@ -0,0 +1,17 @@
+# Agent fixes (deprecated)
+
+**Status:** deprecated. Analyze no longer writes `*-fix-manifest.json` or
+`*-agent-jobs/`.
+
+Use the structured report instead:
+
+- [Analyze reports](./analyze.md) — `*-report.json` + `*-report.md`
+- [Design](./superpowers/specs/2026-10-27-structured-report-design.md)
+
+The previous agent-jobs / fix-manifest workflow (work packages, `prompt.md` per
+package, `flightcheck-orchestrate`) remains in the repo for transitional imports
+but is not part of the default output. Prefer building any new agent automation
+on `findings[]` in `*-report.json`.
+
+Stack detection still feeds the report `analysis.stack` block. See
+[stack.md](./stack.md).

package/docs/agent-ready.md

@@ -0,0 +1,44 @@
+# Agent readiness
+
+Flightcheck can audit how ready a site is for AI agents, aligned with the practical
+checks from [isitagentready.com](https://isitagentready.com/).
+
+**Status:** implemented as standalone check `agent-ready` (default pipeline).
+
+## What it checks
+
+| Area | Signal | Severity when missing |
+| --- | --- | --- |
+| Bot access | `Content-Signal` in robots.txt | warning |
+| Bot access | Explicit AI bot `User-agent` rules (GPTBot, ClaudeBot, …) | warning |
+| Content | `/llms.txt` plain-text overview with `#` title | warning / review if incomplete |
+| Content | Markdown negotiation (`Accept: text/markdown` → `text/markdown`) | warning |
+| Discoverability | Homepage `Link` headers (`api-catalog`, `service-doc`, …) | review |
+| Protocols | Well-known MCP / Agent Skills / API Catalog / ARD / A2A | review (informational for content sites) |
+
+robots.txt existence and sitemaps remain in the existing `robots-txt` and `sitemap` checks.
+
+## Architecture
+
+- Module: `src/checks/agent-ready.ts`
+- Pure analyzer: `analyzeAgentReady()` (unit-tested)
+- Network runner: `runAgentReadyCheck()` — parallel fetches of robots, llms.txt, homepage
+  (HTML + markdown Accept), and well-known endpoints
+- Wave 1 (parallel with crawl / DNS / headers / robots)
+- Report section: `## Agent readiness` via `buildAgentReadySection()` in `reportTier1.ts`
+- Fix package: `agent-ready` → `prompts/fix/agent-ready.md`
+
+## CLI
+
+```bash
+pnpm run flightcheck -- https://example.com
+pnpm run flightcheck -- https://example.com --checks agent-ready,analyze
+```
+
+## Out of scope (for now)
+
+- Commerce protocols (x402, UCP, ACP, MPP)
+- Web Bot Auth
+- DNS-AID
+- WebMCP (needs a browser)
+- Full OAuth / Auth.md discovery as hard failures

package/docs/analyze.md

@@ -0,0 +1,103 @@
+# Flightcheck Analyze Script
+
+This script reads a crawl JSON file and produces a structured report:
+
+- `*-report.json` — machine-readable analysis + findings
+- `*-report.md` — plain-language Markdown rendered from that JSON
+
+The main CLI (`flightcheck`) generates both by default after every crawl. Use this
+standalone script only when you want to re-analyze an existing JSON file without re-crawling.
+
+## Purpose
+
+- Give tools a stable JSON schema (`analysis` + flat `findings[]`).
+- Give people a readable Markdown report generated from the same model.
+- Keep severity, category, and scope on every finding.
+
+## Usage
+
+```bash
+pnpm run analyze -- ./flightcheck/20260618.1413-example.com-raw.json
+```
+
+Include only critical/error findings in the Markdown view:
+
+```bash
+pnpm run analyze -- ./flightcheck/20260618.1413-example.com-raw.json --errors-only
+```
+
+Without `--output`, paths are derived from the input: `-raw.json` becomes
+`-report.md` and `-report.json`.
+
+## Output structure
+
+### `*-report.json`
+
+```json
+{
+  "version": 1,
+  "generatedAt": "2026-10-27T12:00:00.000Z",
+  "source": "./flightcheck/example-raw.json",
+  "redirectOnly": false,
+  "analysis": {
+    "pagesAnalyzed": 24,
+    "pagesWithIssues": 13,
+    "findingCounts": {
+      "critical": 1,
+      "error": 12,
+      "warning": 8,
+      "review": 3
+    },
+    "stack": [
+      {
+        "name": "Next.js",
+        "categories": ["JavaScript frameworks"],
+        "confidence": "high",
+        "evidence": ["Next.js runtime markers in HTML"],
+        "pageCount": 24
+      }
+    ],
+    "templates": ["work", "blog"],
+    "reviewPages": []
+  },
+  "findings": [
+    {
+      "id": "missing-hsts",
+      "severity": "error",
+      "category": "infra",
+      "scope": "origin",
+      "title": "Missing Hsts",
+      "message": "Strict-Transport-Security header is missing on HTTPS."
+    }
+  ]
+}
+```
+
+Findings are a flat list (no severity buckets), sorted critical → review. Each finding
+includes metadata so consumers can filter or regroup.
+
+| Field | Meaning |
+| --- | --- |
+| `severity` | `critical` \| `error` \| `warning` \| `review` |
+| `category` | `infra` \| `seo` \| `a11y` \| `best-practices` \| `security` \| `performance` |
+| `scope` | `site-wide` \| `template` \| `page` \| `origin` |
+| `title` | Short human title |
+| `message` | What to do / what was found |
+| `template` | Present when `scope` is `template` |
+| `urls` / `count` | Affected pages when relevant |
+
+### `*-report.md`
+
+Generated from the JSON. Structure:
+
+1. **At a glance** — page counts and finding totals
+2. **Stack / DNS / redirect** — factual context when available
+3. **Findings** — grouped by severity for reading order, with plain-language titles
+
+## Notes
+
+- The script validates crawl input against the expected flightcheck report schema.
+- On schema errors, the script stops with a clear error message.
+- Fix-manifest and agent-jobs output are no longer generated. Prefer `*-report.json`
+  for machine consumers. See the design note in
+  [superpowers/specs/2026-10-27-structured-report-design.md](./superpowers/specs/2026-10-27-structured-report-design.md).