docs: surface runSitemapAudit for library users; default Schema skill to sitemap (1.7.1)

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 1.7.1 (2026-05-06)
+
+### Documentation
+- README's Programmatic Usage section now documents `runSitemapAudit` alongside `runAeoAudit`. Library users who called `runAeoAudit('https://example.com')` on the homepage missed per-page issues — duplicate singleton `@type`s, JSON parse errors, missing schema on individual templates — because those problems live on subpages. Calling out the scope distinction up front, with a concrete `crossCuttingIssues` / `affectedUrls` example, makes site-wide auditing the obvious choice when one is appropriate.
+- Schema mode in `skills/aeo/SKILL.md` now defaults to sitemap mode (`--sitemap --top-issues`) for site-wide schema requests, mirroring the same scope guidance for skill users.
+
 ## 1.7.0 (2026-04-30)
 
 ### Added

README.md

@@ -168,19 +168,41 @@ Exit code `0` for score >= 70, `1` for < 70 (CI-friendly). In sitemap mode the e
 
 ## Programmatic Usage
 
+The library exposes two audit entry points. **Use `runSitemapAudit` for site-wide checks** — `runAeoAudit` only fetches the URL you pass it, so per-page issues like duplicate `FAQPage` blocks, JSON parse errors, or missing schema on individual templates are invisible if you call it on the homepage of a multi-page site.
+
+### Single page
+
 ```ts
 import { runAeoAudit } from '@ainyc/aeo-audit'
 
-const report = await runAeoAudit('https://example.com', {
+const report = await runAeoAudit('https://example.com/specific-page', {
   includeGeo: false,        // Include geographic signals (default: false)
-  factors: null,             // Run all factors (or pass array of factor IDs)
+  factors: undefined,       // Run all factors (or pass array of factor IDs)
 })
 
 console.log(report.overallGrade) // 'A+'
 console.log(report.overallScore) // 98
 console.log(report.factors)      // Array of factor results with scores, findings, recommendations
 ```
 
+### Site-wide (sitemap)
+
+```ts
+import { runSitemapAudit } from '@ainyc/aeo-audit'
+
+const report = await runSitemapAudit('https://example.com', {
+  limit: 200,               // Max pages to audit (default 200, sorted by sitemap priority)
+  factors: ['schema-validity', 'structured-data'],  // Optional subset
+})
+
+console.log(report.aggregateGrade)   // 'B+'
+console.log(report.pagesAudited)     // 22
+console.log(report.crossCuttingIssues) // Per-factor rollup with affectedUrls for every recommendation
+console.log(report.prioritizedFixes)   // Top 5 fixes ranked by site-wide impact
+```
+
+Each entry in `crossCuttingIssues[].topIssues` carries a `recommendation` plus the exact `affectedUrls` so you can attribute each problem to specific pages — e.g. "FAQPage duplicate" pointing at every blog post that has it.
+
 TypeScript declaration files are included automatically.
 
 ## Claude Code / ClawHub Skill

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ainyc/aeo-audit",
-  "version": "1.7.0",
+  "version": "1.7.1",
   "description": "The most comprehensive open-source Answer Engine Optimization (AEO) audit tool. Scores websites across 14 ranking factors that determine AI citation.",
   "type": "module",
   "main": "./dist/index.js",

skills/aeo/SKILL.md

@@ -164,17 +164,29 @@ Rules:
 
 Use when the request is specifically about JSON-LD or schema quality.
 
-1. Run:
-   ```bash
-   npx @ainyc/aeo-audit@1 "<url>" [flags] --format json --factors structured-data,schema-completeness,schema-validity,entity-consistency
-   ```
-2. Report:
-   - Schema types found
-   - Property completeness by type
-   - Missing recommended properties
-   - **Validity errors** (duplicate singleton `@type`s, JSON parse errors, empty `<script>` blocks) — surface these prominently regardless of overall score; Google drops invalid blocks silently from rich results
-   - Entity consistency issues
-3. Provide corrected JSON-LD examples when useful.
+Validity issues like duplicate singleton `@type`s and JSON parse errors are **per page**, so a homepage-only audit misses every subpage. Default to sitemap mode for site-wide schema requests ("audit my schema", "are my FAQ blocks valid?"); use single-URL mode only when the user names one specific page.
+
+Site-wide (default):
+
+```bash
+npx @ainyc/aeo-audit@1 "<url>" --sitemap --top-issues --format json --factors structured-data,schema-completeness,schema-validity,entity-consistency
+```
+
+Single page:
+
+```bash
+npx @ainyc/aeo-audit@1 "<url>" --format json --factors structured-data,schema-completeness,schema-validity,entity-consistency
+```
+
+Report:
+- Schema types found
+- Property completeness by type
+- Missing recommended properties
+- **Validity errors** (duplicate singleton `@type`s, JSON parse errors, empty `<script>` blocks) — surface these prominently regardless of overall score; Google drops invalid blocks silently from rich results
+- Entity consistency issues
+- In sitemap mode: list every affected URL for each validity error so the user can locate per-page duplicates
+
+Provide corrected JSON-LD examples when useful.
 
 Checklist:
 - `LocalBusiness`: name, address, telephone, openingHours, priceRange, image, url, geo, areaServed, sameAs