@eightmedia/flightcheck 1.0.1 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [1.1.0] — 2026-10-28
+
+### Added
+
+- Findings include an optional `fix` suggestion in `*-report.json` and Markdown (`- Fix: …`)
+
+### Changed
+
+- Default `--max-pages` is now **100** (was 1000)
+- Within the page budget, crawl seeds are selected from **URL-tree shape** (not slug
+  names): home/structural pages and list indexes first, then a fair sample of leaf
+  URLs under parents that have many leaf children
+- Discovered structural links jump the queue; leaf URLs under list parents are capped
+
 ## [1.0.1] — 2026-10-28
 
 ### Added

package/dist/analyze/structuredReport.d.ts

@@ -18,6 +18,8 @@ export type ReportFinding = {
     scope: FindingScope;
     title: string;
     message: string;
+    /** Concrete remediation suggestion when available. */
+    fix?: string;
     template?: string;
     urls?: string[];
     count?: number;

package/dist/analyze/structuredReport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"structuredReport.d.ts","sourceRoot":"","sources":["../../src/analyze/structuredReport.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"structuredReport.d.ts","sourceRoot":"","sources":["../../src/analyze/structuredReport.ts"],"names":[],"mappings":"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"}

package/dist/analyze/structuredReport.js

@@ -170,6 +170,7 @@ function findingFromCheck(issue, category, scope, extras = {}) {
         scope,
         title: humanizeId(issue.id),
         message: issue.message,
+        ...(issue.fix ? { fix: issue.fix } : {}),
         ...extras,
     };
 }
@@ -182,29 +183,35 @@ function pushUnique(findings, finding) {
     findings.push(finding);
 }
 function collectSeoFindings(fields, scope, count, extras = {}) {
-    return fields.map((field) => ({
-        id: field,
-        severity: "error",
-        category: "seo",
-        scope,
-        title: fieldTitle(field),
-        message: fieldMessage(field, scope, extras.template),
-        count,
-        ...extras,
-    }));
+    return fields.map((field) => {
+        const message = fieldMessage(field, scope, extras.template);
+        return {
+            id: field,
+            severity: "error",
+            category: "seo",
+            scope,
+            title: fieldTitle(field),
+            message,
+            fix: message,
+            count,
+            ...extras,
+        };
+    });
 }
 function collectBestPracticeFindings(keys, scope, count, extras = {}) {
     return keys
         .filter((key) => BEST_PRACTICE_IDS.has(key))
         .map((key) => {
         const copy = BEST_PRACTICE_COPY[key];
+        const message = copy?.message ?? `Fix ${key}.`;
         return {
             id: key,
             severity: copy?.severity ?? "review",
             category: "best-practices",
             scope,
             title: copy?.title ?? humanizeId(key),
-            message: copy?.message ?? `Fix ${key}.`,
+            message,
+            fix: message,
             count,
             ...extras,
         };
@@ -215,13 +222,15 @@ function collectA11yFindings(keys, scope, count, extras = {}) {
         .filter((key) => A11Y_IDS.has(key))
         .map((key) => {
         const copy = A11Y_COPY[key];
+        const message = copy?.message ?? `Fix accessibility issue: ${key}.`;
         return {
             id: key,
             severity: "warning",
             category: "a11y",
             scope,
             title: copy?.title ?? humanizeId(key),
-            message: copy?.message ?? `Fix accessibility issue: ${key}.`,
+            message,
+            fix: message,
             count,
             ...extras,
         };
@@ -284,6 +293,7 @@ function buildFindings(analysis, tier1) {
                 scope: "page",
                 title: `Exposed ${secret.provider} ${secret.type}`,
                 message: `Rotate or remove this secret. Masked value: ${secret.masked} (source: ${secret.source}).`,
+                fix: "Remove the secret from client-side HTML/JS, rotate the credential, and load secrets only from a server-side env.",
                 urls: [page.url],
                 count: 1,
             });
@@ -313,13 +323,15 @@ function buildFindings(analysis, tier1) {
     if (!analysis.redirectOnly) {
         const seoById = aggregatePageFindings(analysis.pageFixes, (fix) => fix.remainingFields.map((id) => ({ id })));
         for (const [id, { urls }] of seoById) {
+            const message = fieldMessage(id, "page");
             findings.push({
                 id,
                 severity: "error",
                 category: "seo",
                 scope: "page",
                 title: fieldTitle(id),
-                message: fieldMessage(id, "page"),
+                message,
+                fix: message,
                 urls,
                 count: urls.length,
             });
@@ -327,13 +339,15 @@ function buildFindings(analysis, tier1) {
         const bestById = aggregatePageFindings(analysis.pageFixes, (fix) => fix.remainingWarningKeys.filter((key) => BEST_PRACTICE_IDS.has(key)).map((id) => ({ id })));
         for (const [id, { urls }] of bestById) {
             const copy = BEST_PRACTICE_COPY[id];
+            const message = copy?.message ?? `Fix ${id}.`;
             findings.push({
                 id,
                 severity: copy?.severity ?? "review",
                 category: "best-practices",
                 scope: "page",
                 title: copy?.title ?? humanizeId(id),
-                message: copy?.message ?? `Fix ${id}.`,
+                message,
+                fix: message,
                 urls,
                 count: urls.length,
             });
@@ -341,13 +355,15 @@ function buildFindings(analysis, tier1) {
         const a11yById = aggregatePageFindings(analysis.pageFixes, (fix) => fix.remainingA11yIssues.map((issue) => ({ id: issue.id, message: issue.message })));
         for (const [id, { urls, message }] of a11yById) {
             const copy = A11Y_COPY[id];
+            const resolved = message ?? copy?.message ?? `Fix accessibility issue: ${id}.`;
             findings.push({
                 id,
                 severity: "warning",
                 category: "a11y",
                 scope: "page",
                 title: copy?.title ?? humanizeId(id),
-                message: message ?? copy?.message ?? `Fix accessibility issue: ${id}.`,
+                message: resolved,
+                fix: copy?.message ?? resolved,
                 urls,
                 count: urls.length,
             });
@@ -439,6 +455,8 @@ function formatFindingMarkdown(finding) {
     const lines = [`#### ${finding.title}`, "", finding.message, "", `- Where: ${scopeLabel(finding)}`];
     if (finding.category)
         lines.push(`- Category: ${finding.category}`);
+    if (finding.fix)
+        lines.push(`- Fix: ${finding.fix}`);
     if (finding.urls && finding.urls.length > 1) {
         lines.push("- Pages:");
         for (const url of finding.urls.slice(0, 20)) {

package/dist/checks/agent-ready.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-ready.d.ts","sourceRoot":"","sources":["../../src/checks/agent-ready.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAGrD,6FAA6F;AAC7F,eAAO,MAAM,kBAAkB,8LAarB,CAAC;AAEX,4EAA4E;AAC5E,eAAO,MAAM,eAAe,wEAAyE,CAAC;AAEtG,MAAM,MAAM,qBAAqB,GAAG;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,SAAS,EAAE;QACT,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QACtB,iBAAiB,EAAE,OAAO,CAAC;QAC3B,cAAc,EAAE,MAAM,EAAE,CAAC;QACzB,eAAe,EAAE,MAAM,EAAE,CAAC;KAC3B,CAAC;IACF,OAAO,EAAE;QACP,GAAG,EAAE,MAAM,CAAC;QACZ,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QACtB,QAAQ,EAAE,OAAO,CAAC;KACnB,CAAC;IACF,mBAAmB,EAAE;QACnB,GAAG,EAAE,MAAM,CAAC;QACZ,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QACtB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,gBAAgB,EAAE,OAAO,CAAC;KAC3B,CAAC;IACF,WAAW,EAAE;QACX,SAAS,EAAE,MAAM,EAAE,CAAC;KACrB,CAAC;IACF,SAAS,EAAE;QACT,aAAa,EAAE,OAAO,CAAC;QACvB,WAAW,EAAE,OAAO,CAAC;QACrB,UAAU,EAAE,OAAO,CAAC;QACpB,GAAG,EAAE,OAAO,CAAC;QACb,YAAY,EAAE,OAAO,CAAC;KACvB,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,MAAM,EAAE,UAAU,EAAE,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,qBAAqB,CAAC;IAClC,OAAO,CAAC,EAAE,qBAAqB,CAAC;IAChC,QAAQ,CAAC,EAAE,qBAAqB,CAAC;IACjC,QAAQ,CAAC,EAAE,qBAAqB,CAAC;IACjC,SAAS,CAAC,EAAE;QACV,aAAa,CAAC,EAAE,qBAAqB,CAAC;QACtC,WAAW,CAAC,EAAE,qBAAqB,CAAC;QACpC,UAAU,CAAC,EAAE,qBAAqB,CAAC;QACnC,GAAG,CAAC,EAAE,qBAAqB,CAAC;QAC5B,YAAY,CAAC,EAAE,qBAAqB,CAAC;KACtC,CAAC;CACH,CAAC;AAoDF,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,sBAAsB,GAAG,qBAAqB,CAoItF;AAmCD,wBAAsB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,SAAS,GAAG,OAAO,CAAC,qBAAqB,CAAC,CA+C7G"}
+{"version":3,"file":"agent-ready.d.ts","sourceRoot":"","sources":["../../src/checks/agent-ready.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAGrD,6FAA6F;AAC7F,eAAO,MAAM,kBAAkB,8LAarB,CAAC;AAEX,4EAA4E;AAC5E,eAAO,MAAM,eAAe,wEAAyE,CAAC;AAEtG,MAAM,MAAM,qBAAqB,GAAG;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,SAAS,EAAE;QACT,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QACtB,iBAAiB,EAAE,OAAO,CAAC;QAC3B,cAAc,EAAE,MAAM,EAAE,CAAC;QACzB,eAAe,EAAE,MAAM,EAAE,CAAC;KAC3B,CAAC;IACF,OAAO,EAAE;QACP,GAAG,EAAE,MAAM,CAAC;QACZ,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QACtB,QAAQ,EAAE,OAAO,CAAC;KACnB,CAAC;IACF,mBAAmB,EAAE;QACnB,GAAG,EAAE,MAAM,CAAC;QACZ,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QACtB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,gBAAgB,EAAE,OAAO,CAAC;KAC3B,CAAC;IACF,WAAW,EAAE;QACX,SAAS,EAAE,MAAM,EAAE,CAAC;KACrB,CAAC;IACF,SAAS,EAAE;QACT,aAAa,EAAE,OAAO,CAAC;QACvB,WAAW,EAAE,OAAO,CAAC;QACrB,UAAU,EAAE,OAAO,CAAC;QACpB,GAAG,EAAE,OAAO,CAAC;QACb,YAAY,EAAE,OAAO,CAAC;KACvB,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,MAAM,EAAE,UAAU,EAAE,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,qBAAqB,CAAC;IAClC,OAAO,CAAC,EAAE,qBAAqB,CAAC;IAChC,QAAQ,CAAC,EAAE,qBAAqB,CAAC;IACjC,QAAQ,CAAC,EAAE,qBAAqB,CAAC;IACjC,SAAS,CAAC,EAAE;QACV,aAAa,CAAC,EAAE,qBAAqB,CAAC;QACtC,WAAW,CAAC,EAAE,qBAAqB,CAAC;QACpC,UAAU,CAAC,EAAE,qBAAqB,CAAC;QACnC,GAAG,CAAC,EAAE,qBAAqB,CAAC;QAC5B,YAAY,CAAC,EAAE,qBAAqB,CAAC;KACtC,CAAC;CACH,CAAC;AAoDF,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,sBAAsB,GAAG,qBAAqB,CAoJtF;AAmCD,wBAAsB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,SAAS,GAAG,OAAO,CAAC,qBAAqB,CAAC,CA+C7G"}

package/dist/checks/agent-ready.js

@@ -96,31 +96,31 @@ export function analyzeAgentReady(input) {
     };
     const robotsStatus = input.robotsTxt?.status ?? null;
     if (!isSuccessfulStatus(robotsStatus) || !robotsBody.trim()) {
-        issues.push(issue("agent-robots-missing", "warning", "robots.txt is missing or empty; agents cannot discover crawl policy or Content Signals."));
+        issues.push(issue("agent-robots-missing", "warning", "robots.txt is missing or empty; agents cannot discover crawl policy or Content Signals.", "Add a robots.txt at the site root (for example public/robots.txt) with at least `User-agent: *` and a Sitemap line."));
     }
     else {
         if (contentSignals.length === 0) {
-            issues.push(issue("agent-missing-content-signals", "warning", "robots.txt has no Content-Signal directives (ai-train / search / ai-input)."));
+            issues.push(issue("agent-missing-content-signals", "warning", "robots.txt has no Content-Signal directives (ai-train / search / ai-input).", "Add a Content-Signal under `User-agent: *` in robots.txt, for example `Content-Signal: search=yes,ai-train=no`."));
         }
         if (aiBotUserAgents.length === 0) {
-            issues.push(issue("agent-missing-ai-bot-rules", "warning", "robots.txt has no explicit AI bot User-agent rules (e.g. GPTBot, ClaudeBot, Google-Extended)."));
+            issues.push(issue("agent-missing-ai-bot-rules", "warning", "robots.txt has no explicit AI bot User-agent rules (e.g. GPTBot, ClaudeBot, Google-Extended).", "Add explicit `User-agent` blocks for AI crawlers (GPTBot, ClaudeBot, Google-Extended, …) with Allow/Disallow as intended."));
         }
     }
     if (!llmsOk) {
-        issues.push(issue("agent-missing-llms-txt", "warning", "llms.txt is missing or not a plain-text overview at /llms.txt."));
+        issues.push(issue("agent-missing-llms-txt", "warning", "llms.txt is missing or not a plain-text overview at /llms.txt.", "Add /llms.txt as plain text with an H1 title (`# Site Name`) and links to the most important content."));
     }
     else if (!llmsHasTitle) {
-        issues.push(issue("agent-llms-txt-incomplete", "review", "llms.txt exists but has no H1 title line (# Site Name)."));
+        issues.push(issue("agent-llms-txt-incomplete", "review", "llms.txt exists but has no H1 title line (# Site Name).", "Start llms.txt with an H1 line, for example `# Site Name`."));
     }
     if (!markdownOk) {
-        issues.push(issue("agent-missing-markdown-negotiation", "warning", "Homepage does not negotiate Markdown (Accept: text/markdown → Content-Type: text/markdown)."));
+        issues.push(issue("agent-missing-markdown-negotiation", "warning", "Homepage does not negotiate Markdown (Accept: text/markdown → Content-Type: text/markdown).", "When the request has `Accept: text/markdown`, return the page body as Markdown with `Content-Type: text/markdown` (middleware or route)."));
     }
     if (agentLinkRelations.length === 0) {
-        issues.push(issue("agent-missing-link-headers", "review", 'Homepage has no agent-useful Link headers (rel="api-catalog", "service-doc", "service-desc", or "describedby").'));
+        issues.push(issue("agent-missing-link-headers", "review", 'Homepage has no agent-useful Link headers (rel="api-catalog", "service-doc", "service-desc", or "describedby").', 'Add Link response headers on the homepage, for example `Link: </.well-known/api-catalog>; rel="api-catalog"`.'));
     }
     const wellKnownPresent = Object.values(wellKnown).some(Boolean);
     if (!wellKnownPresent) {
-        issues.push(issue("agent-missing-protocol-discovery", "review", "No agent protocol discovery endpoints found (MCP Server Card, Agent Skills, API Catalog, ARD, or A2A Agent Card)."));
+        issues.push(issue("agent-missing-protocol-discovery", "review", "No agent protocol discovery endpoints found (MCP Server Card, Agent Skills, API Catalog, ARD, or A2A Agent Card).", "Add /.well-known/agent-skills/index.json. Use an empty array if no skills are available (`skills: []`)."));
     }
     const findings = {
         robotsTxt: {

package/dist/checks/crawl.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"crawl.d.ts","sourceRoot":"","sources":["../../src/checks/crawl.ts"],"names":[],"mappings":"AAOA,OAAO,EAAuB,KAAK,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAKjF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,YAAY,CAAC,EAAE,GAAG,CAAC,UAAU,CAAC,CAAC;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC;IAC9E,kBAAkB,EAAE,MAAM,CAAC;IAC3B,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,GAAG,CAAC,UAAU,CAAC,CAAC;CAC/B,CAAC,CAyDD;AAED,wBAAsB,aAAa,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAiCzF"}
+{"version":3,"file":"crawl.d.ts","sourceRoot":"","sources":["../../src/checks/crawl.ts"],"names":[],"mappings":"AAOA,OAAO,EAAuB,KAAK,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAMjF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,YAAY,CAAC,EAAE,GAAG,CAAC,UAAU,CAAC,CAAC;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC;IAC9E,kBAAkB,EAAE,MAAM,CAAC;IAC3B,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,GAAG,CAAC,UAAU,CAAC,CAAC;CAC/B,CAAC,CAuED;AAED,wBAAsB,aAAa,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAiCzF"}

package/dist/checks/crawl.js

@@ -2,6 +2,7 @@ import { DEFAULT_BURST_DELAY_MS, DEFAULT_CONCURRENCY, DEFAULT_DELAY_MS, DEFAULT_
 import { resolveActiveGroups } from "../crawler/checkGroups.js";
 import { buildDefaultOutputPaths } from "../crawler/outputPaths.js";
 import { runCrawler } from "../crawler/runCrawler.js";
+import { selectSmartCrawlUrls } from "../crawler/smartPageSelection.js";
 import { collectSitemapPageUrls } from "./sitemap.js";
 import { isHttpUrl, matchesExcludePattern, normalizeUrl } from "../crawler/urlUtils.js";
 export async function prepareCrawlSeedUrls(options) {
@@ -51,6 +52,16 @@ export async function prepareCrawlSeedUrls(options) {
         }
     }
     seedUrls = seedUrls.filter((url) => !matchesExcludePattern(url, excludePatterns));
+    const unlimitedSeedCount = seedUrls.length;
+    const smart = selectSmartCrawlUrls(seedUrls, Math.floor(maxPages), {
+        startUrl: normalizedStartUrl,
+    });
+    seedUrls = smart.urls;
+    if (unlimitedSeedCount > seedUrls.length) {
+        // Intentionally concise: full URL lists stay in sitemap compare / crawl JSON.
+        const listCount = smart.tree.listParents.size;
+        console.info(`[crawl] smart max-pages: selected ${seedUrls.length}/${unlimitedSeedCount} seed URLs (limit=${Math.floor(maxPages)}, listParents=${listCount})`);
+    }
     return { normalizedStartUrl, seedUrls, outputPath, activeGroups };
 }
 export async function runCrawlCheck(options) {

package/dist/checks/dns.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dns.d.ts","sourceRoot":"","sources":["../../src/checks/dns.ts"],"names":[],"mappings":"AAEA,OAAO,EAAS,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAErD,MAAM,MAAM,UAAU,GAAG;IACvB,CAAC,EAAE,MAAM,EAAE,CAAC;IACZ,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,EAAE,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAClD,GAAG,EAAE,MAAM,EAAE,CAAC;IACd,EAAE,EAAE,MAAM,EAAE,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,UAAU,CAAC;IACpB,IAAI,EAAE,cAAc,CAAC;IACrB,MAAM,EAAE,UAAU,EAAE,CAAC;CACtB,CAAC;AA2CF,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAuC9E;AAED,wBAAsB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAE3E"}
+{"version":3,"file":"dns.d.ts","sourceRoot":"","sources":["../../src/checks/dns.ts"],"names":[],"mappings":"AAEA,OAAO,EAAS,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAErD,MAAM,MAAM,UAAU,GAAG;IACvB,CAAC,EAAE,MAAM,EAAE,CAAC;IACZ,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,EAAE,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAClD,GAAG,EAAE,MAAM,EAAE,CAAC;IACd,EAAE,EAAE,MAAM,EAAE,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,UAAU,CAAC;IACpB,IAAI,EAAE,cAAc,CAAC;IACrB,MAAM,EAAE,UAAU,EAAE,CAAC;CACtB,CAAC;AA2CF,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAqD9E;AAED,wBAAsB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAE3E"}

package/dist/checks/dns.js

@@ -56,10 +56,10 @@ export async function analyzeDnsRecords(input) {
     const dmarc = (await resolveDmarc(hostname)) ?? findDmarc(hostname, flatTxt);
     const skipMailAuthIssues = isPlatformPreviewHostname(hostname);
     if (!skipMailAuthIssues && !spf) {
-        issues.push(issue("missing-spf", "warning", "No SPF TXT record found."));
+        issues.push(issue("missing-spf", "warning", "No SPF TXT record found.", `Add a TXT record on ${hostname} starting with \`v=spf1\` that lists your mail senders.`));
     }
     if (!skipMailAuthIssues && !dmarc) {
-        issues.push(issue("missing-dmarc", "warning", "No DMARC TXT record found."));
+        issues.push(issue("missing-dmarc", "warning", "No DMARC TXT record found.", `Add a TXT record on \`_dmarc.${hostname}\` starting with \`v=DMARC1;\` (for example \`p=none; rua=mailto:dmarc@${hostname}\`).`));
     }
     return {
         hostname,

package/dist/checks/issues.d.ts

@@ -3,6 +3,8 @@ export type CheckIssue = {
     id: string;
     severity: CheckIssueSeverity;
     message: string;
+    /** Concrete remediation suggestion for reports / agents. */
+    fix?: string;
 };
-export declare function issue(id: string, severity: CheckIssueSeverity, message: string): CheckIssue;
+export declare function issue(id: string, severity: CheckIssueSeverity, message: string, fix?: string): CheckIssue;
 //# sourceMappingURL=issues.d.ts.map

package/dist/checks/issues.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"issues.d.ts","sourceRoot":"","sources":["../../src/checks/issues.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,kBAAkB,GAAG,UAAU,GAAG,OAAO,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE7E,MAAM,MAAM,UAAU,GAAG;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,kBAAkB,EAAE,OAAO,EAAE,MAAM,GAAG,UAAU,CAE3F"}
+{"version":3,"file":"issues.d.ts","sourceRoot":"","sources":["../../src/checks/issues.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,kBAAkB,GAAG,UAAU,GAAG,OAAO,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE7E,MAAM,MAAM,UAAU,GAAG;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,wBAAgB,KAAK,CACnB,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,EAAE,MAAM,EACf,GAAG,CAAC,EAAE,MAAM,GACX,UAAU,CAEZ"}

package/dist/checks/issues.js

@@ -1,3 +1,3 @@
-export function issue(id, severity, message) {
-    return { id, severity, message };
+export function issue(id, severity, message, fix) {
+    return fix === undefined ? { id, severity, message } : { id, severity, message, fix };
 }

package/dist/checks/redirect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"redirect.d.ts","sourceRoot":"","sources":["../../src/checks/redirect.ts"],"names":[],"mappings":"AAEA,OAAO,EAAS,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAG1C,eAAO,MAAM,qBAAqB,aAAqC,CAAC;AACxE,eAAO,MAAM,+BAA+B,aAAsB,CAAC;AAEnE,MAAM,MAAM,kBAAkB,GAAG;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG,kBAAkB,GAAG;IACrD,UAAU,EAAE,OAAO,CAAC;IACpB,YAAY,EAAE,OAAO,CAAC;IACtB,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,QAAQ,CAAC,EAAE,qBAAqB,CAAC;CAClC,CAAC;AAEF,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAG1D;AAED,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAIzD;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,kBAAkB,EAAE,gBAAgB,CAAC,GAAG,MAAM,CAE/G;AAMD,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAM7D;AAED,eAAO,MAAM,uBAAuB,EAAE,OAAO,EAAuB,CAAC;AAmBrE,wBAAgB,eAAe,CAAC,KAAK,EAAE,kBAAkB,GAAG,mBAAmB,CAyD9E;AAED,wBAAgB,uBAAuB,CACrC,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,IAAI,CAAC,kBAAkB,EAAE,KAAK,GAAG,QAAQ,GAAG,UAAU,GAAG,gBAAgB,GAAG,cAAc,CAAC,GACjG,UAAU,EAAE,CAyEd;AAED,wBAAgB,iBAAiB,CAAC,eAAe,EAAE,OAAO,EAAE,GAAG,OAAO,CAKrE;AAED,wBAAgB,wBAAwB,CACtC,eAAe,EAAE,OAAO,EAAE,EAC1B,QAAQ,EAAE,IAAI,CAAC,mBAAmB,EAAE,cAAc,CAAC,GAClD,OAAO,EAAE,CAWX;AAED,wBAAgB,uBAAuB,CAAC,eAAe,EAAE,OAAO,EAAE,EAAE,eAAe,EAAE,OAAO,EAAE,GAAG,OAAO,EAAE,CAGzG;AA0DD,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,SAAqB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CA8BrH"}
+{"version":3,"file":"redirect.d.ts","sourceRoot":"","sources":["../../src/checks/redirect.ts"],"names":[],"mappings":"AAEA,OAAO,EAAS,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAG1C,eAAO,MAAM,qBAAqB,aAAqC,CAAC;AACxE,eAAO,MAAM,+BAA+B,aAAsB,CAAC;AAEnE,MAAM,MAAM,kBAAkB,GAAG;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG,kBAAkB,GAAG;IACrD,UAAU,EAAE,OAAO,CAAC;IACpB,YAAY,EAAE,OAAO,CAAC;IACtB,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,QAAQ,CAAC,EAAE,qBAAqB,CAAC;CAClC,CAAC;AAEF,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAG1D;AAED,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAIzD;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,kBAAkB,EAAE,gBAAgB,CAAC,GAAG,MAAM,CAE/G;AAMD,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAM7D;AAED,eAAO,MAAM,uBAAuB,EAAE,OAAO,EAAuB,CAAC;AAmBrE,wBAAgB,eAAe,CAAC,KAAK,EAAE,kBAAkB,GAAG,mBAAmB,CA0E9E;AAED,wBAAgB,uBAAuB,CACrC,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,IAAI,CAAC,kBAAkB,EAAE,KAAK,GAAG,QAAQ,GAAG,UAAU,GAAG,gBAAgB,GAAG,cAAc,CAAC,GACjG,UAAU,EAAE,CAgFd;AAED,wBAAgB,iBAAiB,CAAC,eAAe,EAAE,OAAO,EAAE,GAAG,OAAO,CAKrE;AAED,wBAAgB,wBAAwB,CACtC,eAAe,EAAE,OAAO,EAAE,EAC1B,QAAQ,EAAE,IAAI,CAAC,mBAAmB,EAAE,cAAc,CAAC,GAClD,OAAO,EAAE,CAWX;AAED,wBAAgB,uBAAuB,CAAC,eAAe,EAAE,OAAO,EAAE,EAAE,eAAe,EAAE,OAAO,EAAE,GAAG,OAAO,EAAE,CAGzG;AA0DD,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,SAAqB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CA8BrH"}

package/dist/checks/redirect.js

@@ -62,19 +62,19 @@ export function analyzeRedirect(input) {
         };
     }
     if (!input.location) {
-        issues.push(issue("redirect-missing-location", "error", "Redirect response is missing a Location header."));
+        issues.push(issue("redirect-missing-location", "error", "Redirect response is missing a Location header.", "Include a valid Location header on redirect responses pointing at the canonical URL."));
     }
     else if (!input.resolvedTarget) {
-        issues.push(issue("redirect-invalid-location", "error", "Redirect Location header is not a valid URL."));
+        issues.push(issue("redirect-invalid-location", "error", "Redirect Location header is not a valid URL.", "Set Location to an absolute http(s) URL for the redirect target."));
     }
     if (input.status !== null && !PERMANENT_REDIRECT_STATUS_CODES.has(input.status)) {
-        issues.push(issue("redirect-temporary-status", "warning", `Redirect uses status ${input.status}; use 301 or 308 for permanent domain redirects.`));
+        issues.push(issue("redirect-temporary-status", "warning", `Redirect uses status ${input.status}; use 301 or 308 for permanent domain redirects.`, "Change the redirect status to 301 or 308 for permanent domain redirects."));
     }
     if (isHttps && !input.headers["strict-transport-security"]) {
-        issues.push(issue("redirect-missing-hsts", "warning", "Strict-Transport-Security header is missing on the redirect response."));
+        issues.push(issue("redirect-missing-hsts", "warning", "Strict-Transport-Security header is missing on the redirect response.", "Send Strict-Transport-Security on the HTTPS redirect response as well as on final pages."));
     }
     if (input.resolvedTarget && input.targetStatus !== null && input.targetStatus >= 400) {
-        issues.push(issue("redirect-target-unreachable", "error", `Redirect target returned status ${input.targetStatus}: ${input.resolvedTarget}`));
+        issues.push(issue("redirect-target-unreachable", "error", `Redirect target returned status ${input.targetStatus}: ${input.resolvedTarget}`, "Fix the redirect target so it returns a successful response, or point Location at a working URL."));
     }
     return {
         ...input,
@@ -87,27 +87,27 @@ export function analyzeWwwAliasRedirect(canonicalUrl, probe) {
     const issues = [];
     const canonicalHost = hostnameFromUrl(canonicalUrl);
     if (probe.status === null) {
-        issues.push(issue("redirect-www-alias-unreachable", "error", `Alternate host is unreachable and should redirect to ${canonicalHost}: ${probe.url}`));
+        issues.push(issue("redirect-www-alias-unreachable", "error", `Alternate host is unreachable and should redirect to ${canonicalHost}: ${probe.url}`, `Configure DNS and hosting so the alternate host responds and permanently redirects to ${canonicalHost}.`));
         return issues;
     }
     if (!REDIRECT_STATUS_CODES.has(probe.status)) {
-        issues.push(issue("redirect-www-alias-no-redirect", "error", `Alternate host should redirect to ${canonicalHost} but returned status ${probe.status}: ${probe.url}`));
+        issues.push(issue("redirect-www-alias-no-redirect", "error", `Alternate host should redirect to ${canonicalHost} but returned status ${probe.status}: ${probe.url}`, `Configure the alternate host to respond with 301/308 Location pointing at ${canonicalHost}.`));
         return issues;
     }
     if (!probe.location) {
-        issues.push(issue("redirect-www-alias-missing-location", "error", `Alternate host redirect is missing a Location header: ${probe.url}`));
+        issues.push(issue("redirect-www-alias-missing-location", "error", `Alternate host redirect is missing a Location header: ${probe.url}`, `Add a Location header on the alternate-host redirect targeting ${canonicalHost}.`));
     }
     else if (!probe.resolvedTarget) {
-        issues.push(issue("redirect-www-alias-invalid-location", "error", `Alternate host redirect Location header is not a valid URL: ${probe.url}`));
+        issues.push(issue("redirect-www-alias-invalid-location", "error", `Alternate host redirect Location header is not a valid URL: ${probe.url}`, `Set Location to an absolute http(s) URL on ${canonicalHost}.`));
     }
     else if (hostnameFromUrl(probe.resolvedTarget) !== canonicalHost) {
-        issues.push(issue("redirect-www-alias-wrong-target", "error", `Alternate host redirects to ${probe.resolvedTarget} instead of ${canonicalHost}: ${probe.url}`));
+        issues.push(issue("redirect-www-alias-wrong-target", "error", `Alternate host redirects to ${probe.resolvedTarget} instead of ${canonicalHost}: ${probe.url}`, `Point the alternate-host redirect at the canonical hostname (${canonicalHost}).`));
     }
     if (probe.status !== null && !PERMANENT_REDIRECT_STATUS_CODES.has(probe.status)) {
-        issues.push(issue("redirect-www-alias-temporary-status", "warning", `Alternate host redirect uses status ${probe.status}; use 301 or 308 for permanent domain redirects: ${probe.url}`));
+        issues.push(issue("redirect-www-alias-temporary-status", "warning", `Alternate host redirect uses status ${probe.status}; use 301 or 308 for permanent domain redirects: ${probe.url}`, "Change the alternate-host redirect status to 301 or 308."));
     }
     if (probe.resolvedTarget && probe.targetStatus !== null && probe.targetStatus >= 400) {
-        issues.push(issue("redirect-www-alias-target-unreachable", "error", `Alternate host redirect target returned status ${probe.targetStatus}: ${probe.resolvedTarget}`));
+        issues.push(issue("redirect-www-alias-target-unreachable", "error", `Alternate host redirect target returned status ${probe.targetStatus}: ${probe.resolvedTarget}`, "Fix the canonical target URL so the alternate-host redirect lands on a successful page."));
     }
     return issues;
 }

package/dist/checks/robots-txt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"robots-txt.d.ts","sourceRoot":"","sources":["../../src/checks/robots-txt.ts"],"names":[],"mappings":"AACA,OAAO,EAAS,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAGrD,MAAM,MAAM,qBAAqB,GAAG;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,MAAM,EAAE,UAAU,EAAE,CAAC;CACtB,CAAC;AAgDF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,qBAAqB,GAAG,oBAAoB,CA2CnF;AAED,wBAAsB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,SAAS,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAmB3G"}
+{"version":3,"file":"robots-txt.d.ts","sourceRoot":"","sources":["../../src/checks/robots-txt.ts"],"names":[],"mappings":"AACA,OAAO,EAAS,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAGrD,MAAM,MAAM,qBAAqB,GAAG;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,MAAM,EAAE,UAAU,EAAE,CAAC;CACtB,CAAC;AAgDF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,qBAAqB,GAAG,oBAAoB,CAqFnF;AAED,wBAAsB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,SAAS,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAmB3G"}

package/dist/checks/robots-txt.js

@@ -47,15 +47,15 @@ export function analyzeRobotsTxt(input) {
     const issues = [];
     const { url, status, body } = input;
     if (status === null || status === 404) {
-        issues.push(issue("robots-missing", "warning", "robots.txt is missing."));
+        issues.push(issue("robots-missing", "warning", "robots.txt is missing.", "Publish /robots.txt at the site origin with at least `User-agent: *` and a Sitemap directive."));
         return { url, status, body, sitemapUrls: [], issues };
     }
     if (!body) {
-        issues.push(issue("robots-unparseable", "error", "robots.txt response body is empty."));
+        issues.push(issue("robots-unparseable", "error", "robots.txt response body is empty.", "Return a non-empty robots.txt body with valid User-agent / Allow / Disallow / Sitemap lines."));
         return { url, status, body, sitemapUrls: [], issues };
     }
     if (hasMalformedRobotsLines(body)) {
-        issues.push(issue("robots-unparseable", "error", "robots.txt contains malformed directives."));
+        issues.push(issue("robots-unparseable", "error", "robots.txt contains malformed directives.", "Fix robots.txt syntax: one directive per line (`User-agent:`, `Allow:`, `Disallow:`, `Sitemap:`)."));
     }
     let sitemapUrls = [];
     try {
@@ -64,17 +64,17 @@ export function analyzeRobotsTxt(input) {
         sitemapUrls = parsed.getSitemaps();
     }
     catch {
-        issues.push(issue("robots-unparseable", "error", "robots.txt could not be parsed."));
+        issues.push(issue("robots-unparseable", "error", "robots.txt could not be parsed.", "Validate robots.txt content and encoding; ensure it is plain text with standard directives."));
         return { url, status, body, sitemapUrls: [], issues };
     }
     if (sitemapUrls.length === 0) {
         sitemapUrls = extractSitemapUrls(body);
     }
     if (blocksAllUserAgents(body, url)) {
-        issues.push(issue("robots-blocks-all", "critical", "robots.txt disallows all crawling for User-agent: *."));
+        issues.push(issue("robots-blocks-all", "critical", "robots.txt disallows all crawling for User-agent: *.", "Remove or narrow `Disallow: /` under `User-agent: *` so search engines and agents can crawl public pages."));
     }
     if (sitemapUrls.length === 0) {
-        issues.push(issue("robots-missing-sitemap", "warning", "robots.txt has no Sitemap directive."));
+        issues.push(issue("robots-missing-sitemap", "warning", "robots.txt has no Sitemap directive.", "Add a Sitemap line pointing at your sitemap, for example `Sitemap: https://example.com/sitemap.xml`."));
     }
     return { url, status, body, sitemapUrls, issues };
 }

package/dist/checks/security-headers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"security-headers.d.ts","sourceRoot":"","sources":["../../src/checks/security-headers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAErD,MAAM,MAAM,6BAA6B,GAAG;IAC1C,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAWF,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE,6BAAkC,GAC1C,UAAU,EAAE,CA0Cd;AAED,MAAM,MAAM,0BAA0B,GAAG;IACvC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,MAAM,EAAE,UAAU,EAAE,CAAC;CACtB,CAAC;AAEF,wBAAsB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAgBnG"}
+{"version":3,"file":"security-headers.d.ts","sourceRoot":"","sources":["../../src/checks/security-headers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAErD,MAAM,MAAM,6BAA6B,GAAG;IAC1C,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAWF,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE,6BAAkC,GAC1C,UAAU,EAAE,CA8Ed;AAED,MAAM,MAAM,0BAA0B,GAAG;IACvC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,MAAM,EAAE,UAAU,EAAE,CAAC;CACtB,CAAC;AAEF,wBAAsB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAgBnG"}

package/dist/checks/security-headers.js

@@ -17,22 +17,22 @@ export function analyzeSecurityHeaders(headers, options = {}) {
     const referrerPolicy = headerValue(headers, "referrer-policy");
     const permissionsPolicy = headerValue(headers, "permissions-policy");
     if (isHttps && !hsts) {
-        issues.push(issue("missing-hsts", "error", "Strict-Transport-Security header is missing on HTTPS."));
+        issues.push(issue("missing-hsts", "error", "Strict-Transport-Security header is missing on HTTPS.", "Send `Strict-Transport-Security: max-age=31536000; includeSubDomains` on HTTPS responses (hosting or app headers)."));
     }
     if (!csp) {
-        issues.push(issue("missing-csp", "warning", "Content-Security-Policy header is missing."));
+        issues.push(issue("missing-csp", "warning", "Content-Security-Policy header is missing.", "Add a Content-Security-Policy header tailored to your app (start with report-only if needed)."));
     }
     if (!xFrameOptions && !hasFrameAncestorsCsp(csp)) {
-        issues.push(issue("missing-clickjacking-protection", "warning", "Neither X-Frame-Options nor CSP frame-ancestors is set."));
+        issues.push(issue("missing-clickjacking-protection", "warning", "Neither X-Frame-Options nor CSP frame-ancestors is set.", "Set `X-Frame-Options: DENY` (or SAMEORIGIN) or add `frame-ancestors` to your Content-Security-Policy."));
     }
     if (!nosniff || nosniff.toLowerCase() !== "nosniff") {
-        issues.push(issue("missing-nosniff", "warning", "X-Content-Type-Options: nosniff is missing."));
+        issues.push(issue("missing-nosniff", "warning", "X-Content-Type-Options: nosniff is missing.", "Send `X-Content-Type-Options: nosniff` on all responses."));
     }
     if (!referrerPolicy) {
-        issues.push(issue("missing-referrer-policy", "review", "Referrer-Policy header is missing."));
+        issues.push(issue("missing-referrer-policy", "review", "Referrer-Policy header is missing.", "Send a Referrer-Policy such as `strict-origin-when-cross-origin`."));
     }
     if (!permissionsPolicy) {
-        issues.push(issue("missing-permissions-policy", "review", "Permissions-Policy header is missing."));
+        issues.push(issue("missing-permissions-policy", "review", "Permissions-Policy header is missing.", "Add a Permissions-Policy header that disables unused browser features (camera, mic, geolocation, …)."));
     }
     return issues;
 }

package/dist/checks/sitemap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sitemap.d.ts","sourceRoot":"","sources":["../../src/checks/sitemap.ts"],"names":[],"mappings":"AAGA,OAAO,EAAS,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAMrD,MAAM,MAAM,mBAAmB,GAAG;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,OAAO,EAAE,mBAAmB,EAAE,CAAC;IAC/B,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,UAAU,EAAE,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,0BAA0B,GAAG;IACvC,OAAO,EAAE,mBAAmB,EAAE,CAAC;IAC/B,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CAC5B,CAAC;AAQF,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,0BAA0B,GAAG,kBAAkB,CA6G3F;AAED,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,MAAM,EAAE,iBAAiB,GAAE,MAAM,EAAO,GAAG,MAAM,EAAE,CAIpG;AAkBD,wBAAsB,kBAAkB,CACtC,aAAa,EAAE,MAAM,EAAE,EACvB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAchC;AAED,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG,IAAI,CACpC,sBAAsB,EACtB,WAAW,GAAG,0BAA0B,GAAG,iBAAiB,CAC7D,CAAC;AAEF,wBAAsB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAYlG;AAED,wBAAsB,sBAAsB,CAC1C,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,iBAAiB,GAAE,MAAM,EAAO,EAChC,gBAAgB,CAAC,EAAE,MAAM,GACxB,OAAO,CAAC,MAAM,EAAE,CAAC,CAmBnB"}
+{"version":3,"file":"sitemap.d.ts","sourceRoot":"","sources":["../../src/checks/sitemap.ts"],"names":[],"mappings":"AAGA,OAAO,EAAS,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAMrD,MAAM,MAAM,mBAAmB,GAAG;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,OAAO,EAAE,mBAAmB,EAAE,CAAC;IAC/B,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,UAAU,EAAE,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,0BAA0B,GAAG;IACvC,OAAO,EAAE,mBAAmB,EAAE,CAAC;IAC/B,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CAC5B,CAAC;AAQF,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,0BAA0B,GAAG,kBAAkB,CAyH3F;AAED,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,MAAM,EAAE,iBAAiB,GAAE,MAAM,EAAO,GAAG,MAAM,EAAE,CAIpG;AAkBD,wBAAsB,kBAAkB,CACtC,aAAa,EAAE,MAAM,EAAE,EACvB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAchC;AAED,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG,IAAI,CACpC,sBAAsB,EACtB,WAAW,GAAG,0BAA0B,GAAG,iBAAiB,CAC7D,CAAC;AAEF,wBAAsB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAYlG;AAED,wBAAsB,sBAAsB,CAC1C,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,iBAAiB,GAAE,MAAM,EAAO,EAChC,gBAAgB,CAAC,EAAE,MAAM,GACxB,OAAO,CAAC,MAAM,EAAE,CAAC,CAmBnB"}

package/dist/checks/sitemap.js

@@ -16,12 +16,12 @@ export function analyzeSitemapCompare(input) {
     const issues = [];
     for (const source of input.sources) {
         if (source.status === null || source.status >= 400) {
-            issues.push(issue("sitemap-unreachable", "error", `Sitemap not reachable: ${source.url} (${source.status ?? "unreachable"}).`));
+            issues.push(issue("sitemap-unreachable", "error", `Sitemap not reachable: ${source.url} (${source.status ?? "unreachable"}).`, `Ensure ${source.url} returns HTTP 200 with a valid XML sitemap or sitemap index.`));
         }
     }
     const successfulSources = input.sources.filter((source) => source.status !== null && source.status >= 200 && source.status < 300);
     if (successfulSources.length === 0) {
-        issues.push(issue("sitemap-missing", "error", "No sitemap found."));
+        issues.push(issue("sitemap-missing", "error", "No sitemap found.", "Publish /sitemap.xml (or reference it from robots.txt) and make sure it returns HTTP 200."));
         return {
             sources: input.sources,
             sitemapPageUrls: [],
@@ -35,7 +35,7 @@ export function analyzeSitemapCompare(input) {
     const sitemapPageUrls = filterComparableUrls(successfulSources.flatMap((source) => source.pageUrls), excludePatterns);
     const crawledUrls = filterComparableUrls(input.crawledUrls, excludePatterns);
     if (sitemapPageUrls.length === 0) {
-        issues.push(issue("sitemap-empty", "error", "Sitemap was reachable but contained no page URLs (check sitemap index nesting and host aliases such as apex vs www)."));
+        issues.push(issue("sitemap-empty", "error", "Sitemap was reachable but contained no page URLs (check sitemap index nesting and host aliases such as apex vs www).", "Populate the sitemap with page `<loc>` entries, or fix nested sitemap indexes and apex/www host mismatches."));
         return {
             sources: input.sources,
             sitemapPageUrls,
@@ -51,17 +51,17 @@ export function analyzeSitemapCompare(input) {
     const inSitemapNotCrawled = sitemapPageUrls.filter((url) => !crawledSet.has(url));
     const crawledNotInSitemap = crawledUrls.filter((url) => !sitemapSet.has(url));
     if (inSitemapNotCrawled.length > 0) {
-        issues.push(issue("sitemap-url-not-crawled", "critical", `${inSitemapNotCrawled.length} sitemap URL(s) were not crawled. ${SITEMAP_URL_NOT_CRAWLED_TIP}`));
+        issues.push(issue("sitemap-url-not-crawled", "critical", `${inSitemapNotCrawled.length} sitemap URL(s) were not crawled. ${SITEMAP_URL_NOT_CRAWLED_TIP}`, "Remove stale sitemap entries, fix robots blocks, or raise --max-pages so listed URLs can be crawled."));
     }
     if (crawledNotInSitemap.length > 0) {
-        issues.push(issue("sitemap-missing-crawled-url", "critical", `${crawledNotInSitemap.length} crawled URL(s) are missing from the sitemap.`));
+        issues.push(issue("sitemap-missing-crawled-url", "critical", `${crawledNotInSitemap.length} crawled URL(s) are missing from the sitemap.`, "Add the crawled URLs to the sitemap (or regenerate the sitemap from the live route set)."));
     }
     const total = new Set([...sitemapPageUrls, ...crawledUrls]).size;
     const mismatchCount = new Set([...inSitemapNotCrawled, ...crawledNotInSitemap]).size;
     const mismatchPercent = total === 0 ? 0 : (mismatchCount / total) * 100;
     if (mismatchPercent > threshold) {
         issues.push(issue("sitemap-mismatch-threshold", "critical", `Sitemap mismatch is ${mismatchPercent.toFixed(1)}% (threshold ${threshold}%). ` +
-            "Sitemap URLs must match crawled URLs exactly, including hostname."));
+            "Sitemap URLs must match crawled URLs exactly, including hostname.", "Align sitemap hostnames and paths with the live site (apex vs www) and regenerate the sitemap."));
     }
     return {
         sources: input.sources,

package/dist/cli.js

@@ -26,7 +26,7 @@ async function main() {
         .option("--errors-only", "Include only critical/error findings in the Markdown report", false)
         .option("--parallel", "Run independent checks in parallel", false)
         .option("--checks <ids>", "Comma-separated checks to run (crawl,analyze,lighthouse,security-headers,dns,robots-txt,sitemap,agent-ready)")
-        .option("--max-pages <n>", "Maximum number of pages", String(DEFAULT_MAX_PAGES))
+        .option("--max-pages <n>", "Maximum pages to crawl (default 100; prefers structural pages, samples leaf URLs under large list branches)", String(DEFAULT_MAX_PAGES))
         .option("--delay-ms <n>", "Delay between requests in ms", String(DEFAULT_DELAY_MS))
         .option("--timeout-ms <n>", "Request timeout in ms", String(DEFAULT_TIMEOUT_MS))
         .option("--concurrency <n>", "Maximum concurrent requests", String(DEFAULT_CONCURRENCY))

package/dist/crawler/defaults.d.ts

@@ -1,4 +1,5 @@
-export declare const DEFAULT_MAX_PAGES = 1000;
+/** Default crawl budget; smart selection prefers root/list pages within this cap. */
+export declare const DEFAULT_MAX_PAGES = 100;
 export declare const DEFAULT_DELAY_MS = 500;
 export declare const DEFAULT_TIMEOUT_MS = 10000;
 export declare const DEFAULT_CONCURRENCY = 1;

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

@@ -1 +1 @@
-{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../../src/crawler/defaults.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,iBAAiB,OAAO,CAAC;AACtC,eAAO,MAAM,gBAAgB,MAAM,CAAC;AACpC,eAAO,MAAM,kBAAkB,QAAQ,CAAC;AACxC,eAAO,MAAM,mBAAmB,IAAI,CAAC;AACrC,eAAO,MAAM,sBAAsB,IAAI,CAAC;AACxC,eAAO,MAAM,kBAAkB,kBAAkB,CAAC;AAClD,eAAO,MAAM,0BAA0B,iBAAiB,CAAC;AACzD,eAAO,MAAM,oBAAoB,KAAK,CAAC;AACvC,eAAO,MAAM,wBAAwB,QAAQ,CAAC;AAC9C,eAAO,MAAM,kBAAkB,2CAA2C,CAAC"}
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../../src/crawler/defaults.ts"],"names":[],"mappings":"AAAA,qFAAqF;AACrF,eAAO,MAAM,iBAAiB,MAAM,CAAC;AACrC,eAAO,MAAM,gBAAgB,MAAM,CAAC;AACpC,eAAO,MAAM,kBAAkB,QAAQ,CAAC;AACxC,eAAO,MAAM,mBAAmB,IAAI,CAAC;AACrC,eAAO,MAAM,sBAAsB,IAAI,CAAC;AACxC,eAAO,MAAM,kBAAkB,kBAAkB,CAAC;AAClD,eAAO,MAAM,0BAA0B,iBAAiB,CAAC;AACzD,eAAO,MAAM,oBAAoB,KAAK,CAAC;AACvC,eAAO,MAAM,wBAAwB,QAAQ,CAAC;AAC9C,eAAO,MAAM,kBAAkB,2CAA2C,CAAC"}

package/dist/crawler/defaults.js

@@ -1,4 +1,5 @@
-export const DEFAULT_MAX_PAGES = 1000;
+/** Default crawl budget; smart selection prefers root/list pages within this cap. */
+export const DEFAULT_MAX_PAGES = 100;
 export const DEFAULT_DELAY_MS = 500;
 export const DEFAULT_TIMEOUT_MS = 10000;
 export const DEFAULT_CONCURRENCY = 1;

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

@@ -1 +1 @@
-{"version":3,"file":"runCrawler.d.ts","sourceRoot":"","sources":["../../src/crawler/runCrawler.ts"],"names":[],"mappings":"AAUA,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAOjE,OAAO,KAAK,EAAiB,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAKrE,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,YAAY,CAAC,EAAE,GAAG,CAAC,UAAU,CAAC,CAAC;IAC/B,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,wBAAsB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAAC,WAAW,EAAE,OAAO,CAAA;CAAE,CAAC,CAqK7H"}
+{"version":3,"file":"runCrawler.d.ts","sourceRoot":"","sources":["../../src/crawler/runCrawler.ts"],"names":[],"mappings":"AAUA,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAOjE,OAAO,KAAK,EAAiB,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAMrE,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,YAAY,CAAC,EAAE,GAAG,CAAC,UAAU,CAAC,CAAC;IAC/B,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,wBAAsB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAAC,WAAW,EAAE,OAAO,CAAA;CAAE,CAAC,CA4K7H"}

package/dist/crawler/runCrawler.js

@@ -8,6 +8,7 @@ import { extractSameOriginScripts } from "./jsAssets.js";
 import { loadRobotsPolicy } from "./robots.js";
 import { writeReportToFile } from "./reporter.js";
 import { scanText } from "./secrets.js";
+import { createDiscoveryGate } from "./smartPageSelection.js";
 import { matchesExcludePattern, normalizeUrl, sleep } from "./urlUtils.js";
 const MAX_JS_ASSET_BYTES = 5_000_000; // 5 MB — skip larger bundles to bound memory
 export async function runCrawler(options) {
@@ -84,10 +85,14 @@ export async function runCrawler(options) {
     const requestQueue = await RequestQueue.open();
     const records = [];
     const seen = new Set();
+    const discovery = createDiscoveryGate(seedUrls, maxPages);
+    // Seeds are already smart-ordered (home/root/list before details); FIFO preserves that.
     for (const seed of seedUrls) {
         if (!matchesExcludePattern(seed, excludePatterns)) {
-            await requestQueue.addRequest({ url: seed, uniqueKey: normalizeUrl(seed) });
-            seen.add(normalizeUrl(seed));
+            const normalized = normalizeUrl(seed);
+            await requestQueue.addRequest({ url: seed, uniqueKey: normalized });
+            seen.add(normalized);
+            discovery.remember(normalized);
         }
     }
     let processedSinceBurst = 0;
@@ -151,8 +156,12 @@ export async function runCrawler(options) {
                         continue;
                     if (robotsPolicy && !robotsPolicy.isAllowed(normalized))
                         continue;
+                    if (!discovery.allowEnqueue(normalized))
+                        continue;
                     seen.add(normalized);
-                    await requestQueue.addRequest({ url: normalized, uniqueKey: normalized });
+                    discovery.remember(normalized);
+                    const forefront = discovery.isStructural(normalized);
+                    await requestQueue.addRequest({ url: normalized, uniqueKey: normalized }, { forefront });
                 }
             }
         },

package/dist/crawler/smartPageSelection.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Smart crawl URL selection based on URL-tree shape (not slug names).
+ *
+ * A "list" parent is a path with many direct children that are mostly leaves
+ * (no further subpages) — typical for archives like news/events/blog, whatever
+ * they are named. Within --max-pages we keep structural pages and sample
+ * leaves under each list parent.
+ */
+export type UrlKind = "home" | "root" | "list" | "detail" | "other";
+export type ClassifiedUrl = {
+    url: string;
+    kind: UrlKind;
+    /** Pathname of the list parent when kind is list/detail, e.g. "/stories". */
+    section: string | null;
+    /** Sort priority (higher = sooner). */
+    priority: number;
+};
+export type UrlTreeAnalysis = {
+    /** Pathnames that look like list indexes (many leaf children). */
+    listParents: ReadonlySet<string>;
+    /** Origin used to rebuild URLs from pathnames when needed. */
+    origin: string;
+};
+/** Minimum direct leaf children before a path is treated as a list parent. */
+export declare const DEFAULT_LIST_MIN_CHILDREN = 8;
+/** Share of direct children that must be leaves to count as a list. */
+export declare const DEFAULT_LIST_LEAF_RATIO = 0.7;
+export declare function pathSegments(urlOrPath: string): string[];
+export declare function pathnameOf(urlString: string): string;
+/** Parent pathname: `/a/b` → `/a`, `/a` → `/`, `/` → null. */
+export declare function parentPathname(pathname: string): string | null;
+/**
+ * Build parent → direct children maps from a URL set and detect list parents:
+ * paths with many children that are mostly leaves (no further children in the set).
+ */
+export declare function analyzeUrlTree(urls: string[], options?: {
+    startUrl?: string;
+    listMinChildren?: number;
+    listLeafRatio?: number;
+}): UrlTreeAnalysis;
+/** Closest list-parent pathname for this path, or null. */
+export declare function listParentForPathname(pathname: string, listParents: ReadonlySet<string>): string | null;
+export declare function classifyCrawlUrl(urlString: string, tree: UrlTreeAnalysis): ClassifiedUrl;
+export declare function crawlRequestPriority(urlString: string, tree: UrlTreeAnalysis): number;
+/**
+ * Soft per-list-parent cap for detail URLs discovered during a crawl.
+ * Structural pages (home/root/list) are never capped this way.
+ */
+export declare function detailCapPerSection(maxPages: number, listParentCount?: number): number;
+/**
+ * Pick up to `maxPages` URLs using URL-tree shape: keep home/root/list pages,
+ * then round-robin a sample of leaf details under each detected list parent.
+ */
+export declare function selectSmartCrawlUrls(urls: string[], maxPages: number, options?: {
+    startUrl?: string;
+    listMinChildren?: number;
+    listLeafRatio?: number;
+}): {
+    urls: string[];
+    tree: UrlTreeAnalysis;
+};
+/** Sort URLs by crawl priority (desc), stable for equal priority. */
+export declare function sortByCrawlPriority(urls: string[], tree: UrlTreeAnalysis): string[];
+/**
+ * Tracks list parents during a live crawl: uses seed analysis up front, and
+ * promotes parents to "list" when enough leaf-like children are observed.
+ */
+export declare function createDiscoveryGate(seedUrls: string[], maxPages: number, options?: {
+    listMinChildren?: number;
+    listLeafRatio?: number;
+}): {
+    tree: UrlTreeAnalysis;
+    allowEnqueue: (url: string) => boolean;
+    remember: (url: string) => void;
+    isStructural: (url: string) => boolean;
+};
+//# sourceMappingURL=smartPageSelection.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"smartPageSelection.d.ts","sourceRoot":"","sources":["../../src/crawler/smartPageSelection.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEpE,MAAM,MAAM,aAAa,GAAG;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,OAAO,CAAC;IACd,6EAA6E;IAC7E,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,uCAAuC;IACvC,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,kEAAkE;IAClE,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACjC,8DAA8D;IAC9D,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,8EAA8E;AAC9E,eAAO,MAAM,yBAAyB,IAAI,CAAC;AAE3C,uEAAuE;AACvE,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAU3C,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAOxD;AAED,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAQpD;AAED,8DAA8D;AAC9D,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAK9D;AA2BD;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,CAAC,EAAE;IACR,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,GACA,eAAe,CA2CjB;AAED,2DAA2D;AAC3D,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,GAC/B,MAAM,GAAG,IAAI,CAOf;AAED,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,GAAG,aAAa,CAsBxF;AAED,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,GAAG,MAAM,CAErF;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,eAAe,SAAI,GAAG,MAAM,CAIjF;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EAAE,EACd,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE;IACR,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,GACA;IAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,IAAI,EAAE,eAAe,CAAA;CAAE,CAmE3C;AAED,qEAAqE;AACrE,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,eAAe,GAAG,MAAM,EAAE,CAKnF;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAAE,EAClB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE;IAAE,eAAe,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7D;IACD,IAAI,EAAE,eAAe,CAAC;IACtB,YAAY,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACvC,QAAQ,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,YAAY,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;CACxC,CAqEA"}

package/dist/crawler/smartPageSelection.js

@@ -0,0 +1,308 @@
+/**
+ * Smart crawl URL selection based on URL-tree shape (not slug names).
+ *
+ * A "list" parent is a path with many direct children that are mostly leaves
+ * (no further subpages) — typical for archives like news/events/blog, whatever
+ * they are named. Within --max-pages we keep structural pages and sample
+ * leaves under each list parent.
+ */
+/** Minimum direct leaf children before a path is treated as a list parent. */
+export const DEFAULT_LIST_MIN_CHILDREN = 8;
+/** Share of direct children that must be leaves to count as a list. */
+export const DEFAULT_LIST_LEAF_RATIO = 0.7;
+const PRIORITY = {
+    home: 100,
+    root: 80,
+    list: 60,
+    detail: 40,
+    other: 20,
+};
+export function pathSegments(urlOrPath) {
+    try {
+        const pathname = urlOrPath.includes("://") ? new URL(urlOrPath).pathname : urlOrPath;
+        return pathname.split("/").filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+}
+export function pathnameOf(urlString) {
+    try {
+        const pathname = new URL(urlString).pathname;
+        if (!pathname || pathname === "")
+            return "/";
+        return pathname.length > 1 && pathname.endsWith("/") ? pathname.slice(0, -1) : pathname;
+    }
+    catch {
+        return "/";
+    }
+}
+/** Parent pathname: `/a/b` → `/a`, `/a` → `/`, `/` → null. */
+export function parentPathname(pathname) {
+    if (pathname === "/" || pathname === "")
+        return null;
+    const segments = pathname.split("/").filter(Boolean);
+    if (segments.length <= 1)
+        return "/";
+    return `/${segments.slice(0, -1).join("/")}`;
+}
+function originOf(urls, startUrl) {
+    const candidate = startUrl ?? urls[0];
+    if (!candidate)
+        return "https://example.com";
+    try {
+        return new URL(candidate).origin;
+    }
+    catch {
+        return "https://example.com";
+    }
+}
+function uniqueUrls(urls, startUrl) {
+    const seen = new Set();
+    const unique = [];
+    if (startUrl) {
+        unique.push(startUrl);
+        seen.add(startUrl);
+    }
+    for (const url of urls) {
+        if (seen.has(url))
+            continue;
+        seen.add(url);
+        unique.push(url);
+    }
+    return unique;
+}
+/**
+ * Build parent → direct children maps from a URL set and detect list parents:
+ * paths with many children that are mostly leaves (no further children in the set).
+ */
+export function analyzeUrlTree(urls, options) {
+    const minChildren = options?.listMinChildren ?? DEFAULT_LIST_MIN_CHILDREN;
+    const leafRatio = options?.listLeafRatio ?? DEFAULT_LIST_LEAF_RATIO;
+    const unique = uniqueUrls(urls, options?.startUrl);
+    const origin = originOf(unique, options?.startUrl);
+    const childrenOf = new Map();
+    const pathnames = new Set();
+    for (const url of unique) {
+        const pathname = pathnameOf(url);
+        pathnames.add(pathname);
+        let child = pathname;
+        let parent = parentPathname(child);
+        while (parent !== null) {
+            let bucket = childrenOf.get(parent);
+            if (!bucket) {
+                bucket = new Set();
+                childrenOf.set(parent, bucket);
+            }
+            bucket.add(child);
+            child = parent;
+            parent = parentPathname(child);
+        }
+    }
+    const isLeaf = (pathname) => {
+        const kids = childrenOf.get(pathname);
+        return !kids || kids.size === 0;
+    };
+    const listParents = new Set();
+    for (const [parent, children] of childrenOf) {
+        if (parent === "/")
+            continue; // home fan-out is structural, not an archive list
+        const childList = [...children];
+        if (childList.length < minChildren)
+            continue;
+        const leafCount = childList.filter((child) => isLeaf(child)).length;
+        if (leafCount >= minChildren && leafCount / childList.length >= leafRatio) {
+            listParents.add(parent);
+        }
+    }
+    return { listParents, origin };
+}
+/** Closest list-parent pathname for this path, or null. */
+export function listParentForPathname(pathname, listParents) {
+    let current = parentPathname(pathname);
+    while (current !== null) {
+        if (listParents.has(current))
+            return current;
+        current = parentPathname(current);
+    }
+    return null;
+}
+export function classifyCrawlUrl(urlString, tree) {
+    const pathname = pathnameOf(urlString);
+    if (pathname === "/") {
+        return { url: urlString, kind: "home", section: null, priority: PRIORITY.home };
+    }
+    if (tree.listParents.has(pathname)) {
+        return { url: urlString, kind: "list", section: pathname, priority: PRIORITY.list };
+    }
+    const listParent = listParentForPathname(pathname, tree.listParents);
+    if (listParent) {
+        return { url: urlString, kind: "detail", section: listParent, priority: PRIORITY.detail };
+    }
+    const depth = pathSegments(pathname).length;
+    if (depth <= 2) {
+        return { url: urlString, kind: "root", section: null, priority: PRIORITY.root - (depth - 1) * 5 };
+    }
+    return { url: urlString, kind: "other", section: null, priority: PRIORITY.other };
+}
+export function crawlRequestPriority(urlString, tree) {
+    return classifyCrawlUrl(urlString, tree).priority;
+}
+/**
+ * Soft per-list-parent cap for detail URLs discovered during a crawl.
+ * Structural pages (home/root/list) are never capped this way.
+ */
+export function detailCapPerSection(maxPages, listParentCount = 8) {
+    const detailBudget = Math.max(8, Math.floor(maxPages * 0.5));
+    const sections = Math.max(1, listParentCount);
+    return Math.max(2, Math.floor(detailBudget / Math.min(sections, 8)));
+}
+/**
+ * Pick up to `maxPages` URLs using URL-tree shape: keep home/root/list pages,
+ * then round-robin a sample of leaf details under each detected list parent.
+ */
+export function selectSmartCrawlUrls(urls, maxPages, options) {
+    if (!Number.isFinite(maxPages) || maxPages <= 0) {
+        return { urls: [], tree: analyzeUrlTree([], options) };
+    }
+    const limit = Math.floor(maxPages);
+    const unique = uniqueUrls(urls, options?.startUrl);
+    const tree = analyzeUrlTree(unique, options);
+    if (unique.length <= limit) {
+        return { urls: sortByCrawlPriority(unique, tree), tree };
+    }
+    const classified = unique.map((url) => classifyCrawlUrl(url, tree));
+    const home = [];
+    const roots = [];
+    const lists = [];
+    const others = [];
+    const detailsBySection = new Map();
+    for (const item of classified) {
+        if (item.kind === "home")
+            home.push(item);
+        else if (item.kind === "root")
+            roots.push(item);
+        else if (item.kind === "list")
+            lists.push(item);
+        else if (item.kind === "detail") {
+            const key = item.section ?? "_";
+            const bucket = detailsBySection.get(key) ?? [];
+            bucket.push(item);
+            detailsBySection.set(key, bucket);
+        }
+        else
+            others.push(item);
+    }
+    const selected = [];
+    const selectedSet = new Set();
+    const take = (items) => {
+        for (const item of items) {
+            if (selected.length >= limit)
+                return;
+            if (selectedSet.has(item.url))
+                continue;
+            selected.push(item.url);
+            selectedSet.add(item.url);
+        }
+    };
+    take(home);
+    take(roots);
+    take(lists);
+    const sectionQueues = [...detailsBySection.values()].map((bucket) => [...bucket]);
+    let progress = true;
+    while (selected.length < limit && progress) {
+        progress = false;
+        for (const queue of sectionQueues) {
+            if (selected.length >= limit)
+                break;
+            while (queue.length > 0) {
+                const next = queue.shift();
+                if (selectedSet.has(next.url))
+                    continue;
+                selected.push(next.url);
+                selectedSet.add(next.url);
+                progress = true;
+                break;
+            }
+        }
+    }
+    take(others);
+    return { urls: selected, tree };
+}
+/** Sort URLs by crawl priority (desc), stable for equal priority. */
+export function sortByCrawlPriority(urls, tree) {
+    return urls
+        .map((url, index) => ({ url, index, priority: crawlRequestPriority(url, tree) }))
+        .sort((a, b) => b.priority - a.priority || a.index - b.index)
+        .map((row) => row.url);
+}
+/**
+ * Tracks list parents during a live crawl: uses seed analysis up front, and
+ * promotes parents to "list" when enough leaf-like children are observed.
+ */
+export function createDiscoveryGate(seedUrls, maxPages, options) {
+    const minChildren = options?.listMinChildren ?? DEFAULT_LIST_MIN_CHILDREN;
+    const leafRatio = options?.listLeafRatio ?? DEFAULT_LIST_LEAF_RATIO;
+    const tree = analyzeUrlTree(seedUrls, options);
+    const listParents = new Set(tree.listParents);
+    const childrenOf = new Map();
+    const known = new Set();
+    const detailCounts = new Map();
+    const register = (url) => {
+        const pathname = pathnameOf(url);
+        if (known.has(pathname))
+            return;
+        known.add(pathname);
+        let child = pathname;
+        let parent = parentPathname(child);
+        while (parent !== null) {
+            let bucket = childrenOf.get(parent);
+            if (!bucket) {
+                bucket = new Set();
+                childrenOf.set(parent, bucket);
+            }
+            bucket.add(child);
+            if (parent !== "/") {
+                const childList = [...bucket];
+                if (childList.length >= minChildren) {
+                    const leafCount = childList.filter((c) => {
+                        const grand = childrenOf.get(c);
+                        return !grand || grand.size === 0;
+                    }).length;
+                    if (leafCount >= minChildren && leafCount / childList.length >= leafRatio) {
+                        listParents.add(parent);
+                    }
+                }
+            }
+            child = parent;
+            parent = parentPathname(child);
+        }
+    };
+    for (const seed of seedUrls)
+        register(seed);
+    const liveTree = () => ({ listParents, origin: tree.origin });
+    const capFor = () => detailCapPerSection(maxPages, Math.max(1, listParents.size));
+    return {
+        get tree() {
+            return liveTree();
+        },
+        allowEnqueue(url) {
+            const pathname = pathnameOf(url);
+            const parent = listParentForPathname(pathname, listParents);
+            if (!parent)
+                return true;
+            return (detailCounts.get(parent) ?? 0) < capFor();
+        },
+        remember(url) {
+            register(url);
+            const classified = classifyCrawlUrl(url, liveTree());
+            if (classified.kind !== "detail" || !classified.section)
+                return;
+            detailCounts.set(classified.section, (detailCounts.get(classified.section) ?? 0) + 1);
+        },
+        isStructural(url) {
+            const kind = classifyCrawlUrl(url, liveTree()).kind;
+            return kind === "home" || kind === "root" || kind === "list";
+        },
+    };
+}

package/docs/agent-ready.md

@@ -25,8 +25,8 @@ robots.txt existence and sitemaps remain in the existing `robots-txt` and `sitem
 - 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: issues land in `findings[]` (`category: "infra"`) in `*-report.json`; the
-  Markdown report lists them under **Findings**
+- Report: issues land in `findings[]` (`category: "infra"`) in `*-report.json` with a
+  `fix` suggestion; the Markdown report lists them under **Findings** with a Fix line
 
 ## CLI
 

package/docs/analyze.md

@@ -69,7 +69,8 @@ Without `--output`, paths are derived from the input: `-raw.json` becomes
       "category": "infra",
       "scope": "origin",
       "title": "Missing Hsts",
-      "message": "Strict-Transport-Security header is missing on HTTPS."
+      "message": "Strict-Transport-Security header is missing on HTTPS.",
+      "fix": "Send `Strict-Transport-Security: max-age=31536000; includeSubDomains` on HTTPS responses (hosting or app headers)."
     }
   ]
 }
@@ -84,7 +85,8 @@ includes metadata so consumers can filter or regroup.
 | `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 |
+| `message` | What was found |
+| `fix` | Concrete remediation suggestion when available |
 | `template` | Present when `scope` is `template` |
 | `urls` / `count` | Affected pages when relevant |
 
@@ -103,7 +105,7 @@ Generated from the JSON. Structure:
 1. Header — generated time, Flightcheck version, flags, source path
 2. **At a glance** — page counts and finding totals
 3. **Stack / DNS / redirect** — factual context when available
-4. **Findings** — grouped by severity for reading order, with plain-language titles
+4. **Findings** — grouped by severity for reading order, with plain-language titles and a **Fix** line when available
 
 ## Notes
 

package/docs/crawler.md

@@ -34,7 +34,7 @@ Key flags:
 - `--errors-only` include only critical/error findings in the Markdown report
 - `--checks <ids>` comma-separated checks; default: all implemented checks (`crawl`, `security-headers`, `dns`, `robots-txt`, `sitemap`, `analyze`)
 - `--parallel` run independent checks in the same wave concurrently
-- `--max-pages <n>`
+- `--max-pages <n>` (default **100**) — hard crawl budget with smart URL selection (see below)
 - `--delay-ms <n>`
 - `--timeout-ms <n>`
 - `--concurrency <n>`
@@ -149,7 +149,20 @@ Additionally:
 
 - Only internal links are crawled. Links are discovered via `extractInternalLinks` and added to the queue; Crawlee's `enqueueLinks` is intentionally not used.
 - Sitemap URLs are added to the crawl queue by default so pages from `sitemap.xml` are visited even when they are not reachable via internal links.
-- `--max-pages` is the hard stop (`maxRequestsPerCrawl`). The crawl stops once this count is processed, even if unvisited links remain. Increase `--max-pages` to crawl the entire site.
+- `--max-pages` (default **100**) is the hard stop (`maxRequestsPerCrawl`). The crawl stops once this count is processed, even if unvisited links remain. Raise `--max-pages` (for example `1000` or higher) when you need broader coverage of a large site.
+
+### Smart page selection
+
+Large sitemaps often list thousands of archive detail URLs. Selection is based on **URL-tree shape**, not slug names (so `/stories`, `/nieuws`, or `/whatever` all work the same):
+
+1. Build a path tree from known URLs (sitemap seeds and later discoveries)
+2. Treat a path as a **list parent** when it has many direct children that are mostly **leaves** (no further subpages) — typical archive indexes
+3. Prefer **home**, other **structural** shallow pages, and those **list** indexes
+4. Under each list parent, take only a **round-robin sample** of leaf URLs until `--max-pages` is filled
+
+Seed order follows that ranking (FIFO). Structural links discovered from HTML are pushed to the front of the queue (`forefront`); leaf URLs under list parents are capped so one archive cannot flood the budget.
+
+Selection lives in `src/crawler/smartPageSelection.ts`.
 - Query parameters and hashes do not count toward URL identity.
 - Non-HTML responses are reported with `note`.
 - Links to files with a known non-HTML extension (such as `.pdf`, `.zip`, images, video, fonts) are not added to the queue, so Crawlee does not generate unnecessary retries and errors.

package/docs/index.md

@@ -15,6 +15,7 @@
 
 - Package releases: [CHANGELOG.md](../CHANGELOG.md)
 - Branch notes: [changelog/](./changelog/)
+  - [2026-10-28 — smart-max-pages](./changelog/2026-10-28--smart-max-pages.md)
   - [2026-10-28 — report-version-flags](./changelog/2026-10-28--report-version-flags.md)
   - [2026-10-27 — npm-public-package](./changelog/2026-10-27--npm-public-package.md)
   - [2026-10-27 — structured-report-json](./changelog/2026-10-27--structured-report-json.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eightmedia/flightcheck",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Pre-launch website audit: crawl SEO/a11y/security checks and emit structured JSON + Markdown reports.",
   "license": "GPL-3.0",
   "type": "module",