aeoptimize 0.5.3 → 0.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. package/.claude-plugin/marketplace.json +5 -5
  2. package/.claude-plugin/plugin.json +4 -4
  3. package/CHANGELOG.md +35 -0
  4. package/CONTRIBUTING.md +37 -0
  5. package/README.md +86 -130
  6. package/ROADMAP.md +31 -0
  7. package/SECURITY.md +15 -0
  8. package/agents/aeo-ai-scorer.md +10 -39
  9. package/agents/aeo-analyzer.md +9 -55
  10. package/dist/cli/index.js +18 -18
  11. package/dist/cli/index.js.map +1 -1
  12. package/dist/core/ai-prompt.js +8 -6
  13. package/dist/core/ai-prompt.js.map +1 -1
  14. package/dist/core/generator.js +17 -47
  15. package/dist/core/generator.js.map +1 -1
  16. package/dist/core/merger.js +2 -2
  17. package/dist/core/merger.js.map +1 -1
  18. package/dist/core/rules.js +92 -154
  19. package/dist/core/rules.js.map +1 -1
  20. package/dist/core/scanner.js +2 -20
  21. package/dist/core/scanner.js.map +1 -1
  22. package/dist/plugins/next.js +2 -2
  23. package/dist/plugins/next.js.map +1 -1
  24. package/dist/plugins/vite.js +2 -2
  25. package/dist/plugins/vite.js.map +1 -1
  26. package/docs/methodology.md +78 -0
  27. package/docs/release-v0.6.md +66 -0
  28. package/examples/github-action-sample/.github/workflows/aeoptimize.yml +18 -0
  29. package/examples/github-action-sample/README.md +9 -0
  30. package/examples/github-action-sample/site/index.html +38 -0
  31. package/fixtures/v0.6/rule-corpus.ts +326 -0
  32. package/package.json +28 -13
  33. package/scripts/verify-release-candidate.sh +86 -0
  34. package/scripts/verify-release-v0.6.sh +180 -0
  35. package/skills/aeo-generate/SKILL.md +21 -39
  36. package/skills/aeo-scan/SKILL.md +17 -64
  37. package/skills/aeo-transform/SKILL.md +20 -72
package/skills/aeo-generate/SKILL.md CHANGED
@@ -1,53 +1,35 @@
1
1
  ---
2
2
  name: aeo-generate
3
- description: Use when creating llms.txt, JSON-LD structured data, or robots.txt AI crawler configuration for a website or project build output
3
+ description: Use when previewing optional llms.txt proposal files, candidate JSON-LD, or crawler-control suggestions for a website build
4
4
  ---
5
5
 
6
- # AEO Generate — AI Infrastructure Files
6
+ # AEO Generate — Optional Discovery Artifacts
7
7
 
8
- Generate AI infrastructure files from existing website content to make it discoverable by AI search engines.
9
-
10
- ## What Gets Generated
11
-
12
- | File | Purpose |
13
- |------|---------|
14
- | `llms.txt` | Machine-readable site summary for LLMs (llmstxt.org standard) |
15
- | `llms-full.txt` | Full content version for deep AI consumption |
16
- | `_aeo/generated-schemas.json` | JSON-LD schemas (Article, FAQPage, BreadcrumbList) |
17
- | robots.txt suggestions | AI crawler allow/deny rules (printed, not auto-applied) |
8
+ Generate reviewable candidate artifacts. These files do not guarantee crawling, indexing, search features, visibility, or citation.
18
9
 
19
10
  ## Workflow
20
11
 
21
- 1. **Identify build output.** Ask the user for the directory containing their built site (e.g., `dist/`, `out/`, `build/`). Check for common framework patterns:
22
- - Next.js: `.next/` or `out/`
23
- - Vite/Astro: `dist/`
24
- - Hugo/Jekyll: `public/`
12
+ 1. Identify an authorized static build directory.
13
+ 2. Preview without writing:
25
14
 
26
- 2. **Preview first.** Run:
15
+ ```bash
16
+ npx aeoptimize generate <directory> --dry-run
27
17
  ```
28
- npx aeoptimize generate <dir> --dry-run
29
- ```
30
- Show the user what will be generated and explain each file's purpose.
31
18
 
32
- 3. **Confirm and generate.** On approval:
33
- ```
34
- npx aeoptimize generate <dir>
35
- ```
36
-
37
- 4. **Review generated files.** Read each generated file and suggest manual refinements:
38
- - `llms.txt`: Verify site name, description, and page listing are accurate
39
- - JSON-LD: Check that generated schemas match the actual content
40
- - robots.txt: Explain each AI crawler and let user decide allow/deny
19
+ 3. Review every output:
20
+ - `llms.txt` and `llms-full.txt` are experiments based on a proposal.
21
+ - Candidate `Article` or `BreadcrumbList` JSON-LD must match visible content.
22
+ - Crawler rules have service-specific meanings; an allow rule is not an outcome guarantee.
23
+ 4. Write only after the user approves the exact directory:
41
24
 
42
- 5. **Integration guidance.** Explain how to deploy:
43
- - Place `llms.txt` at site root (alongside `robots.txt`)
44
- - Add `<link rel="llms-txt" href="/llms.txt">` to HTML `<head>`
45
- - Inject generated JSON-LD into page `<head>` sections
46
- - Merge robots.txt suggestions with existing rules
25
+ ```bash
26
+ npx aeoptimize generate <directory>
27
+ ```
47
28
 
48
- ## Important
29
+ ## Boundaries
49
30
 
50
- - Always preview with `--dry-run` before writing
51
- - Never overwrite existing files without user confirmation
52
- - Suggest running `/aeo-scan` first to understand current state
53
- - The robots.txt suggestions are printed only — never auto-modify robots.txt
31
+ - Never overwrite an existing artifact without confirmation and a recoverable copy.
32
+ - Never infer `FAQPage` from question headings.
33
+ - Never add `<link rel="llms-txt">` as if it were a standardized discovery mechanism.
34
+ - Never auto-apply `robots.txt` suggestions.
35
+ - Validate structured data against current primary documentation before deployment.
package/skills/aeo-scan/SKILL.md CHANGED
@@ -1,78 +1,31 @@
1
1
  ---
2
2
  name: aeo-scan
3
- description: Use when auditing a website or build output for AI search readiness, checking AI readability scores, or diagnosing why content isn't being cited by AI assistants like ChatGPT, Perplexity, or Google AI Overview
3
+ description: Use when auditing a website or build output for deterministic content-readiness regressions and evidence-bounded discovery checks
4
4
  ---
5
5
 
6
- # AEO Scan — AI Readability Audit
6
+ # AEO Scan — Content Readiness Audit
7
7
 
8
- Scan a website or build directory and produce an interactive AI readability report. Supports multi-AI scoring with gemini and copilot CLIs.
9
-
10
- ## Scoring Dimensions (0-100)
11
-
12
- | Dimension | Max | What it measures |
13
- |-----------|-----|------------------|
14
- | Structure | 25 | Heading hierarchy, paragraph length, FAQ presence, list usage |
15
- | Citability | 25 | Self-contained statements, data/stats, definitions, attribution |
16
- | Schema | 20 | JSON-LD presence, completeness, AI-relevant types |
17
- | AI Metadata | 15 | llms.txt, robots.txt AI config, meta description |
18
- | Content Density | 15 | Content vs boilerplate, keyword stuffing, uniqueness |
8
+ Run aeoptimize against a URL or build directory. The deterministic report is suitable for regression checks; optional Gemini, Copilot, or Claude reviews are experimental and do not predict ranking, indexing, rich results, visibility, or citation.
19
9
 
20
10
  ## Workflow
21
11
 
22
- 1. **Identify target.** Ask the user for a URL or directory path. If in a project with a build output (e.g., `dist/`, `out/`, `.next/`, `build/`), suggest scanning that.
23
-
24
- 2. **Detect AI CLIs.** Check which AI tools are available:
25
- ```
26
- which gemini && which copilot
27
- ```
28
- Report which are found. If both are available, offer multi-AI scoring.
29
-
30
- 3. **Run scan.** Choose based on available CLIs:
12
+ 1. Identify the URL, file, or build directory.
13
+ 2. Run the deterministic scan with machine-readable output:
31
14
 
32
- **If external AI CLIs available:**
33
- ```
34
- npx aeoptimize scan <target> --multi-ai --json
35
- ```
36
- This runs the rule engine + dispatches gemini/copilot for parallel scoring.
37
-
38
- **If no external CLIs:**
39
- ```
15
+ ```bash
40
16
  npx aeoptimize scan <target> --json
17
+ npx aeoptimize scan <directory> --dir --json
41
18
  ```
42
- Then use the `aeo-ai-scorer` agent to add Claude's AI-level analysis on top of the rule engine score.
43
-
44
- 4. **Present results.** Show:
45
- - **Consensus score** (rule engine + AI weighted average)
46
- - **Per-scorer breakdown** (Rule Engine, Claude, Gemini, Copilot — whichever are available)
47
- - Dimensions scoring below 60% of their max
48
- - All critical issues
49
- - **AI insights** — each AI's one-sentence summary of the biggest issue
50
-
51
- 5. **Discuss improvements.** For each weak dimension, explain:
52
- - Why it matters for AI search visibility
53
- - Concrete steps to improve
54
- - Expected score impact
55
- - Cross-reference insights from different AI scorers if they agree/disagree
56
-
57
- 6. **Deep analysis (optional).** If the user wants detailed per-page analysis, dispatch the `aeo-analyzer` agent with the page HTML and scan report. It provides issue-by-issue breakdown with before/after examples.
58
-
59
- 7. **Offer next steps:**
60
- - Score below 50? Suggest running `/aeo-transform` on the worst pages
61
- - Missing llms.txt or schema? Suggest `/aeo-generate`
62
- - Score above 80? Congratulate and suggest monitoring over time
63
-
64
- ## Multi-AI Scoring Methodology
65
19
 
66
- | Scenario | Weighting |
67
- |----------|-----------|
68
- | Rule engine + 2+ AIs | 50% rule engine + 50% AI average |
69
- | Rule engine + 1 AI | 60% rule engine + 40% AI |
70
- | Rule engine only | 100% rule engine |
20
+ 3. Report the deterministic score, methodology version, critical findings, and heuristic limitations.
21
+ 4. Use `--multi-ai` only when the user explicitly asks for a subjective review. Label the result an experimental blend and keep the deterministic score separate.
22
+ 5. Prioritize sourced quantitative claims, unintentional `noindex`, malformed or misleading structured data, and reproducible content regressions.
23
+ 6. Suggest `/aeo-generate` only for an optional artifact preview. State that `llms.txt` is an unscored proposal.
71
24
 
72
- ## Important
25
+ ## Boundaries
73
26
 
74
- - Always run the CLI with `--json` for machine-readable output
75
- - Present scores visually with context, not just numbers
76
- - Focus discussion on high-impact fixes first
77
- - If scanning a URL fails (CORS, timeout), suggest scanning the local build output instead
78
- - When using Claude as AI scorer (no external CLIs), dispatch the `aeo-ai-scorer` agent
27
+ - FAQ content and `llms.txt` have no score impact.
28
+ - A score increase is not evidence of a ranking or citation increase.
29
+ - Generated schema must match visible content and current feature documentation.
30
+ - If a URL scan fails, use an authorized local build instead of bypassing access controls.
31
+ - Always use `--json` when another tool will consume the result.
package/skills/aeo-transform/SKILL.md CHANGED
@@ -1,84 +1,32 @@
1
1
  ---
2
2
  name: aeo-transform
3
- description: Use when restructuring website content for better AI citation — splitting long paragraphs, adding FAQ schema, removing keyword stuffing, improving heading structure, or injecting structured data into HTML or Markdown files
3
+ description: Use when proposing evidence-bounded readability and structure edits without inventing content, ranking claims, or structured data
4
4
  ---
5
5
 
6
- # AEO Transform — AI-Friendly Content Restructuring
6
+ # AEO Transform — Evidence-Bounded Content Restructuring
7
7
 
8
- Transform SEO-optimized content into AI-search-ready format using language understanding. This skill uses your Claude subscription — no additional API costs.
9
-
10
- ## Transformation Strategies
11
-
12
- | Strategy | What it does | Impact |
13
- |----------|-------------|--------|
14
- | **Split paragraphs** | Break long paragraphs (>150 words) into self-contained statements | High |
15
- | **Extract FAQ** | Find implicit Q&A content and convert to explicit FAQ with schema | High |
16
- | **Remove keyword stuffing** | Replace repeated keywords with natural synonyms | High |
17
- | **Improve headings** | Rewrite vague headings as specific, question-format headings | Medium |
18
- | **Add structured data** | Inject JSON-LD based on content analysis | Medium |
19
- | **Fix dangling references** | Rewrite paragraphs starting with "This", "It", "They" to be self-contained | Medium |
8
+ Propose focused edits while preserving meaning, voice, provenance, and recoverability.
20
9
 
21
10
  ## Workflow
22
11
 
23
- 1. **Identify targets.** Ask the user which files to transform. If unsure, suggest running `/aeo-scan` first to find the lowest-scoring pages.
24
-
25
- 2. **Read and analyze.** For each file:
26
- - Read the full content
27
- - Run `npx aeoptimize scan <file> --json` to get the current score
28
- - Identify which strategies apply based on the issues found
29
-
30
- 3. **Transform incrementally.** Apply one strategy at a time:
31
- - Show the proposed change as a diff
32
- - Explain why this change improves AI readability
33
- - Wait for user approval before applying
34
- - Move to the next strategy
35
-
36
- 4. **Preserve voice.** Critical rules:
37
- - Never invent new content or add claims not in the original
38
- - Preserve the author's writing style and tone
39
- - Only restructure — do not rewrite meaning
40
- - Keep all existing data, quotes, and references intact
41
-
42
- 5. **Verify improvement.** After all transforms:
43
- - Re-run `npx aeoptimize scan <file> --json`
44
- - Show before/after score comparison
45
- - Highlight which dimensions improved
46
-
47
- ## Strategy Details
48
-
49
- ### Split Paragraphs
50
- For each paragraph over 150 words:
51
- - Identify distinct ideas within the paragraph
52
- - Split at natural boundaries (topic shifts, "Additionally", "However")
53
- - Ensure each new paragraph is self-contained (has its own subject, not just "It..." or "This...")
54
-
55
- ### Extract FAQ
56
- Look for patterns like:
57
- - Heading followed by a short answer paragraph
58
- - "What is X?" / "How does X work?" patterns in body text
59
- - Implicit questions answered in the content
60
-
61
- Convert to:
62
- - Explicit `<h3>` question headings
63
- - Concise answer paragraphs
64
- - FAQPage JSON-LD schema
12
+ 1. Read one authorized file and run the deterministic scan.
13
+ 2. Classify each finding as an official requirement, deterministic check, heuristic, or experiment.
14
+ 3. Show a focused diff before changing the file.
15
+ 4. Change only what improves readability, factual provenance, or a documented technical requirement.
16
+ 5. Rerun the same scan and report the reproducible output change separately from any external outcome.
65
17
 
66
- ### Remove Keyword Stuffing
67
- When a word appears >3% of content (excluding stop words):
68
- - Replace some occurrences with synonyms or related terms
69
- - Remove redundant mentions that don't add meaning
70
- - Ensure remaining usage feels natural
18
+ ## Allowed transformations
71
19
 
72
- ### Fix Dangling References
73
- For paragraphs starting with pronouns/conjunctions:
74
- - Replace "This feature" with "[Product name]'s feature"
75
- - Replace "It provides" with "[Subject] provides"
76
- - Replace "However," with a self-contained restatement
20
+ - Split a long paragraph where comprehension improves.
21
+ - Repair a genuinely confusing document outline; multiple H1 elements are not automatically wrong.
22
+ - Cite or remove unsupported quantitative claims.
23
+ - Reduce repetitive wording without changing meaning.
24
+ - Propose structured data only when it matches visible content and current documentation.
25
+ - Clarify genuine reader questions without auto-generating FAQ schema.
77
26
 
78
- ## Important
27
+ ## Boundaries
79
28
 
80
- - Always show diffs before applying changes
81
- - Transform one file at a time, one strategy at a time
82
- - Score comparison before/after is mandatory
83
- - This skill is interactive — never batch-transform without review
84
- - Supports `.html` and `.md` files
29
+ - Never invent facts, statistics, sources, quotes, authors, dates, or benefits.
30
+ - Never describe a score increase as evidence of ranking, indexing, rich results, or citation.
31
+ - Never batch-transform files without explicit scope.
32
+ - Preserve a reviewable diff and the user's original voice.